# 智慧农业大数据可视化控制中心 项目需求文档

> 文档版本：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、发布默认值、设备测试、关于、记住最后文件夹、轮播选项、页面重排 —— **已全部实现** ✅ |