284 lines
13 KiB
Plaintext
284 lines
13 KiB
Plaintext
# 智慧农业大数据可视化控制中心 项目需求文档
|
||
|
||
> 文档版本：3.0（2026-08-23 更新）
|
||
> 对应实现版本：v0.1.0（Electron 重写版）
|
||
>
|
||
> 更新说明：
|
||
> - v2.0（2026-08-23）：根据项目当前实现阶段全面重写。原文档基于旧 WinForm 版（v1.0）撰写，
|
||
> 技术架构、界面结构、功能划分均已按 Electron + React 重写版实际状态更新。
|
||
> - v3.0（2026-08-23）：补充绿色版打包、应用图标、打包瘦身等已完成事项（见 §5）；
|
||
> 更新待办与后续规划（§7）；需求来源对照补充最新阶段（§8）。
|
||
>
|
||
> 已实现需求标注 ✅，规划中需求标注 ⏳。
|
||
> 项目完整开发进度与快速启动指南见根目录 `开发进度存档` 文档。
|
||
|
||
---
|
||
|
||
## 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/`
|
||
- 配置：`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 包
|
||
|
||
---
|
||
|
||
## 6. 非功能需求
|
||
|
||
1. **单实例运行**：应用同一时刻仅允许一个实例
|
||
2. **未保存守卫**：关闭窗口时若有未保存修改，提示用户处理
|
||
3. **快捷键避坑**：数字键长按阈值机制避免与网页输入冲突；锁定键可一键暂停快捷键识别（适合演示场景）
|
||
4. **多屏异步输出**：支持多页面、多屏幕，实现多屏异步输出不同大屏网页
|
||
5. **性能**：发布页面使用独立渲染视图，不影响编辑器操作
|
||
|
||
---
|
||
|
||
## 7. 待办与后续规划 ⏳
|
||
|
||
| 待办 | 说明 | 状态 |
|
||
|---|---|---|
|
||
| 绿色版打包与分发 | electron-builder 打包、应用图标、打包瘦身 | ✅ 已完成（见 §5） |
|
||
| 页面预览图截图流程实测 | `page:snapshot` 依赖页面 URL 可加载，需用真实可访问 URL 实测截图 | ⏳ 候选 |
|
||
| 遥控器模拟界面视觉美化 | 配置页「遥控设置」的遥控器模拟器视觉优化 | ⏳ 候选 |
|
||
| 项目导入 / 导出 | 编辑 Tab 项目操作补齐 | ⏳ 候选 |
|
||
| 代码视图 / 页面视图切换 | 编辑页面双视图 | ⏳ 候选 |
|
||
| 遥控器硬件对接 | 对接实体遥控器硬件操作大屏（当前为键盘模拟方案） | ⏳ 候选 |
|
||
| 帮助文档入口 | 「关于」中提供外部帮助文档链接 | ⏳ 候选 |
|
||
|
||
---
|
||
|
||
## 8. 需求来源对照
|
||
|
||
| 来源 | 状态 |
|
||
|---|---|
|
||
| 原 WinForm 版需求（v1.0 文档） | 已在 Electron 重写版中落地，本文档为当前实现版 |
|
||
| 界面/功能调整清单（指令清单） | 发布按钮组 6 按钮、配置页 6 菜单、遥控阈值、快捷方式×3、发布默认值、设备测试、关于、记住最后文件夹、轮播选项、页面重排 —— **已全部实现** ✅ |
|
||
| 打包分发阶段（v3.0 起） | 绿色版打包、应用图标、压缩与语言包瘦身 —— **已完成** ✅；分发体积已从 139.7MB 降至 128.9MB |
|