From b11bea196290774ad6932c41f1ccebdac8a46bd3 Mon Sep 17 00:00:00 2001 From: fanhongcai Date: Sun, 23 Aug 2026 11:26:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B9=E7=9B=AE=E9=9C=80=E6=B1=82?= =?UTF-8?q?=E5=8D=87=E7=BA=A7=20v3.0=20+=20=E6=96=B0=E5=A2=9E=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E8=BF=9B=E5=BA=A6=E5=AD=98=E6=A1=A3=EF=BC=88=E8=B7=A8?= =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E6=81=A2=E5=A4=8D=E5=85=A5=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codebuddy/memory/2026-08-23.md | 7 ++ .codebuddy/memory/MEMORY.md | 12 +-- 开发进度存档 | 151 ++++++++++++++++++++++++++++++++ 项目需求 | 39 ++++++--- 4 files changed, 194 insertions(+), 15 deletions(-) create mode 100644 开发进度存档 diff --git a/.codebuddy/memory/2026-08-23.md b/.codebuddy/memory/2026-08-23.md index aabba7c..32a3c37 100644 --- a/.codebuddy/memory/2026-08-23.md +++ b/.codebuddy/memory/2026-08-23.md @@ -194,3 +194,10 @@ - **⚠️ 打包环境大坑（重要）**：CodeBuddy CN 注入的 `node-safe-delete-shim` 把 Node 的 `fs.rm`/PowerShell `Remove-Item` 劫持为"回收站批量删除守卫"，删除大量文件时报错（中文用户名 `范先生` 路径乱码致守卫脚本 MODULE_NOT_FOUND）。**electron-builder 解压前必须删旧 win-unpacked → 必触发 → 打包失败**。而且失败后 `npm run dist` 的 node/electron-builder 进程**会挂死不退出、占用 release 文件**。 - **解法**：① 打包前用 `[System.IO.Directory]::Delete(...,$true)` 删掉整个 `release` 目录（.NET API 绕过钩子）；② 若报"文件被占用"，先 `Get-CimInstance Win32_Process | Where CommandLine -like '*SmartAgriCenter*'` 找到挂死的 npm/electron-builder 进程 `Stop-Process -Force`；③ 再删 release 重跑 `npm run dist`。 - 首次打包成功是因为 release 当时不存在；此后只要 release 存在就会触发删除陷阱。**记住：每次打包前先 .NET 删 release**。 + +## 2026-08-23 文档三件套 + 开发进度存档（跨会话恢复入口） + +- 「项目需求」升级 **v3.0**：§5 补充绿色版打包✅/图标✅/瘦身方案（zip 139.7→128.9MB）；§7 待办更新（打包分发标✅，新增截图实测/遥控美化候选）；§8 补打包阶段对照。 +- **新增根目录 `开发进度存档`（无扩展名）**：作为跨会话上下文恢复入口，含目录结构/快速启动/打包手册（含所有坑）/代码结构地图/功能清单/待办/Git 信息/踩坑实录表。 +- MEMORY.md 更新：顶部加「换环境先读 `开发进度存档`」指引；文档三件套说明；打包章节更新（128.9MB、build/icon.ico、SafeDelete 坑）。 +- 目的：用户重装 CodeBuddy/换文件夹路径后，新会话读 `开发进度存档` 即可省积分快速恢复上下文。 diff --git a/.codebuddy/memory/MEMORY.md b/.codebuddy/memory/MEMORY.md index c04b109..674e462 100644 --- a/.codebuddy/memory/MEMORY.md +++ b/.codebuddy/memory/MEMORY.md @@ -1,11 +1,12 @@ # 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）。 +- 工作区：仓库根目录（当前为 `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。 @@ -34,13 +35,14 @@ ## 版本号与打包（2026-08-23 新增） - 版本号单一来源 = `package.json version`（当前 0.1.0）；主进程 `app.getVersion()`；标题栏显示「系统版本号 vX.Y.Z」；任务栏标题由 `did-finish-load` 时 `setTitle` 兜底（页面 `` 会覆盖构造标题）。 -- 项目需求文档：根目录 `项目需求`（无扩展名）2026-08-23 重写为 v2.0（Electron 重写版当前阶段，✅/⏳ 标注）；根目录 `指令清单` 为历史补充需求清单（需求已全部实现）。另有 UI 速览图 `SmartAgriCenter/docs/ui-screenshots/`（若有）。 +- 文档三件套（均在根目录，无扩展名）：`项目需求`（v3.0，✅/⏳ 标注）、`开发进度存档`（**跨会话恢复入口**）、`指令清单`（历史，已全部实现）。 - 已实现功能全景（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，electron-builder@26.15.3 已装）：`npm run dist` → `release\智慧农业大数据可视化控制中心-0.1.0-win.zip`（绿色免安装，当前 **128.9MB**）+ `release\win-unpacked\`。应用图标 `build/icon.ico` 已配置。瘦身：`compression: maximum` + `scripts/afterPack.js` 裁剪 locales（55→3），zip 139.7→128.9MB。 +- **⚠️ 打包必读**：每次 `npm run dist` 前必须用 `[System.IO.Directory]::Delete(...,$true)` 删掉旧 `release/`（SafeDelete 守卫会拦批量删除并导致打包卡死）；打包前设 `$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"`。详见根目录 `开发进度存档` §4。 ## 待办/候选开发点（截至 2026-08-23） 1. 页面预览图实际截图流程实测（page:snapshot 依赖 URL 可加载）。 2. 遥控器模拟界面视觉美化。 -3. 打包分发（electron-builder 等）。 -4. 项目 JSON 导入/导出。 +3. 项目 JSON 导入/导出。 +4. 代码视图/页面视图切换、遥控器硬件对接、帮助文档入口。 diff --git a/开发进度存档 b/开发进度存档 new file mode 100644 index 0000000..f29f47f --- /dev/null +++ b/开发进度存档 @@ -0,0 +1,151 @@ +# 智慧农业大数据可视化控制中心 — 开发进度存档 + +> 本文件是**跨会话上下文恢复的入口文档**。更换环境/重装 CodeBuddy/新开会话时， +> 先读本文件即可快速恢复项目全貌，无需重新探索代码。 +> 最后更新：2026-08-23 · 当前版本：v0.1.0 · 状态：功能开发阶段基本完成，分发阶段已完成一轮。 + +--- + +## 1. 项目一句话 + +Windows 桌面应用（Electron + React 19 + TS），扮演 **编辑器/调度器/发布器** 三角色： +管理大屏 HTML 页面工程、按屏幕分发轮播、输出到显示器全屏展示。软件不做图表绘制，业务内容全是网页。 + +## 2. 目录结构 + +``` +DataViewCenter/ # Git 仓库根目录 +├─ 项目需求 # 需求文档 v3.0（已实现✅/规划⏳标注） +├─ 开发进度存档 # 本文件 +├─ 指令清单 # 历史补充需求清单（已全部实现，仅存档） +├─ prototype/ # 大屏原型（index.html、sample-screen.html） +└─ SmartAgriCenter/ # Electron 主项目 + ├─ src/main/ # 主进程 + ├─ src/preload/ # 预加载桥接 + ├─ src/renderer/ # React 渲染层 + ├─ scripts/afterPack.js # 打包后处理（裁剪语言包） + ├─ build/icon.ico # 应用图标 + ├─ electron-builder.yml # 打包配置 + ├─ electron.vite.config.ts + ├─ 智慧农业大数据可视化.json # 示例工程 + └─ package.json # 版本号单一来源（当前 0.1.0） +``` + +## 3. 快速启动（省时操作手册） + +> ⚠️ **本机 PowerShell 中文路径坑**：参数含中文路径（`c:/Users/范先生/...`）会乱码导致 cd 失败， +> **命令一律在 `DataViewCenter` 根目录用相对路径**，或先 `cd SmartAgriCenter` 再执行。 + +```powershell +# ① 开发模式（热更新，推荐日常开发） +cd SmartAgriCenter; npm run dev + +# ② 生产预览（build 后） +npm run build; npm start + +# ③ 类型检查（改完代码必跑） +npm run typecheck + +# ④ 打包绿色版 zip（见 §4 打包前的必备步骤！） +npm run dist +``` + +后台启动 dev（不占终端）： +```powershell +cd SmartAgriCenter +Start-Process npm.cmd -ArgumentList 'run','dev' -RedirectStandardOutput 'dev.log' -RedirectStandardError 'dev-err.log' -WindowStyle Hidden +``` +注意：**必须用 `npm.cmd`**（直接 `Start-Process npm` 报 "not a valid Win32 application"）。 + +## 4. 打包分发（npm run dist） + +**打包前必备步骤（否则必失败）：** +1. 删除旧 `release/` 目录 —— CodeBuddy 注入的删除守卫（SafeDelete）会拦截 `Remove-Item`/`fs.rm`， + 必须用 .NET API 绕过： + ```powershell + [System.IO.Directory]::Delete("$PWD\SmartAgriCenter\release", $true) + ``` +2. （网络受限时）设二进制镜像： + ```powershell + $env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/" + ``` +3. `cd SmartAgriCenter; npm run dist` + +产物：`release\智慧农业大数据可视化控制中心-0.1.0-win.zip`（约 128.9MB，解压即用）+ `win-unpacked\`（绿色目录）。 + +**瘦身方案（已落地）**：`electron-builder.yml` 的 `compression: maximum`（7z 极限压缩）+ `scripts/afterPack.js` +裁剪 locales（55 → 3：zh-CN/zh-TW/zh-HK/en-US）。zip 139.7→128.9MB；win-unpacked 364.9→319.8MB。 +- `LICENSES.chromium.html`（~19MB）：开源许可证合规文件，**勿删**。 +- `dxcompiler.dll`（~24MB，WebGPU 用）：默认保留；`afterPack.js` 有开关可删，约再省 22MB。 + +**若打包失败（release 文件被占用）**：找到挂死的进程并杀掉再重试： +```powershell +Get-CimInstance Win32_Process | Where CommandLine -like '*SmartAgriCenter*' | ForEach { Stop-Process -Id $_.ProcessId -Force } +``` + +## 5. 代码结构地图 + +| 文件 | 职责 | +|---|---| +| `src/main/index.ts` | 无边框主窗口 + 单实例锁；`handleLaunch`（快捷方式拉起项目）；`session.setPermissionRequestHandler` 放行麦克风 | +| `src/main/ipc.ts` | 全部 IPC 注册 + 未保存关闭守卫；工程读写带密码；`page:snapshot` 截图 | +| `src/main/screens.ts` | 屏幕窗口管理器：多屏发布/单屏轮播/主屏 WebContentsView 全屏；`makeKeyHandler` 快捷键（1-9 长按阈值/Esc/F5/锁定键）；`probeScreens` 屏幕检测 | +| `src/main/settings.ts` | 配置持久化 `userData/settings.json`（名称/密码/阈值/锁定键/发布默认值/lastDir） | +| `src/main/crypto.ts` | AES-256-GCM 加密（key=SHA256(pwd)，密文前缀 `enc:v1:`，只加密 URL/参数） | +| `src/main/project.ts` | 工程文件读写/密码解密、URL 拼接 | +| `src/main/shortcuts.ts` | 桌面快捷方式（app/edit/publish 三类）+ `--project --mode` 参数解析 | +| `src/main/loader.ts` | 渲染层未就绪时的项目加载暂存 | +| `src/preload/` | contextBridge 暴露 `window.api`（win/screens/project/key/syncProject/setDirty/beep/createShortcut/confirm/carousel/page.snapshot/settings/app） | +| `src/renderer/src/store.ts` | zustand 全局状态（pages/视图/settings/密码状态） | +| `src/renderer/src/publishActions.ts` | 发布动作（预览/单屏轮播/多屏/关闭/检测/应用默认发布） | +| `src/renderer/src/views/` | App 主视图、编辑视图、配置视图 | +| `src/renderer/src/components/` | Ribbon、PageList、WebFrame、弹窗、配置面板等 15 组件 | +| `src/renderer/src/utils.ts` | 页面 JSON 序列化（含 PagePreview Base64） | +| `src/renderer/src/types.ts` | 全部类型（Page/AppSettings/PublishDefaults/LoadPayload/AppInfo…） | + +**三进程**：main（窗口/发布/快捷键/IPC）→ preload（安全桥接）→ renderer（编辑与配置 UI）。 +视图仅有 `'edit' | 'config'` 两种（发布功能已并入编辑 Tab 的 Ribbon）。 + +## 6. 已实现功能清单（v0.1.0） + +- **Ribbon 三组**：项目（新建/打开/保存/另存为/页面重排）、页面（新建/前插/复制/删除/上移/下移/缩略图）、 + 发布 6 按钮（预览本页👁️/单屏发布🎠可轮播/多屏发布🖥️可同时主屏/停止轮播⏹️/关闭所有🏁/检测屏幕📡，全部弹窗交互） +- **页面列表**：预览图卡片（Base64 截图）+ 底部操作组（SVG 扁平图标，仅选中显示） +- **快捷键**：1-9 长按超阈值切页（默认 350ms）、↑↓ 轮播切换、Esc 退出、F5 刷新、锁定键（默认 F9）全局开关 +- **配置 6 菜单**：项目信息（名称/版本/JSON 密码）、遥控设置（模拟器+阈值+锁定键+速查表）、快捷方式×3、发布设置（默认模式）、设备测试（键/音/麦/屏）、关于 +- **安全**：AES-256-GCM 工程加密、未保存关闭守卫、单实例锁 +- **分发**：绿色版打包 zip、应用图标、compression maximum + 语言包裁剪 + +## 7. 后续待办（按优先级） + +1. ⏳ 页面预览图截图流程实测（`page:snapshot` 依赖 URL 可加载，用真实网址验证） +2. ⏳ 遥控器模拟界面视觉美化 +3. ⏳ 项目 JSON 导入/导出 +4. ⏳ 代码视图/页面视图切换 +5. ⏳ 遥控器硬件对接 +6. ⏳ 帮助文档入口 + +## 8. Git 远程与提交 + +- 远程：`https://github.bbitcn.net/fanhongcai/DataViewCenter.git` +- **远程名是 `DataViewCenter`，不是 `origin`**；`main` 已设上游跟踪 → 直接 `git push` +- 提交历史：`68810be`（init 全量）→ `682962e`（打包瘦身） +- `.gitignore` 忽略：node_modules / out / dist / release / 日志 / IDE +- `.codebuddy/memory/` 随仓库备份（跨会话记忆） + +## 9. 关键环境经验（踩坑实录） + +| 坑 | 解法 | +|---|---| +| PowerShell 中文路径乱码 | 命令用相对路径；先 cd 再执行；避免 `git -C`/直接写中文文件名 | +| `npm run dist` 卡死/文件占用 | 挂死的 node/electron-builder 进程未退出 → 先杀进程再删 release（§4） | +| CodeBuddy 删除守卫拦截批量删除 | 用 `[System.IO.Directory]::Delete(dir,$true)` 或 `cmd /c "rd /s /q <dir>"` | +| electron 二进制缺失（"Electron failed to install correctly"） | `node node_modules/electron/install.js`；网络受限先 `$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"` | +| 改 main/preload 后不生效 | electron-vite dev 不会自动重启 electron → 杀掉 dev 进程组（npm-cli→electron-vite→electron）重启；仅 renderer 改动走 HMR | +| webview 预览高度异常 | 动态创建 webview 需 class+`style.display='flex';height:100%` + 父级 flex 拉伸（三重保险，已修） | +| 打包验证进程名 | 包名即 exe 名「智慧农业大数据可视化控制中心」，用 `Get-Process | Where MainWindowTitle -like '*智慧农业*'` 定位 | +| `credential-manager-core` 告警 | 无害，凭据已缓存，忽略 | + +--- + +*更新规则：本文件随每次开发阶段收尾更新；详细逐日变更见 `.codebuddy/memory/YYYY-MM-DD.md`。* diff --git a/项目需求 b/项目需求 index 9ef2d28..9e04f07 100644 --- a/项目需求 +++ b/项目需求 @@ -1,11 +1,16 @@ # 智慧农业大数据可视化控制中心 项目需求文档 -> 文档版本：2.0（2026-08-23 重写） +> 文档版本：3.0（2026-08-23 更新） > 对应实现版本：v0.1.0（Electron 重写版） > -> 更新说明：本版根据项目当前实现阶段全面重写。原文档基于旧 WinForm 版（v1.0）撰写， -> 技术架构、界面结构、功能划分均已按 Electron + React 重写版实际状态更新； +> 更新说明： +> - v2.0（2026-08-23）：根据项目当前实现阶段全面重写。原文档基于旧 WinForm 版（v1.0）撰写， +> 技术架构、界面结构、功能划分均已按 Electron + React 重写版实际状态更新。 +> - v3.0（2026-08-23）：补充绿色版打包、应用图标、打包瘦身等已完成事项（见 §5）； +> 更新待办与后续规划（§7）；需求来源对照补充最新阶段（§8）。 +> > 已实现需求标注 ✅，规划中需求标注 ⏳。 +> 项目完整开发进度与快速启动指南见根目录 `开发进度存档` 文档。 --- @@ -230,8 +235,18 @@ - 主进程通过 `app.getVersion()` 读取 - 标题栏、任务栏/Alt+Tab 标题均显示版本号 - 升级时仅需修改 `package.json` 一处 -2. **绿色版打包**：`npm run dist` 生成免安装 zip 压缩包（x64，解压即用），输出到 `release/` +2. **绿色版打包** ✅：`npm run dist` 生成免安装 zip 压缩包（x64，解压即用），输出到 `release/` + - 配置：`SmartAgriCenter/electron-builder.yml`（electron-builder@26.15.3） + - 产物：`release\智慧农业大数据可视化控制中心-0.1.0-win.zip`（当前约 **128.9MB**）+ `release\win-unpacked\`（绿色目录） + - 应用图标 ✅：`build/icon.ico`（≥256x256 多帧，任务栏/快捷方式/exe 均使用） + - **打包瘦身** ✅：`compression: maximum`（7z 极限压缩）+ `afterPack` 脚本 `scripts/afterPack.js` 裁剪语言包（locales 55 → 3：zh-CN/zh-TW/zh-HK/en-US） + - 体积对比：zip 139.7MB → 128.9MB；win-unpacked 364.9MB → 319.8MB + - `LICENSES.chromium.html`（约 19MB）为开源许可证合规文件，**必须保留**；`dxcompiler.dll`（WebGPU 着色器编译器，约 24MB）默认保留，删除可再省约 22MB（`scripts/afterPack.js` 有开关） 3. **运行时信息**：可通过主窗口「关于」查看 Electron / Chromium / Node 版本 +4. **打包注意事项**（见 `开发进度存档`）： + - 打包前需先删除旧 `release/` 目录（用 .NET API `[System.IO.Directory]::Delete`，规避 CodeBuddy 注入的删除守卫报错） + - 打包前设 `$env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"`（网络受限时） + - `npm run pack` = 只出 win-unpacked 目录；`npm run dist` = 打 zip 包 --- @@ -247,12 +262,15 @@ ## 7. 待办与后续规划 ⏳ -| 待办 | 说明 | -|---|---| -| 项目导入 / 导出 | 编辑 Tab 项目操作补齐 | -| 代码视图 / 页面视图切换 | 编辑页面双视图 | -| 遥控器硬件对接 | 对接实体遥控器硬件操作大屏（当前为键盘模拟方案） | -| 帮助文档入口 | 「关于」中提供外部帮助文档链接 | +| 待办 | 说明 | 状态 | +|---|---|---| +| 绿色版打包与分发 | electron-builder 打包、应用图标、打包瘦身 | ✅ 已完成（见 §5） | +| 页面预览图截图流程实测 | `page:snapshot` 依赖页面 URL 可加载，需用真实可访问 URL 实测截图 | ⏳ 候选 | +| 遥控器模拟界面视觉美化 | 配置页「遥控设置」的遥控器模拟器视觉优化 | ⏳ 候选 | +| 项目导入 / 导出 | 编辑 Tab 项目操作补齐 | ⏳ 候选 | +| 代码视图 / 页面视图切换 | 编辑页面双视图 | ⏳ 候选 | +| 遥控器硬件对接 | 对接实体遥控器硬件操作大屏（当前为键盘模拟方案） | ⏳ 候选 | +| 帮助文档入口 | 「关于」中提供外部帮助文档链接 | ⏳ 候选 | --- @@ -262,3 +280,4 @@ |---|---| | 原 WinForm 版需求（v1.0 文档） | 已在 Electron 重写版中落地，本文档为当前实现版 | | 界面/功能调整清单（指令清单） | 发布按钮组 6 按钮、配置页 6 菜单、遥控阈值、快捷方式×3、发布默认值、设备测试、关于、记住最后文件夹、轮播选项、页面重排 —— **已全部实现** ✅ | +| 打包分发阶段（v3.0 起） | 绿色版打包、应用图标、压缩与语言包瘦身 —— **已完成** ✅；分发体积已从 139.7MB 降至 128.9MB |