init: 智慧农业大数据可视化控制中心 v0.1.0（Electron + React 19 + TS 重写版）

.codebuddy/memory/2026-08-23.md

@@ -0,0 +1,180 @@
+# 2026-08-23
+
+## SmartAgriCenter：用 Electron + React + TypeScript 重写「智慧农业大数据可视化控制中心」
+
+用户对之前 WinForm + WebView2 版（`SmartAgriDataCenter`）效果不满意，改用 Electron 技术栈重写，新项目位于 `c:/Users/范先生/CodeBuddy/DataViewCenter/SmartAgriCenter`。
+
+**技术栈**：Electron + React 19 + TypeScript + Vite 7 + electron-vite@5 + zustand。依赖固定为 `electron-vite@5 vite@7 @vitejs/plugin-react@5`（避免最新版 vite8 与 electron-vite peer 冲突）。
+
+**架构**：
+- 主进程 `src/main/`：`index.ts`（无边框主窗口 + 单实例锁）、`ipc.ts`（全部 IPC + 未保存关闭守卫）、`screens.ts`（屏幕窗口管理器，每个显示器一个全屏 BrowserWindow，`before-input-event` 支持数字键 1-9 切页、Esc 退出全屏）。
+- 预加载 `src/preload/`：contextBridge 暴露 `window.api`（win/screens/project/key/syncProject/setDirty/beep/createShortcut/confirm）。
+- 渲染层 `src/renderer/`：zustand store 管理 pages/屏幕/视图；三视图（编辑/发布/配置）；Webview 用 `document.createElement('webview')` 封装（webviewTag: true），编辑画布与发布预览共用；示例大屏 `public/sample-screen.html` 按 `no`/`title` 参数显示 4 种主题动态图表。
+
+**关键经验**：
+- 本机 PowerShell 传参含中文路径（`c:/Users/范先生/...`）会乱码导致 cd 失败；命令一律用相对路径。npm 安装时 `node_modules/electron` 二进制可能因网络下载失败缺失（表现为 cli.js 报 "Electron failed to install correctly"），需 `node node_modules/electron/install.js` 手动下载；网络受限时先 `$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"`。
+- TypeScript 新版移除了 `baseUrl`，paths 需写相对形式 `"./src/..."`。
+- electron-vite 默认输出 CJS，主进程可用 `__dirname`。
+- 验证渲染层是否正常：`Start-Process electron.cmd -ArgumentList ".", "--remote-debugging-port=9223"` 后用 CDP 的 `Runtime.evaluate` 检查 `#root` children / `window.api`。
+
+**运行**：`cd SmartAgriCenter && npm run dev`（开发）或 `npm run build && npm start`（生产）。已通过 typecheck + build + 启动验证（React 挂载、4 页面、画布 webview 正常）。
+
+## 2026-08-23 下午：UI/发布功能增强（需求 2/3/4 全部落地）
+
+针对新需求完成以下改造（均通过 typecheck + build + dev 启动验证）：
+
+1. **编辑界面**：Ribbon 中「项目」菜单组移到「页面」组之前（`Ribbon.tsx` 调序）。左侧页面列表改为预览图卡片（`PageList.tsx` 重写）：新增 `pc-thumb` 预览区（无预览显示占位）、hover 出现「前插 ⏫ / 截图 📷」按钮、卡片底部「＋ 插入新页」按钮。
+2. **预览图机制**：页面 JSON 新增 `PagePreview` 字段（Base64 图片），`utils.ts` 的 `pagesToJson`/`jsonToPages` 已读写；`types.ts` 的 `Page` 增加 `preview`。主进程新增 `page:snapshot` IPC（`ipc.ts`）：隐藏 BrowserWindow 加载 URL → 等 1.6s → `capturePage()` → `toDataURL()`。store 的 `capturePreview(index?)`/`insertBefore(index?)` 支持指定索引。
+3. **发布逻辑**：
+   - 多屏发布：沿用 `screens.ts` 的 `publishScreen`（全屏 BrowserWindow），支持数字键 1-9 切页、**Esc 关闭、F5 刷新**（新增 `before-input-event` 快捷键处理）。
+   - **单屏轮播**（`screens.ts` `startCarousel/stopCarousel`）：在目标屏幕为每页创建一个全屏窗口叠放（`show: false`），键盘 ↑/↓ 循环切换、数字键直达、Esc 停止并销毁、F5 刷新当前页；轮播状态存 `carousels` Map，`listScreens` 中显示「单屏轮播（N 页 · 第 M 页）」。
+   - `publishActions.ts` 新增 `startCarouselOnScreen`（取 `display=true` 页面轮播）/`stopCarouselOnScreen`；`PublishView.tsx` 增加「🎠 单屏轮播」/「⏹ 停止轮播」按钮。
+   - preload `index.ts`/`index.d.ts` 新增 `carousel.start/stop` 与 `page.snapshot` API；`PageFile` 增加 `PagePreview`。
+4. **临时文件**：验证时生成的 `dev.log`/`dev-err.log` 受环境 SafeDelete 保护未能删除（无害，位于 SmartAgriCenter 根目录）。
+5. **环境注意**：后台启动 dev 用 `Start-Process npm.cmd -ArgumentList 'run','dev'`（npm 直接 Start-Process 会报 "not a valid Win32 application"）；PowerShell 中文路径需用 `$env:USERPROFILE` 拼接。
+
+## 2026-08-23 修复：编辑页 webview 预览未撑满容器
+
+- 问题：`WebFrame.tsx` 动态创建的 `<webview>` 元素未设置任何 class，而 CSS 已有 `.webframe-webview { width:100%; height:100%; display:block; border:none }` 但从未被使用，导致预览画面尺寸异常、不填满画布。
+- 修复：创建 webview 时加 `wv.setAttribute('class', 'webframe-webview')`。
+- 注意：`WebFrame` 的 `useEffect` 空依赖创建 webview，HMR 不会重建已存在的 webview，改完需重启 dev 生效。
+
+## 2026-08-23 编辑页 UI 功能调整（需求一批）
+
+1. **页面属性**：PageUrl 改为 textarea（`.url-area`，rows=2 多行）；PageParams textarea 加 `maxLength={255}` 并显示计数 "已输入 N / 255"。
+2. **页面列表卡片**：新增底部操作按钮组 `.pc-actions`（上移⬆/下移⬇/复制📑/删除🗑/截图📷），样式参考半透明深色截图按钮，**仅 `.page-card.active` 时显示**（CSS `display:none`→`flex`）；缩略图右上角 hover 只保留"前插⏫"；底部按钮文案改为"＋ 新建页面"。
+3. **按钮调整**：Ribbon「项目」组去掉"重置项目"，新增"🔀 页面重置"→ `store.resetOrder()`：按列表顺序重排 `id='P-001'…'P-NNN'`、`screen=i+1`、`ctrl=i+1`。"空白页"按钮与 `store.initBlank` 一并删除。
+4. **页面按钮组排序**：新建页面 → 插入页面（原"前插页面"）→ 复制页面 → 删除页面 → 上移 → 下移 → 缩略图（原"截图预览"）。
+5. store 接口移除 `resetProject`/`initBlank`（`defaultPages` 仍作初始数据保留）。
+
+## 2026-08-23 图标扁平化 + 按钮布局调整
+
+1. 新建 `src/renderer/src/components/icons.tsx`：Feather 风格 SVG 扁平图标组件（`IconInsert/IconUp/IconDown/IconCopy/IconTrash/IconCamera`），stroke=currentColor，size 默认 13。
+2. 页面列表卡片：缩略图右上角 hover「前插⏫」按钮**移除**，全部操作按钮（前插、上移、下移、复制、删除、截图共 6 个）统一放底部 `.pc-actions`，图标改用 SVG 扁平图标；`.pc-thumb-actions` 相关 CSS 已删除。
+3. Ribbon 顶部紧凑：`.ribbon-body` 高度 84→68px、padding 8/14→5/10px、gap 6→4px；`.ribbon-group` gap 4→2px、padding 0 10→0 6px；`.ribbon-btn` min-width 64→52、高 64→50、gap 4→2、font-size 11→10.5px；`.rb-icon` 30→22px、font 17→13px。
+
+## 2026-08-23 去掉「发布」Tab，发布功能移植编辑 Tab
+
+- **删除** `views/PublishView.tsx` 及 global.css 中发布视图样式块（`.publish-view/.pub-*/`.screen-grid/.scard/.publish-right/.preview-*`）。
+- `types.ts` `ViewMode` 由 `'edit' | 'publish' | 'config'` → `'edit' | 'config'`；`App.tsx` 移除 PublishView 分支与 import；`StatusBar.tsx` 视图名简化。
+- `Ribbon.tsx` 重构：`TAB_ICON/TAB_NAME` 仅 edit/config；编辑 Tab 新增「发布」组（在项目/页面组之后），共 5 个按钮：
+  - 🖥️ 多屏发布 `publishAll`
+  - 📤 发布当前页 `publishCurrentToScreen(curPage.screen)`（disabled=无当前页）
+  - 🎠 单屏轮播 `startCarouselOnScreen(curPage.screen)`（基于当前页所属屏幕轮播所有 display 页面）
+  - ⏹️ 停止轮播 `stopCarouselOnScreen(curPage.screen)`（disabled=该屏未轮播，依据 screens 状态 /轮播/ 匹配）
+  - 🚪 关闭全部 `closeAllScreenOutput`
+  - `RibbonItem` 增加可选 `title` 字段（提示当前屏号/快捷键说明）。
+- 移除发布 Tab 后快捷键逻辑不受影响（主窗口数字键切页仍走 App.tsx）。
+
+## 2026-08-23 二次修复：仅设 class 仍只占顶部 100px
+
+- 现象：加上 class 后，webview 仍只占画布顶部约 100px（看起来是内容 intrinsic 高度），下方 620px 空白。
+- 根因：Electron `<webview>` 是 inline-flex 替换元素，普通 `height: 100%` 在某些情况下会被内容撑开。需配合父级 flex 拉伸 + inline style 兜底。
+- 修复（三重保险）：
+  1. `WebFrame.tsx` 创建 webview 时加 `style.display='flex'; style.width='100%'; style.height='100%'`。
+  2. `.canvas-stage` 加 `display: flex`。
+  3. `.webframe` 加 `flex: 1 1 auto; min-width: 0; min-height: 0`（用 flex 拉伸代替纯 height: 100%）。
+
+## 2026-08-23 配置页面重构为左右结构 + 7 大菜单（项目信息/遥控设置/快捷方式/发布设置/设备测试/关于）
+
+**布局**：`ConfigView.tsx` 改为 `.config-shell` 左右结构（左侧 `.config-menu` 菜单栏 6 项 + 右侧 `.config-area`），面板组件在 `src/renderer/src/components/config/` 下。
+
+**新增主进程模块**：
+- `settings.ts`：配置持久化到 userData/settings.json（projectName/projectVersion/jsonPassword/keyThreshold/keyLockKey/publish{mode,screenIndex,alsoMain,intervalSec}），IPC `settings:get/set`。
+- `crypto.ts`：AES-256-GCM（key=SHA256(pwd) + 随机 IV），密文前缀 `enc:v1:`，只加密页面 `PageUrl`/`PageParams`；密码错误 decrypt 返回 null。
+- `project.ts`：`readProjectFile/writeProjectFile`（带密码解密/加密，错误码 '密码错误'）、`pagesToSync`、`setUrlBase/buildPageUrl`。
+- `shortcuts.ts`：`createDesktopShortcut(kind:'app'|'edit'|'publish', path)` + `parseArgv`（--project/--mode）+ `chooseProjectFile`。快捷方式参数 `"appDir" --project "path" --mode edit|publish`。
+- `loader.ts`：`setPendingLoad/consumePendingLoad/pushLoad`，渲染层未就绪时暂存，`app:consumeLoad` invoke 兜底 + `app:loadProject` 实时事件（second-instance 也走 handleLaunch）。
+- `main/index.ts`：`handleLaunch` 读取项目（settings.jsonPassword 解密）→ 推给渲染层；`session.setPermissionRequestHandler` 放行 media（麦克风测试）。
+- 工程 IPC 带密码：`project:saveAs/save({data,password})`、`project:open(password?)`、`project:openAt({path,password})`。
+
+**快捷键阈值/锁定（screens.ts）**：`setKeyLock/isKeyLocked` 全局锁定；`makeKeyHandler` 统一处理 屏幕窗口/轮播/publishMain：Esc 立即退出、F5 刷新、锁定键（默认 F9）切换识别、数字/方向键需**长按超过 keyThreshold 才触发**（auto-repeat 不刷新时间戳，避免网页快速输入数字误触切屏）。轮播新增 intervalSec 自动切换定时器。
+
+**renderer**：
+- `store.ts`：新增 `settings` 状态 + `loadSettings/updateSettings/loadProject`；save/saveAs/open 全部带密码（open 密码错误时 `passwordState.askPassword()` 弹输入框重试，成功后记忆到设置）；新增 `passwordState.ts` + `components/PasswordModal.tsx`（App.tsx 挂载）。
+- `publishActions.ts`：新增 `applyPublishDefaults()`（按发布设置 multi/single/main 发布，single 支持 intervalSec）。
+- `App.tsx`：启动 loadSettings + `app:consumeLoad`/`onLoadProject` 加载快捷方式项目，mode==='publish' 自动 applyPublishDefaults。
+- 面板：ProjectInfo（名称/版本/密码+显示切换）、RemoteControl（遥控器模拟器 rc-remote 数字键/↑↓/Esc/F5/🔒、阈值滑杆、锁定键下拉、测试区 rc-test、快捷键速查表）、ShortcutPanel（3 卡片）、PublishSettings（radio+屏幕+间隔+alsoMain）、DeviceTest（键盘回显/WebAudio 提示音+音阶+音量/麦克风电平条 getMediaStream/屏幕列表+probe）、AboutPanel（hero+运行环境+编辑帮助+发布帮助，AppInfo 走 `app:info`）。
+- types.ts 增加 AppSettings/PublishDefaults/LoadPayload/AppInfo；preload d.ts 同步。
+
+**踩坑**：主窗口数字键切页仍在 App.tsx（renderer keydown）；大屏窗口数字键切页走主进程 keyHandler（长按阈值）。密码输入必须用自定义 Modal（Electron sandbox 下 window.prompt 不可用）。
+
+## 2026-08-23 编辑界面 4 项改动
+
+1. **打开/另存为记住最后文件夹**：AppSettings 新增 `lastDir`，`ipc.ts` 的 `project:open`（defaultPath=lastDir）与 `project:saveAs`（join(lastDir, projectName+'.json')）选择后通过 `rememberDir` 写回 settings.json。
+2. **发布按钮组顺序**：预览本页 → 单屏发布 → 多屏发布 → 停止轮播 → 关闭所有 → 检测屏幕（Ribbon.tsx pubItems 调整）。
+3. **单屏发布弹窗新增轮播选项**：ScreenSelectModal 增加 `showCarousel` prop，勾选「自动轮播」显示间隔输入（默认取 settings.publish.intervalSec），onConfirm 签名改为 `(index, {carousel, intervalSec})`；Ribbon 单屏发布传 `startCarouselOnScreen(i, carousel ? intervalSec : 0)`，不勾选则固定第一页（intervalSec=0 手动切换）。
+4. **页面重置按钮改名「页面重排」**（Ribbon resetorder label）。
+
+新增样式：.m-carousel/.m-interval（弹窗内轮播选项，global.css modal 区）。
+
+## 2026-08-23 发布按钮组大改造（弹窗选屏 + 检测屏幕 + 编辑器屏幕全屏）
+
+**发布组 6 按钮**：多屏发布🖥️ / 预览本页👁️ / 单屏发布🎠 / 停止轮播⏹️ / 关闭所有🏁 / 检测屏幕📡。全部通过弹窗交互：
+- **预览本页**：弹窗选屏 → `publishCurrentToScreen(selected)` 全屏播放当前页（Esc/F5/数字键）。
+- **单屏发布**：弹窗选屏 → `startCarouselOnScreen(selected)` 轮播所有 display 页（↑/↓/数字键/Esc）。
+- **多屏发布**：`MultiPublishModal` 预览各屏布局卡片（编号/分辨率/主显示器 + 分配到该屏的页面 chip）+ CheckBox「同时在本机编辑器屏幕上全屏显示页面（屏 X）」，确定后 `publishAll(alsoMain)`。
+- **关闭所有**：`closeAllScreenOutput`（closeAll 已含 restoreMain + closeProbe）。
+- **检测屏幕**：`DetectModal` 显示屏幕列表，同时 `probeScreens()` 在每块屏显示黑底白字「屏幕 N + 分辨率 + 主显示器」标签 6 秒。
+
+**主进程 screens.ts 新增**：
+- `setMainWindow/mainScreenIndex/isMainPlaying/publishMain/restoreMain`：编辑器主窗口用 **WebContentsView 覆盖**实现全屏播放（不破坏编辑器 store 状态，退出即移除 view），`before-input-event` 支持 Esc 退出/F5 刷新/数字键 1-9 按 ctrl 切页。
+- `probeScreens/closeProbe`：data URL 黑底白字标签窗口，6 秒自动销毁。
+- `closeAllScreens` 增加 `restoreMain()` 与 `closeProbe()`。
+- IPC 新增 `screens:mainIndex`、`screen:publishMain`、`screen:restoreMain`、`screens:probe`；`main/index.ts` 窗口创建后 `setMainWindow(mainWindow)`、closed 置 null。
+- preload `index.ts`/`index.d.ts`：`screens` 增加 `mainIndex/publishMain/restoreMain/probe`。
+
+**renderer**：
+- `publishActions.ts`：`publishAll(alsoMain)`、`detectScreens()`；`publishCurrentToScreen`/`startCarouselOnScreen` 保留为弹窗确认回调。
+- 新组件 `components/Modal.tsx`（通用弹窗）+ `components/PublishModals.tsx`（`ScreenSelectModal`/`MultiPublishModal`/`DetectModal`）。
+- `Ribbon.tsx`：`pubModal` useState 控制四类弹窗；按钮 action 打开弹窗。
+- global.css 追加 `.modal-overlay/.modal/.modal-head/.modal-body/.modal-foot/.m-screen-row/.m-scard/.m-check` 等弹窗样式。
+
+## 2026-08-23 系统崩溃重启 + 存档快照
+
+- 上午系统崩溃，重启后重新拉起客户端：`cd SmartAgriCenter && Start-Process npm.cmd -ArgumentList 'run','dev' -RedirectStandardOutput 'dev.log' -RedirectStandardError 'dev-err.log' -WindowStyle Hidden`（仍必须用 npm.cmd，npm 直接 Start-Process 报 "not a valid Win32 application"）。
+- 验证：vite dev server 5173 HTTP 200；Electron 主窗口标题「智慧农业大数据可视化控制中心」，4 个 electron 进程。
+- **当前完成度**：项目需求 1-4 及指令清单 1-5 条已全部落地并通过 typecheck + build + dev 启动验证。核心模块：编辑界面（预览图卡片页面列表 + Ribbon + 画布 webview）、发布（预览本页/单屏发布轮播/多屏发布/关闭所有/检测屏幕，全弹窗交互，WebContentsView 主屏全屏）、配置页 6 菜单（项目信息/遥控设置/快捷方式/发布设置/设备测试/关于）、AES 密码加密 JSON、快捷方式三件套、发布默认值。
+- **后续候选开发点**（未做，供下次继续）：(1) 页面列表预览图实际截图流程实测（page:snapshot 依赖 URL 可加载）；(2) 遥控器模拟界面视觉美化；(3) 打包分发（electron-builder 等）；(4) 项目 JSON 的导入/导出（项目需求编辑 Tab 提到）。
+
+## 2026-08-23 版本管理 + 标题栏版本号 + 绿色版打包准备
+
+- **版本管理**：版本号单一来源 = `package.json` 的 `version`（当前 0.1.0），主进程用 `app.getVersion()` 读取，渲染层经 `window.api.app.info().appVersion` 获取。
+- **标题栏显示版本号**：
+  - `TitleBar.tsx`：useEffect 拉 `app.info()`，标题右侧新增 `<span className="tb-ver">系统版本号 v{appVersion}</span>`；global.css 加 `.titlebar .tb-ver` 样式。
+  - `main/index.ts`：窗口 `title` 改为 `智慧农业大数据可视化控制中心 v${app.getVersion()}`；因页面 `<title>` 会覆盖构造标题，加 `webContents.on('did-finish-load')` 里 `setTitle` 兜底（任务栏/Alt+Tab 显示 v0.1.0）。
+- **绿色版打包配置（已就绪，未执行）**：新建 `electron-builder.yml`（appId com.bbit.smartagri，productName 智慧农业大数据可视化控制中心，`files: [out/**, package.json]`，asar:true，win target `zip`（x64，解压即用绿色版），electronDownload mirror npmmirror）；`package.json` 新增 scripts：`pack`（electron-builder --dir 出 win-unpacked 目录）、`dist`（打 zip 包，输出 release/）。**注意：electron-builder 尚未安装，需 `npm i -D electron-builder` 后才能执行打包；用户明确说「打包」才执行。**
+- **踩坑实测**：`electron-vite dev` 修改 `src/main` 后**不会**自动重建/重启 electron（renderer 走 HMR 正常，main 不行）——需手动杀 dev 进程组（npm-cli→electron-vite→electron）后重启；仅改 renderer 无需重启。
+- 验证：重启后窗口标题「智慧农业大数据可视化控制中心 v0.1.0」，typecheck 通过、无 lint/运行错误。
+
+## 2026-08-23 绿色版打包完成（用户明确指示后执行）
+
+- 安装 `electron-builder@26.15.3`（`npm i -D electron-builder --registry=https://registry.npmmirror.com`，270 包 12s）。
+- 执行 `npm run dist`（electron-vite build + electron-builder）成功：
+  - 产物：`release\智慧农业大数据可视化控制中心-0.1.0-win.zip`（139.7MB，绿色免安装压缩包）+ `release\win-unpacked\`（绿色目录，exe 224.6MB）。
+  - 打包参数：win32 x64 / electron 43.4.1 / asar / 默认 Electron 图标（**未配置应用图标**，如需要后续加 build/icon.ico）。
+  - 二进制镜像：打包前设 `$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"`，electron 本体走 yml 里 electronDownload.mirror=npmmirror。
+- 验证：win-unpacked 的 exe 独立启动成功，窗口标题「智慧农业大数据可视化控制中心 v0.1.0」；zip 解压测试通过（含 exe）。验证后已关闭。
+- 经验：
+  - **PowerShell 传参含中文路径会乱码**（再现）——用 `Get-ChildItem 'release\*.zip' | Select -First 1` 通配符定位再操作，避免直接写中文文件名。
+  - 包名「智慧农业大数据可视化控制中心」的进程名即 exe 名（非 electron），验证用 `Get-Process | Where MainWindowTitle -like '*智慧农业*'` 或 tasklist 匹配。
+  - `electron-vite dev` 启动 electron 偶尔延迟（日志已 "starting electron app" 但进程 10 秒后才出现），查询需多等并重试；`tasklist | Select-String electron` 比 Get-Process 更稳。
+  - SafeDelete 会拦截 release 目录下的批量 `Remove-Item -Recurse`，临时目录用 `cmd /c "rd /s /q <dir>"` 清理。
+- dev 开发环境已恢复运行（主窗口 v0.1.0，vite 5173 HTTP 200）。
+
+## 2026-08-23 更换应用图标（用户提供的 ico）
+
+- 源图标：`C:\Program Files\Honor\PCManager\qspublic\Documents\LocalAppCenter\Icons\localc04dba21984d49682a967afd00ed0152.ico`（仅 64x64 单帧/32bpp）。
+- **坑**：electron-builder 要求 `win.icon` ≥ 256x256，64x64 直接报 `Icon must be at least 256x256 pixels`。
+- 解决：PowerShell + System.Drawing 把 64x64 按 HighQualityBicubic 放大生成 16/24/32/48/64/128/256 共 7 帧的 `build/icon.ico`（PNG 帧编码 + 手写 ICONDIR 头）。脚本已用完删除（用 `cmd /c del`，SafeDelete 会拦 Remove-Item）。
+- 改动：`electron-builder.yml` 加 `win.icon: build/icon.ico`，files 加 `build/icon.ico`（打进 asar）；`main/index.ts` BrowserWindow 加 `icon: join(app.getAppPath(), 'build/icon.ico')`（dev 与打包后任务栏一致）。
+- 重新 `npm run dist` 成功，zip 已更新（10:52）；`[System.Drawing.Icon]::ExtractAssociatedIcon(exe)` 验证 exe 图标 32x32 正常提取；打包日志不再有 "default Electron icon is used"。
+- dev 已重启，主窗口 v0.1.0 无错误。图标源文件保留在 Program Files（勿删）；如需换图，提供 ≥256x256 的 ico 直接替换 `build/icon.ico` 再打包。
+
+## 2026-08-23 重写「项目需求」文档
+
+- 根目录 `项目需求`（无扩展名，原 WinForm 版 v1.0 需求）重写为 **v2.0**，反映 Electron 重写版当前实现阶段。
+- 结构：概述/技术架构/界面布局/功能需求（编辑·发布·配置）/业务流程/数据与安全/版本与分发/非功能需求/待办规划/需求来源对照。已实现 ✅、规划 ⏳ 标注。
+- 核对确认：配置菜单 6 项（info/remote/shortcut/publish/device/about，`configMenus.ts`）、发布 6 按钮顺序与指令清单一致、快捷键体系（1-9 长按阈值/↑↓/Esc/F5/锁定键）、AES-256-GCM 加密、settings.json 字段（lastDir 等）、Page 字段 9 项（含 PagePreview）。
+- **未实现（写入文档规划）**：项目导入/导出、代码视图/页面视图切换、遥控器硬件对接、帮助文档入口。
+- 交付：根目录 `项目需求` 文件已整体覆盖为新版；`指令清单` 未改动（其需求已全部实现，作为历史保留）。

.codebuddy/memory/MEMORY.md

@@ -0,0 +1,46 @@
+# MEMORY.md — SmartAgriCenter 智慧农业大数据可视化控制中心
+
+> 维护说明：本文件为跨会话长期记忆，记录项目稳定事实与约定。每日详细变更见 `YYYY-MM-DD.md`。
+
+## 项目定位
+- Electron + React 19 + TypeScript + Vite 7 + electron-vite@5 + zustand 重写版（替代旧 WinForm 版 SmartAgriDataCenter）。
+- 角色：软件本身只是**编辑器/调度器/发布器**，大屏业务内容是 HTML 网页，不做图表绘制。
+- 工作区：`c:/Users/范先生/CodeBuddy/DataViewCenter`，项目在 `SmartAgriCenter/`。原型参考在 `prototype/`（index.html、sample-screen.html）。
+
+## 依赖与运行（重要！）
+- 依赖固定 `electron-vite@5 vite@7 @vitejs/plugin-react@5`（避免 vite8 与 electron-vite peer 冲突）；Electron ^43。
+- 命令：`npm run dev` / `npm run build` / `npm start`（preview）/ `npm run typecheck`。
+- **中文路径 PowerShell 坑**：参数含中文路径（`c:/Users/范先生/...`）会乱码导致 cd 失败，命令一律用相对路径。
+- 后台启动 dev：`cd SmartAgriCenter; Start-Process npm.cmd -ArgumentList 'run','dev' -RedirectStandardOutput 'dev.log' -RedirectStandardError 'dev-err.log'`（必须 npm.cmd）。
+- Electron 二进制缺失时：先 `$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"` 再 `node node_modules/electron/install.js`。
+- dev.log / dev-err.log 留在 SmartAgriCenter 根目录，受 SafeDelete 保护，无害。
+
+## 架构要点
+- 三进程：`src/main/`（index.ts 无边框主窗+单实例锁；ipc.ts 全部 IPC+未保存关闭守卫；screens.ts 屏幕窗口/轮播/WebContentsView 主屏全屏/probe；settings.ts 配置持久化 userData/settings.json；crypto.ts AES-256-GCM 密码加密页面 URL/参数；project.ts；shortcuts.ts；loader.ts）。
+- preload：`window.api`（win/screens/project/key/syncProject/setDirty/beep/createShortcut/confirm/carousel/page.snapshot/settings）。
+- renderer：zustand store（pages/屏幕/视图/settings）；视图仅 `'edit' | 'config'`（发布 Tab 已并入编辑 Tab Ribbon）；Webview 用 `document.createElement('webview')` 封装。
+- 页面 JSON 字段含 `PagePreview`（Base64 截图），项目文件存 `.json`。
+
+## 关键 UI/交互约定
+- Ribbon 编辑 Tab 组序：项目 → 页面 → 发布（发布 6 按钮：预览本页👁️/单屏发布🎠/多屏发布🖥️/停止轮播⏹️/关闭所有🏁/检测屏幕📡，全部走弹窗）。
+- 页面列表卡片：预览图 + 底部操作组（前插/上移/下移/复制/删除/截图，SVG 扁平图标，仅 active 显示）。
+- 快捷键：大屏窗口/轮播数字键 1-9 需**长按超过 keyThreshold**（防网页内输入数字误触），Esc 退出、F5 刷新、锁定键（默认 F9）全局开关。
+- 发布设置可配 multi/single/main 三种默认模式，single 支持 intervalSec 轮播。
+
+## 验证方法
+- 渲染层 CDP：`Start-Process electron.cmd -ArgumentList ".", "--remote-debugging-port=9223"` 后 `Runtime.evaluate` 检查 `#root` children / `window.api`。
+- 改完 WebFrame 相关代码需重启 dev（HMR 不重建已存在 webview）。
+- **electron-vite dev 修改 src/main/preload 不会自动重启 electron**，需手动杀掉 dev 进程组（npm-cli→electron-vite→electron）再重新启动；仅 renderer 改动走 HMR 无需重启。
+
+## 版本号与打包（2026-08-23 新增）
+- 版本号单一来源 = `package.json version`（当前 0.1.0）；主进程 `app.getVersion()`；标题栏显示「系统版本号 vX.Y.Z」；任务栏标题由 `did-finish-load` 时 `setTitle` 兜底（页面 `<title>` 会覆盖构造标题）。
+- 项目需求文档：根目录 `项目需求`（无扩展名）2026-08-23 重写为 v2.0（Electron 重写版当前阶段，✅/⏳ 标注）；根目录 `指令清单` 为历史补充需求清单（需求已全部实现）。另有 UI 速览图 `SmartAgriCenter/docs/ui-screenshots/`（若有）。
+- 已实现功能全景（v0.1.0）：Ribbon 三组（项目/页面/发布）、发布 6 按钮（预览本页/单屏发布[可轮播]/多屏发布[alsoMain]/停止轮播/关闭所有/检测屏幕）、配置 6 菜单（项目信息/遥控设置[阈值+锁定键]/快捷方式×3/发布设置/设备测试[键/音/麦/屏]/关于）、快捷键（1-9 长按>阈值、↑↓、Esc、F5、锁定键）、AES-256-GCM 密码加密、标题栏版本号（package.json 单一来源）。
+- **未实现/规划**：项目导入/导出、代码视图/页面视图切换、遥控器硬件对接、帮助文档入口。
+- 绿色版打包已完成（2026-08-23，electron-builder@26.15.3 已装）：`npm run dist` → `release\智慧农业大数据可视化控制中心-0.1.0-win.zip`（绿色免安装）+ `release\win-unpacked\`。打包前设 `$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"`。应用图标未配置（默认 Electron 图标），需要时加 build/icon.ico。
+
+## 待办/候选开发点（截至 2026-08-23）
+1. 页面预览图实际截图流程实测（page:snapshot 依赖 URL 可加载）。
+2. 遥控器模拟界面视觉美化。
+3. 打包分发（electron-builder 等）。
+4. 项目 JSON 导入/导出。