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

2026-08-23 10:57:14 +08:00
commit 2c90205766
61 changed files with 14564 additions and 0 deletions
@@ -0,0 +1,264 @@
+# 智慧农业大数据可视化控制中心 项目需求文档
+
+> 文档版本：2.0（2026-08-23 重写）
+> 对应实现版本：v0.1.0（Electron 重写版）
+>
+> 更新说明：本版根据项目当前实现阶段全面重写。原文档基于旧 WinForm 版（v1.0）撰写，
+> 技术架构、界面结构、功能划分均已按 Electron + React 重写版实际状态更新；
+> 已实现需求标注 ✅，规划中需求标注 ⏳。
+
+---
+
+## 1. 项目概述
+
+### 1.1 产品定位
+
+**智慧农业大数据可视化控制中心**是一款 Windows 桌面应用，同时扮演三种角色：
+
+- **编辑器**：编辑、管理大屏页面工程
+- **调度器**：将编辑好的页面按屏分发、轮播调度
+- **发布器**：把网页大屏推送输出到显示屏幕终端
+
+> 核心原则：软件本身是**编辑器、调度器、发布器**，大屏业务内容全部是 HTML 网页。
+> 软件不做图表绘制，只负责管理页面配置与分发调度。
+
+### 1.2 技术架构
+
+| 层 | 技术选型 |
+|---|---|
+| 桌面框架 | Electron（v43.x） |
+| UI 框架 | React 19 + TypeScript |
+| 构建工具 | Vite + electron-vite |
+| 状态管理 | Zustand |
+| 宿主环境 | Windows x64 |
+| 项目存储 | `.json` 工程文件（可选密码加密） |
+
+三进程结构：主进程（main，窗口/发布/快捷键/IPC）、预加载（preload，安全桥接）、渲染进程（renderer，编辑与配置 UI）。
+
+### 1.3 界面布局
+
+1. **无边框自绘标题栏**：工程名 + 版本号（`v0.1.0`，随 `package.json` 版本号自动更新）+ 未保存标记 + 最小化/最大化/关闭按钮
+2. **Ribbon 顶部工具栏**：`项目`、`页面`、`发布` 三组功能按钮
+3. **编辑视图**（三栏布局，参考 WPS 幻灯片界面）：
+   - 左侧：页面列表（缩略图 + 序号，增删改管理）
+   - 中间：大屏预览画布（内嵌加载所选页面，支持缩放与刷新）
+   - 右侧：页面属性面板
+4. **配置视图**（左右结构）：左侧配置菜单栏 + 右侧配置区
+5. **底部状态栏**：系统状态信息
+
+---
+
+## 2. 功能需求
+
+## 2.1 编辑功能
+
+### 2.1.1 项目操作（Ribbon「项目」组）
+
+| 功能 | 状态 | 说明 |
+|---|---|---|
+| 新建项目 | ✅ | 内置 4 个示例页面 |
+| 打开项目 | ✅ | 选择 `.json` 工程文件，含密码解密（见 §5.2） |
+| 保存 | ✅ | 写入当前工程（密码加密） |
+| 另存为 | ✅ | 选择新路径保存 |
+| 记住最后文件夹 | ✅ | 打开/另存为自动定位上次使用的目录 |
+| 导入项目 | ⏳ | 规划中 |
+| 导出项目 | ⏳ | 规划中 |
+
+### 2.1.2 页面操作（Ribbon「页面」组）
+
+| 功能 | 状态 | 说明 |
+|---|---|---|
+| 新建页面 | ✅ | 在列表末尾插入新页 |
+| 前插页面 | ✅ | 在选中页面前插入 |
+| 上移 / 下移 | ✅ | 调整页面顺序 |
+| 复制页面 | ✅ | 复制选中页面 |
+| 删除页面 | ✅ | 删除选中页面 |
+| 截图 | ✅ | 对当前页面 URL 截图，生成预览图 |
+| 页面重排 | ✅ | 重置/整理页面顺序 |
+| 切换代码视图 / 页面视图 | ⏳ | 规划中 |
+
+### 2.1.3 页面列表
+
+- 每个页面以**缩略图 + 序号**展示
+- 预览图来自当前 URL 页面的**截图**，以 **Base64** 方式保存在 JSON 中并展示
+- 选中页面后，中间画布加载该大屏、右侧刷新属性
+
+### 2.1.4 页面属性（右侧面板）
+
+| 字段 | 说明 |
+|---|---|
+| PageID | 页面编号（页面 ID） |
+| ScreenIndex | 绑定屏幕编号（指定该页面投放到哪块屏幕） |
+| ControllerIndex | 控制器索引（键盘数字键长按切换到此页） |
+| IsDisplay | 是否显示 |
+| PageTitle | 页面标题 |
+| PageDescribe | 页面描述备注 |
+| PageUrl | 页面网页地址（如 `about:blank`） |
+| PageParams | 页面参数（自动拼装进 URL 访问） |
+| PagePreview | 页面截图预览（Base64，持久化到 JSON） |
+
+### 2.1.5 画布
+
+- 内嵌加载当前选中页面（`about:blank` 显示空白页提示）
+- 工具栏：显示页面标题、URL、**刷新大屏页面**、**缩小/放大**（±10%）
+
+## 2.2 发布功能（大屏输出调度）
+
+### 2.2.1 发布按钮组（Ribbon「发布」组，顺序固定）
+
+| 按钮 | 状态 | 行为 |
+|---|---|---|
+| **预览本页** | ✅ | 弹窗选择指定屏幕播放当前页面（支持快捷键控制） |
+| **单屏发布** | ✅ | 弹窗选择指定屏幕播放所有页面；新增**是否轮播** + **轮播间隔 X 秒**选项（支持快捷键控制） |
+| **多屏发布** | ✅ | 弹窗预览各屏幕布局与页面；新增 CheckBox 设置**是否在当前编辑器屏幕上也全屏显示**；确认后各页面按所在屏幕 ID 全屏播放（支持快捷键控制） |
+| **停止轮播** | ✅ | 停止单屏轮播 |
+| **关闭所有** | ✅ | 关闭所有播放的页面 |
+| **检测屏幕** | ✅ | 弹窗显示已连接屏幕列表；各屏幕左上角**黑底白字**醒目显示屏幕编号和分辨率，便于演示人员查看屏幕布局 |
+
+### 2.2.2 快捷键体系（大屏 / 轮播 / 主窗口统一生效）
+
+| 按键 | 功能 |
+|---|---|
+| `1` - `9` | 进入对应控制器编号的页面（需长按超过阈值，见 §2.3.2） |
+| `↑` `↓`（或 `←` `→`） | 轮播页面上/下切换 |
+| `Esc` | 退出全屏 / 关闭播放 |
+| `F5` | 刷新当前页面 |
+| `F9`（可配置） | 锁定 / 解锁快捷键识别 |
+
+## 2.3 配置功能
+
+配置页面为**左右结构**：左侧菜单栏 + 右侧配置区。共 6 个菜单：
+
+### 2.3.1 项目信息（📋）
+
+- 配置**项目名称**、**版本号**
+- 配置 **JSON 读写密码**（防止 JSON 文件泄露后明文显示 URL 和网页参数）
+
+### 2.3.2 遥控设置（🎮）
+
+- **遥控器模拟界面**：给演示者展示快捷键信息并测试快捷键
+  - 数字键 `1`-`9`：切换对应控制器编号页面
+  - `↑` `↓`：上一页 / 下一页
+  - `Esc`：关闭所有播放页面
+  - 锁定键：一键锁定/解锁快捷键识别
+- **快捷键触发阈值设置**：解决"网页内交互输入数字也会触发切屏"的问题——数字/方向键需**长按超过阈值**（默认 350ms，可调 100-1500ms）才切屏，快速输入不受影响
+- **锁定/解锁快捷键**：默认 `F9`，可选 `F8` / `F10` / `ScrollLock` / `Pause` / `NumLock`
+- **快捷键测试区**：输入框实测键盘行为，记录按键与键码
+- **快捷键速查表**：集中展示全部快捷键
+
+### 2.3.3 快捷方式（🖱️）
+
+三个桌面快捷方式：
+
+| 序号 | 快捷方式 | 行为 |
+|---|---|---|
+| ① | 打开本控制中心工具 | 直接打开应用主界面 |
+| ② | 打开指定项目 Json | 打开指定项目并进入**编辑**状态 |
+| ③ | 打开指定项目 Json | 打开指定项目并默认进入**发布**状态 |
+
+### 2.3.4 发布设置（🚀）
+
+- 发布**默认值**配置（快捷方式③按此默认配置发布）：
+  - 发布模式：多屏 / 单屏 / 主屏
+  - 屏幕编号、是否同时主屏全屏
+  - 单屏轮播间隔（秒）
+
+### 2.3.5 设备测试（🔌）
+
+| 测试项 | 说明 |
+|---|---|
+| ⌨️ 键盘测试 | 聚焦后记录按键与键码，支持清空记录 |
+| 🔊 音箱测试 | 音量调节、播放提示音、播放 C5 音阶 |
+| 🎙️ 麦克风测试 | 实时电平表，验证麦克风采集 |
+| 🖥️ 屏幕测试 | 检测屏幕，表格显示编号/分辨率/位置/类型/当前播放状态 |
+
+### 2.3.6 关于（ℹ️）
+
+- 显示当前工具版本号、系统简介
+- 运行环境：Electron / Chromium / Node 版本、平台
+- 编辑帮助、发布帮助
+
+---
+
+## 3. 业务流程
+
+1. **编辑**：新建多个大屏页面，配置每个页面的 URL、绑定屏幕索引等属性，必要时截图生成预览图
+2. **发布**：检测屏幕 → 选择屏幕 → 执行预览 / 单屏发布（可轮播）/ 多屏发布，网页大屏即在硬件屏幕上全屏展示
+3. **配置**：硬件调试、系统设置、快捷方式创建；全部工程配置保存到 JSON 文件，方便打开复用项目
+
+---
+
+## 4. 数据与安全
+
+### 4.1 工程文件结构（`.json`）
+
+```json
+{
+  "appName": "项目名称",
+  "version": "项目版本号",
+  "pages": [
+    {
+      "PageID": "页面编号",
+      "PageTitle": "页面标题",
+      "PageDescribe": "页面描述",
+      "ScreenIndex": 0,
+      "ControllerIndex": 0,
+      "IsDisplay": true,
+      "PageUrl": "网页地址",
+      "PageParams": "页面参数",
+      "PagePreview": "Base64 预览图"
+    }
+  ]
+}
+```
+
+### 4.2 密码加密
+
+- 项目 JSON 支持 **AES-256-GCM** 密码加密
+- 设置密码后，保存的 JSON 为密文，打开时需输入密码解密
+- 目的：防止工程文件泄露后明文暴露 URL 与网页参数
+
+### 4.3 应用配置（settings.json，存储于 userData 目录）
+
+项目名称、项目版本号、JSON 密码、快捷键阈值、锁定键、发布默认值（模式/屏幕/同时主屏/轮播间隔）、上次使用的文件夹。
+
+---
+
+## 5. 版本管理与分发
+
+1. **版本号单一来源**：`package.json` 的 `version` 字段（当前 `0.1.0`）
+   - 主进程通过 `app.getVersion()` 读取
+   - 标题栏、任务栏/Alt+Tab 标题均显示版本号
+   - 升级时仅需修改 `package.json` 一处
+2. **绿色版打包**：`npm run dist` 生成免安装 zip 压缩包（x64，解压即用），输出到 `release/`
+3. **运行时信息**：可通过主窗口「关于」查看 Electron / Chromium / Node 版本
+
+---
+
+## 6. 非功能需求
+
+1. **单实例运行**：应用同一时刻仅允许一个实例
+2. **未保存守卫**：关闭窗口时若有未保存修改，提示用户处理
+3. **快捷键避坑**：数字键长按阈值机制避免与网页输入冲突；锁定键可一键暂停快捷键识别（适合演示场景）
+4. **多屏异步输出**：支持多页面、多屏幕，实现多屏异步输出不同大屏网页
+5. **性能**：发布页面使用独立渲染视图，不影响编辑器操作
+
+---
+
+## 7. 待办与后续规划 ⏳
+
+| 待办 | 说明 |
+|---|---|
+| 项目导入 / 导出 | 编辑 Tab 项目操作补齐 |
+| 代码视图 / 页面视图切换 | 编辑页面双视图 |
+| 遥控器硬件对接 | 对接实体遥控器硬件操作大屏（当前为键盘模拟方案） |
+| 帮助文档入口 | 「关于」中提供外部帮助文档链接 |
+
+---
+
+## 8. 需求来源对照
+
+| 来源 | 状态 |
+|---|---|
+| 原 WinForm 版需求（v1.0 文档） | 已在 Electron 重写版中落地，本文档为当前实现版 |
+| 界面/功能调整清单（指令清单） | 发布按钮组 6 按钮、配置页 6 菜单、遥控阈值、快捷方式×3、发布默认值、设备测试、关于、记住最后文件夹、轮播选项、页面重排 —— **已全部实现** ✅ |