# 智慧农业大数据可视化控制中心 — 开发进度存档

> 本文件是**跨会话上下文恢复的入口文档**。更换环境/重装 CodeBuddy/新开会话时，
> 先读本文件即可快速恢复项目全貌，无需重新探索代码。
> 最后更新：2026-08-23 · 当前版本：v1.5.1 · 状态：功能开发阶段基本完成，分发阶段已完成多轮。

---

## 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        # 示例工程
   ├─ 会东智慧墒情大数据中心.json      # 用户工程（未跟踪）
   ├─ 智慧农业大数据可视化控制中心(1.3.2).json  # 用户工程副本（未跟踪）
   └─ package.json                     # 版本号单一来源（当前 1.5.1）
```

## 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 写法里的 `$true` 会被外层 shell 展开报错，**直接走 cmd 最稳**：
   ```powershell
   cmd /c rmdir /s /q "d:\CodeBuddy\Pros\DataViewCenter\SmartAgriCenter\release" 2>nul
   ```
2. （网络受限时）设二进制镜像：
   ```powershell
   $env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
   ```
3. `cd SmartAgriCenter; npm run dist`

产物：`release\智慧农业大数据可视化控制中心-1.5.1-win.zip`（约 135.1MB，解压即用）+ `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（0.1.0）；1.5.1 实测 135.1MB（内容增加后略涨）。
- `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` 按 URL 截图、`page:compress` 预览 webview 截图压缩（PNG→≤500KB JPEG）；`clipboard:write`；`shell:openExternal`（文传易外链） |
| `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:`；**1.5.0 起整体加密整个 JSON**，不只 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/clipboard/shell/page.snapshot/page.compress/settings/app） |
| `src/renderer/src/store.ts` | zustand 全局状态（pages/视图/settings/密码状态/`previewWv` 预览 webview 引用）；`capturePreview` 优先截预览 webview（所见即所得），非当前预览页回退 URL 截图 |
| `src/renderer/src/publishActions.ts` | 发布动作（预览/单屏轮播/多屏/关闭/检测/应用默认发布） |
| `src/renderer/src/views/` | App 主视图、编辑视图、配置视图 |
| `src/renderer/src/components/` | Ribbon、PageList、WebFrame（创建后 `setPreviewWv` 注册供截图）、弹窗、配置面板等组件 |
| `src/renderer/src/configMenus.ts` | 配置菜单定义：快捷方式×3、设备测试、遥控设置；「文传易」外链按钮（关于之前，系统浏览器打开 `http://wenchuanyi.bbitcn.net/`） |
| `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. 已实现功能清单（v1.5.1）

- **Ribbon 三组**：项目（新建/打开/保存/另存为/页面重排）、页面（新建/前插/复制/删除/上移/下移/缩略图）、
  发布 7 按钮（预览本页👁️/单屏发布🎠可轮播/多屏发布🖥️可同时主屏/交互发布🔁主屏轮流投屏各屏页面/停止轮播⏹️/关闭所有🏁/检测屏幕📡，全部弹窗交互）
- **页面列表**：预览图卡片（Base64 截图）+ 底部操作组（SVG 扁平图标，仅选中显示）；新增页面默认值：URL/参数/描述为空，所属屏幕与控制器编号=当前最大值+1
- **快捷键**：1-9 长按超阈值切页（默认 350ms）、↑↓ 轮播切换、Esc 退出、F5 刷新、锁定键（默认 F9）全局开关
- **配置菜单**：项目信息（名称/版本/JSON 密码）、遥控设置（模拟器+阈值+锁定键+速查表）、快捷方式×3、发布设置（默认模式）、设备测试（键/音/麦/屏）、**文传易外链**（关于前，系统浏览器打开 wenchuanyi.bbitcn.net）、关于
- **版本号快捷操作**：nextMajor/nextMinor/nextPatch 一步升级、+1 按钮（次版本+1）、保存工程时修订号自动 +1
- **截图与缩略图**：`capturePreview` 对**编辑区预览 webview 直接截图**（所见即所得，`wv.capturePage()`→PNG→主进程压缩 ≤500KB JPEG），非当前预览页回退按 URL 截图
- **安全**：AES-256-GCM **整体加密整个工程 JSON**、未保存关闭守卫、单实例锁、打开工程防抖（opening）
- **发布优化**：单屏切页闪烁修复（moveTop 置顶）、轮播取消循环+边界提示、交互发布 intervalSec/quick 参数透传、主程序关闭时子页面联动退出
- **编辑界面增强**：URL 3 行/参数 4 行输入、screenCount 至少 4、Paste 粘贴自动提取标题描述、复制经 IPC `clipboard:write`
- **分发**：绿色版打包 zip、应用图标、compression maximum + 语言包裁剪

## 7. 后续待办（按优先级）

1. ✅ 页面预览图截图流程已实测通过（改为截预览 webview，所见即所得，见 §6 截图与缩略图）
2. ⏳ 遥控器模拟界面视觉美化
3. ⏳ 项目 JSON 导入/导出
4. ⏳ 代码视图/页面视图切换
5. ⏳ 遥控器硬件对接
6. ⏳ 帮助文档入口

## 8. Git 远程与提交

- 远程：`https://github.bbitcn.net/fanhongcai/DataViewCenter.git`
- **远程名是 `DataViewCenter`，不是 `origin`**；`main` 已设上游跟踪 → 直接 `git push`
- 提交历史（2026-08-23 重写乱码信息后）：`2c90205`（init v0.1.0）→ `4b3ea03`（打包瘦身）→ `b11bea1`（文档存档 v3.0）→ `8df2f00`（记录乱码修复经验）→ `8d96f51`（清理）→ `aa8f070`（v0.2.0 交互发布+多屏发布增强+页面管理优化）→ `e0d9605`（修复单屏发布闪烁+编辑界面增强+新增页面默认值优化）→ 均已推送
- **当前未提交改动**（文传易外链 / 截图改截预览 webview / 工程 JSON 整体加密 / 缩略图压缩 / 版本 1.5.1）：package.json、src/main/ipc.ts、project.ts、settings.ts、preload/index.ts、index.d.ts、renderer/Ribbon.tsx、WebFrame.tsx、configMenus.ts、store.ts、utils.ts、env.d.ts、global.css、Canvas.tsx、AboutPanel.tsx、ProjectInfo.tsx
- **⚠️ 提交信息防乱码**：`git commit -m "中文"` 在本机会双编码乱码（GBK→UTF-8），**必须用 `git commit -F <utf8消息文件>`**
- `.gitignore` 忽略：node_modules / out / dist / release / 日志 / IDE
- `.codebuddy/memory/` 随仓库备份（跨会话记忆）

## 9. 关键环境经验（踩坑实录）

| 坑 | 解法 |
|---|---|
| PowerShell 中文路径乱码 | 命令用相对路径；先 cd 再执行；避免 `git -C`/直接写中文文件名 |
| **中文 commit message 乱码** | `git commit -m "中文"` 会双编码乱码（GBK→UTF-8）。**改用 `git commit -F <utf8消息文件>`**；已损坏的历史可用 Node 脚本 + `git hash-object -t commit -w` 保真重写（保留 author/committer/时间戳）再 force push |
| `npm run dist` 卡死/文件占用 | 挂死的 node/electron-builder 进程未退出 → 先杀进程再删 release（§4） |
| CodeBuddy 删除守卫拦截批量删除 | 用 `cmd /c rmdir /s /q <dir>`；`.NET API` 写法中的 `$true`/`$_` 会被外层 shell 展开报错，少用 |
| 外层 shell 展开 `$_`/`$true` | 外层命令由 PowerShell 包装执行，`$_` 会被展开 → 改用 `cmd /c dir`、`Where-Object -Filter`、`cmd /c rmdir` 等无变量写法 |
| 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 拉伸（三重保险，已修） |
| 缩略图与预览效果不一致 | 原方案主进程新开 1280×720 隐藏窗口截图，视口/尺寸与编辑区 webview 不同 → 改为直接 `wv.capturePage()`（webview 本体截图）→ `img.toPNG()` → IPC `page:compress` 主进程压缩；非当前预览页回退按 URL 截图 |
| 打包验证进程名 | 包名即 exe 名「智慧农业大数据可视化控制中心」，用 `Get-Process | Where MainWindowTitle -like '*智慧农业*'` 定位 |
| `credential-manager-core` 告警 | 无害，凭据已缓存，忽略 |

---

*更新规则：本文件随每次开发阶段收尾更新；详细逐日变更见 `.codebuddy/memory/YYYY-MM-DD.md`。*
