docs: update feature spec with current implementation status

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-25 08:27:09 +08:00 · 2026-03-25 08:27:09 +08:00 · 884f6ba5f3
parent dae5bdcb9e
commit 884f6ba5f3
1 changed files with 287 additions and 412 deletions
--- a/docs/投煤器布料机功能实现方案.md
+++ b/docs/投煤器布料机功能实现方案.md
@ -1,4 +1,6 @@
-# 投煤器布料机远程监控与控制功能实现方案
+# 投煤器布料机远程监控与控制功能实现方案
+
+> 最后更新：2026-03-24（基于当前代码重新审阅）

 ## 1. 目标

@ -11,551 +13,424 @@
 - 支持故障锁定、人工复位、通讯异常冻结
 - 支持通过配置适配不同现场，不改代码完成项目复用

-## 2. 现有系统能力盘点
+---

-当前项目已经具备较好的通用工业采集平台基础：
+## 2. 当前系统能力盘点

- OPC UA 数据源接入与自动重连
- 节点浏览、批量建点、点位实时订阅
- 点位批量写入能力
- 设备 `equipment` 模型
- 点位到设备绑定 `equipment_id`
- 点位信号角色字段 `signal_role`
- WebSocket 实时推送
+### 2.1 通用平台基础（已有）
+
+- OPC UA 数据源接入与自动重连（`connection.rs`）
+- 节点浏览、批量建点、点位实时订阅（`handler/point.rs`, `handler/source.rs`）
+- 点位批量写入能力（`connection.rs: write_point_values_batch`）
+- WebSocket 实时推送（`websocket.rs`）
 - 前端设备、点位、日志、趋势图基础界面
 - 页面配置 `page` 能力
- 进程内事件总线 `event.rs`
+- 进程内事件总线 `event.rs`（control + telemetry 双通道）
+- HTTP 中间件、鉴权、分页等工具链

-现状更接近“通用点位监控平台”，还不是“投煤器/布料机业务控制系统”。
+### 2.2 业务模型（已有）

-## 3. 与需求的差距
+- `unit` 表（`migrations/20260324090000_add_unit_and_event.sql`）
+  - 包含 `run_time_sec`, `stop_time_sec`, `acc_time_sec`, `bl_time_sec`, `require_manual_ack_after_fault`
+- `event` 表（同上迁移），含 `unit_id`, `equipment_id`, `source_id`, `level`, `payload`
+- `equipment.unit_id` FK
+- `equipment.kind`，`point.signal_role`
+- `ControlUnit`, `EventRecord` 模型（`model.rs`）

-需求文档要求的软件能力，当前尚未落地的核心部分如下：
+### 2.3 业务逻辑（已有）

- 缺少“控制单元”概念，无法表达一组投煤器对应一组布料机
- 缺少业务配置模型，无法配置 `RunTime`、`StopTime`、`AccTime`、`BLTime`
- 缺少设备业务类型约束，尚未明确区分投煤器、布料机
- 缺少设备归属单元字段，尚未形成 `unit -> equipment -> point` 的业务链路
- 缺少业务信号角色规范，尚未标准化 `REM/RUN/FLT/STA/STP`
- 缺少自动控制状态机
- 缺少故障锁定与人工确认恢复流程
- 缺少通讯异常冻结与恢复后重同步机制
- 缺少脉冲写入封装，当前只有通用批量写点
- 缺少单元总览、设备详情、控制面板、报警面板等业务界面
- 缺少统一事件持久化与后续报警模型
+- Unit CRUD 接口：`GET/POST/PUT/DELETE /api/unit`, `GET /api/unit/{id}`
+- 设备手动控制接口：`POST /api/control/equipment/{id}/start|stop`
+  - 内置脉冲写入（写 1 → 等 300ms → 写 0）
+  - 前置校验：`rem == 1`, `flt == 0`, 通讯质量 good（`control/validator.rs`）
+- `AppEvent::EquipmentStartCommandSent/EquipmentStopCommandSent`，自动持久化 `event` 表并推送 WebSocket
+- 内存运行态结构体（`control/runtime.rs`）
+  - `UnitRuntimeState`: Stopped / Running / DistributorRunning / FaultLocked / CommLocked
+  - `UnitRuntime`：含 `accumulated_run_sec`, `fault_locked`, `comm_locked`, `manual_ack_required` 等全部字段
+  - `ControlRuntimeStore`：全局 `HashMap<Uuid, UnitRuntime>`，已注册到 `AppState`
+- `control/validator.rs`：独立的控制前置校验模块
+- `control/engine.rs`：模块骨架已建立，`start()` 函数为空桩
+- 前端：Unit 列表（`units.js`），事件列表（`events.js`），设备 Unit 绑定（`equipment.js`）
+- 事件列表接口：`GET /api/event`（支持 `unit_id`, `event_type` 过滤）
+
+---
+
+## 3. 与需求的差距（当前真实状态）
+
+| 需求项 | 状态 | 说明 |
+|--------|------|------|
+| Unit / 设备 / 点位数据模型 | ✅ 已完成 | 迁移、模型、CRUD 全部到位 |
+| 脉冲写入封装 | ✅ 已完成 | 内置在 `handler/control.rs` |
+| 手动控制前置校验 | ✅ 已完成 | `validator.rs` 实现 REM/FLT/quality 检查 |
+| 手动启停接口 | ✅ 已完成 | start/stop 接口含脉冲写入和事件持久化 |
+| 运行态内存模型 | ✅ 已完成 | `runtime.rs` 数据结构完整，已注入 AppState |
+| 事件持久化与查询 | ✅ 已完成 | event 表 + 事件处理 + GET /api/event |
+| **自动控制状态机** | ❌ 未实现 | `engine.rs` 是空桩，无任何调度逻辑 |
+| **自动控制接口** | ❌ 未实现 | 缺 `start-auto`, `stop-auto` 接口 |
+| **故障锁定联动** | ❌ 未实现 | `runtime.fault_locked` 有字段但无联动逻辑 |
+| **通讯冻结联动** | ❌ 未实现 | `runtime.comm_locked` 有字段但无联动逻辑 |
+| **人工确认解锁接口** | ❌ 未实现 | 缺 `ack-fault` 接口 |
+| **手动控制检查运行态** | ❌ 未实现 | `validator.rs` 未读取 `ControlRuntimeStore` |
+| **运行态 WebSocket 推送** | ❌ 未实现 | 单元状态变更未推送前端 |
+| **运行态查询接口** | ❌ 未实现 | 缺 `GET /api/unit/{id}/runtime` |
+| 前端设备控制面板 | ❌ 未实现 | 缺 REM/RUN/FLT 展示和手动启停按钮 |
+| 前端单元详情/总览 | ❌ 未实现 | 缺状态机状态展示、自动/手动切换 |
+| 前端参数在线编辑 | 🔶 部分 | Unit 编辑 Modal 有表单，但无运行态反馈 |
+
+---

 ## 4. 推荐实现思路

-推荐在现有平台上“增量扩展”，而不是重写：
+继续在现有平台上"增量扩展"：

- 保留现有 `source/node/point/equipment` 通用底座
- 新增面向业务控制的配置表和运行态管理
- 将控制逻辑放在 Rust 服务端，复用当前 OPC UA 连接和写点能力
- 前端增加业务页面，不破坏现有通用点位管理页面
- 基于现有 `event.rs` 扩展事件体系，而不是再造一套事件机制
+- 现有 `unit` / `equipment` / `point` / `event` 底座不动
+- 填充 `control/engine.rs` 实现状态机调度
+- 新增自动控制和 ack-fault 接口
+- `validator.rs` 增加对运行态的检查
+- 扩展 `AppEvent` 业务事件，通过 WebSocket 推送运行态变更
+- 前端增加业务控制页面

-这样做的好处是：
+---

- 现有 OPC UA、点位、设备、WebSocket 基础都能继续复用
- 后续不同现场只需要换设备映射和参数
- 手动调试仍然可以通过现有点位/设备页面完成
- 未来做报警、审计、统计时可以直接复用统一事件体系
+## 5. 命名与模型设计（已落地，确认）

-## 5. 命名与模型设计
-
-### 5.1 命名原则
-
-建议区分“代码命名”和“表命名”：
-
- 代码模型名保留语义完整性，如 `ControlUnit`
- 数据库表名尽量简洁，如 `unit`
-
-不建议使用 `group` 作为表名，原因是语义过泛，后续容易与权限分组、界面分组、标签分组等概念冲突。
-
-### 5.2 设备分类
-
-继续复用 `equipment` 表中的 `kind` 字段，约定：
+### 5.1 设备分类（`equipment.kind`）

 - `coal_feeder`：投煤器
 - `distributor`：布料机

-### 5.3 点位角色规范
-
-继续复用 `point.signal_role`，建议统一枚举值：
+### 5.2 点位角色规范（`point.signal_role`）

 - 状态点：`rem` `run` `flt` `ii` `q`
 - 控制点：`start_cmd` `stop_cmd`
 - 可选扩展：`estop` `mode_auto` `mode_manual` `reset_cmd`

-这样每台设备都可以通过“设备 + 点位角色”完成映射，而不是在代码里写死点名。
+### 5.3 Unit 运行态放内存（已确认）

-### 5.4 新增 `unit` 表
+运行态字段已在 `control/runtime.rs:UnitRuntime` 中定义完整，不落库。
+服务重启后重新从 `REM/RUN/FLT/Q` 重建运行态，不自动补发命令。

-建议新增 `unit` 表，对应代码模型 `ControlUnit`，表示一个业务控制单元。
+### 5.4 统一 `event` 表，预留 `alarm` 表（已落地）

-建议字段：
+- `event`：记录"发生了什么"，已上线
+- `alarm`：记录"需要被告警管理的异常"，第二阶段实现

- `id`
- `code`
- `name`
- `description`
- `enabled`
- `run_time_sec`
- `stop_time_sec`
- `acc_time_sec`
- `bl_time_sec`
- `require_manual_ack_after_fault`
- `created_at`
- `updated_at`
-
-### 5.5 设备直接归属 Unit
-
-当前业务前提下，一台设备只属于一个控制单元，不会跨单元复用，因此不建议单独建立关系表。
-
-更合适的方式是直接在 `equipment` 表新增：
-
- `unit_id`
-
-这样模型会更简单：
-
- 一个 `unit` 对多台 `equipment`
- 一台 `equipment` 只属于一个 `unit`
- `equipment.kind` 用于区分 `coal_feeder` 和 `distributor`
-
-如果后续现场出现“一台设备可挂多个单元”或“单元内设备编排顺序复杂”的需求，再演进成关系表会更合适。第一阶段不建议设计过重。
-
-### 5.6 Unit 运行态放内存
-
-`unit` 运行态不建议优先落数据库，建议由控制引擎保存在内存中。
-
-建议维护的内存运行态字段：
-
- `state`
- `accumulated_run_sec`
- `current_run_elapsed_sec`
- `current_stop_elapsed_sec`
- `distributor_run_elapsed_sec`
- `fault_locked`
- `comm_locked`
- `manual_ack_required`
- `last_tick_at`
-
-状态值建议：
-
- `stopped`
- `running`
- `distributor_running`
- `fault_locked`
- `comm_locked`
-
-原因：
-
- 这些字段变化频率高，不适合高频写库
- 服务重启后直接恢复旧控制态并不安全
- 更合理的方式是重启后重新读取 `REM/RUN/FLT/Q` 并重建运行态
- 通讯恢复或服务重启后不自动补发控制命令，更符合工业控制安全原则
-
-如后续确实需要“断电恢复上下文”或运行分析，再补充轻量级快照能力即可，但不是第一阶段必须项。
-
-### 5.7 统一 `event` 表，预留 `alarm` 表
-
-建议不要命名为 `control_event`，而是使用统一的 `event` 表。
-
-原因：
-
- 当前不仅有控制事件，后续还会有配置事件、通讯事件、数据源事件
- `event` 更适合作为统一审计与业务时间线
- 现有 `event.rs` 已经是进程内事件总线，命名保持一致更自然
-
-建议 `event` 表记录：
-
- 手动启动/停止
- 自动启动/停止
- 故障锁定
- 人工解除故障锁定
- 通讯异常/恢复
- 数据源创建、更新、删除
- 控制参数变更
- 关键状态切换
-
-关键字段建议：
-
- `id`
- `event_type`
- `level`
- `unit_id`
- `equipment_id`
- `source_id`
- `message`
- `payload`
- `created_at`
-
-同时建议未来单独设计 `alarm` 表，而不是把报警状态硬塞进 `event` 表。
-
-原因：
-
- 报警通常有独立生命周期：触发、确认、恢复、清除
- 报警需要独立字段，如 `severity`、`active`、`acked`、`acked_by`、`acked_at`、`cleared_at`
- 把报警硬塞到 `event` 中会让通用事件表越来越臃肿
-
-因此推荐边界是：
-
- `event`：记录“发生了什么”
- `alarm`：记录“需要被告警管理的异常”
-
-第一阶段可以先只落 `event` 表，`alarm` 表先在方案中预留，不急着实现。
+---

 ## 6. 控制逻辑设计

-### 6.1 手动控制
+### 6.1 手动控制（已实现，待补充运行态检查）

-手动控制前置校验：
+当前已实现：
+- `rem == 1` 检查
+- `flt == 0` 检查
+- 通讯质量检查
+- 脉冲写入（300ms）

- `REM == 1`
- `FLT == 0`
- 通讯正常
- 未处于故障锁定
- 如有急停点，`ESTOP == 0`
+**待补充**：在 `validator.rs` 中增加对 `ControlRuntimeStore` 的检查：
+- `fault_locked == true` → 拒绝
+- `comm_locked == true` → 拒绝
+- `manual_ack_required == true` → 拒绝（等待人工确认）

-控制命令统一走脉冲写入：
+### 6.2 自动控制状态机（待实现）

-1. 写入 `1`
-2. 延时 `200-500ms`
-3. 写回 `0`
-
-服务端需要封装 `pulse_write(point_id, high_ms)`，前端不能直接拼两次写点。
-
-### 6.2 自动控制状态机
-
-每个 `unit` 独立维护状态机。
+每个 `unit` 独立维护状态机，在 `control/engine.rs` 中以后台任务驱动。

 #### `STOPPED`

- 累计停止时间
- 若 `stop_elapsed >= StopTime`，尝试启动投煤器
- 成功后切换到 `RUNNING`
+- 累计停止时间 `current_stop_elapsed_sec`
+- 若 `stop_elapsed >= StopTime` → 校验投煤器 REM/FLT/质量 → 发启动命令 → 切换到 `RUNNING`

 #### `RUNNING`

- 累计运行时间
+- 累计运行时间 `current_run_elapsed_sec`
 - `accumulated_run_sec += delta`
- 若 `run_elapsed >= RunTime`，尝试停止投煤器，切换回 `STOPPED`
- 若 `accumulated_run_sec >= AccTime`，进入布料机触发流程
+- 若 `run_elapsed >= RunTime` → 停止投煤器 → 切换回 `STOPPED`
+- 若 `accumulated_run_sec >= AccTime` → 进入 `DISTRIBUTOR_RUNNING`

 #### `DISTRIBUTOR_RUNNING`

- 校验布料机 `REM/FLT/通讯`
- 启动布料机
- 等待 `RUN == 1` 反馈
+- 校验布料机 REM/FLT/质量
+- 启动布料机，等待 `RUN == 1`
 - 计时 `BLTime`
 - 停止布料机
- 累计时间清零
- 回到 `STOPPED` 或回到自动节拍起点
+- 清零 `accumulated_run_sec`
+- 切回 `STOPPED` 或自动节拍起点

-### 6.3 故障机制
+### 6.3 故障机制（待实现）

 任意设备检测到 `FLT == 1`：
-
 - 停止该单元自动控制
- 标记 `fault_locked = true`
- 禁止再次自动发命令
- 发送并持久化关键事件
-
-当 `FLT` 从 `1 -> 0` 恢复：
+- `state = FaultLocked`, `fault_locked = true`
+- 发送并持久化 `FaultLocked` 事件

+当 `FLT` 从 `1 → 0` 恢复：
 - 不自动解锁
- 标记 `manual_ack_required = true`
- 等待人工在界面点击“解除故障锁定”
+- `manual_ack_required = true`
+- 等待人工调用 `POST /api/control/unit/{id}/ack-fault`

-### 6.4 通讯异常机制
+### 6.4 通讯异常机制（待实现）

-当质量位异常或 OPC 连接中断：
-
- 标记 `comm_locked = true`
+当 OPC UA 质量位异常或连接中断：
+- `state = CommLocked`, `comm_locked = true`
 - 冻结全部控制动作
 - 前端按钮灰化
- 不允许任何自动/手动写入

 通讯恢复后：
-
 - 重新读取 `REM/RUN/FLT`
 - 重同步运行态
 - 不自动补发控制命令
- 发送并持久化恢复事件
+- 持久化恢复事件
 - 等待人工操作或下一次自动触发

+---
+
 ## 7. 事件体系设计

 ### 7.1 继续复用 `src/event.rs`

-建议不要另起一套业务事件中心，而是在现有 [src/event.rs](D:/projects/plc_control/src/event.rs) 上扩展。
+当前 `AppEvent` 已有：
+- `SourceCreate/Update/Delete`
+- `PointCreateBatch/PointDeleteBatch`
+- `EquipmentStartCommandSent/EquipmentStopCommandSent`
+- `PointNewValue`（遥测）

-当前它已经承担两类职责：
+**待扩展**：

- 控制类内部事件分发
- 遥测类高频事件分发
-
-推荐继续保留这个结构：
-
- `AppEvent` 作为统一进程内事件枚举
- 高频遥测事件继续走内存和 WebSocket
- 低频且有审计价值的事件选择性落库到 `event` 表
+```rust
+AutoControlStarted { unit_id }
+AutoControlStopped { unit_id }
+FaultLocked { unit_id, equipment_id }
+FaultAcked { unit_id }
+CommLocked { unit_id }
+CommRecovered { unit_id }
+UnitStateChanged { unit_id, from_state, to_state }
+```

 ### 7.2 哪些事件适合落库

-适合落库的：
+- 适合：所有手动/自动启停、故障、通讯、参数变更、状态切换
+- 不适合：`PointNewValue`、高频遥测、内部轮询过程

- `SourceCreate`
- `SourceUpdate`
- `SourceDelete`
- 自动控制启动/停止
- 手动启动/停止命令发送
- 故障锁定
- 人工确认恢复
- 通讯异常/恢复
- 参数配置变更
- 单元状态切换
-
-不适合直接落库的：
-
- `PointNewValue`
- 高频实时遥测
- 细碎的内部轮询过程
-
-### 7.3 推荐扩展方向
-
-建议在 `AppEvent` 中逐步增加业务事件，例如：
-
- `AutoControlStarted`
- `AutoControlStopped`
- `EquipmentStartCommandSent`
- `EquipmentStopCommandSent`
- `FaultLocked`
- `FaultAcked`
- `CommLocked`
- `CommRecovered`
- `UnitStateChanged`
-
-这样后续无论是写日志、落库、推送 WebSocket、做报警触发，都可以基于同一个事件入口。
+---

 ## 8. 后端改造方案

-### 8.1 新增模块
+### 8.1 已有模块（确认现状）

-建议新增：
+| 模块 | 文件 | 状态 |
+|------|------|------|
+| HTTP 控制接口 | `src/handler/control.rs` | ✅ 有 Unit CRUD + start/stop + event list |
+| 控制前置校验 | `src/control/validator.rs` | ✅ REM/FLT/质量检查，**待加运行态检查** |
+| 内存运行态 | `src/control/runtime.rs` | ✅ 数据结构完整 |
+| 自动控制引擎 | `src/control/engine.rs` | ❌ 空桩，待实现 |
+| 服务层 Unit | `src/service/` | ✅ CRUD 完整 |

- `src/handler/control.rs`
- `src/service/control.rs`
- `src/control/engine.rs`
- `src/control/runtime.rs`
- `src/control/validator.rs`
+### 8.2 待新增接口

-职责划分：
-
- `handler`：HTTP 接口
- `service`：数据库读写
- `control/engine`：状态机与调度
- `control/runtime`：内存运行态缓存与同步
- `control/validator`：控制前置校验
-
-### 8.2 新增接口
-
-建议新增接口：
-
- `GET /api/control/unit`
- `POST /api/control/unit`
- `PUT /api/control/unit/{id}`
- `GET /api/control/unit/{id}`
- `POST /api/control/unit/{id}/start-auto`
- `POST /api/control/unit/{id}/stop-auto`
- `POST /api/control/unit/{id}/ack-fault`
- `POST /api/control/equipment/{id}/start`
- `POST /api/control/equipment/{id}/stop`
- `GET /api/events`
+```
+POST /api/control/unit/{id}/start-auto    启动自动控制
+POST /api/control/unit/{id}/stop-auto     停止自动控制
+POST /api/control/unit/{id}/ack-fault     人工确认故障解锁
+GET  /api/unit/{id}/runtime               查询运行态（state, elapsed, fault_locked 等）
+```

 说明：
+- `start/stop-auto` 修改运行态 `auto_enabled`，引擎轮询时读取
+- `ack-fault` 仅在 `manual_ack_required == true` 时允许操作，否则返回 400

- 设备手动控制必须走业务接口，不建议继续直接暴露给页面做原始点位写入
- 原 `/api/point/value/batch` 保留给调试或底层工具能力
- 事件查询接口可以直接面向统一 `event` 表
+### 8.3 控制引擎运行方式（待实现）

-### 8.3 控制引擎运行方式
+在 `control/engine.rs: start()` 中实现后台任务：

-建议服务启动后增加一个后台任务：
+```
+每 500ms 扫描所有 enabled unit
+  ↓
+从 ControlRuntimeStore 读取运行态
+  ↓
+从 connection_manager.get_point_monitor_data_read_guard() 取实时点值
+  ↓
+检查质量位 → 更新 comm_locked
+  ↓
+检查 FLT → 更新 fault_locked
+  ↓
+驱动状态机 tick
+  ↓
+有状态变化 → 更新 ControlRuntimeStore → 发 AppEvent → 推 WebSocket
+```

- 每 `500ms` 或 `1s` 扫描所有启用的 `unit`
- 从内存读取运行态缓存
- 从当前点位监控数据中取 `REM/RUN/FLT/Q`
- 驱动状态机执行
+### 8.4 手动控制补充运行态检查

-控制引擎不要直接查 OPC，应复用当前 `connection_manager` 已维护的实时点值。
+在 `control/validator.rs: validate_manual_control()` 中增加：

-### 8.4 关键复用点
+```rust
+let runtime = state.control_runtime.get(unit_id).await;
+if let Some(runtime) = runtime {
+    if runtime.fault_locked {
+        return Err(ApiErr::Forbidden("Unit is fault locked", ...));
+    }
+    if runtime.comm_locked {
+        return Err(ApiErr::Forbidden("Unit is comm locked", ...));
+    }
+    if runtime.manual_ack_required {
+        return Err(ApiErr::Forbidden("Fault ack required before control", ...));
+    }
+}
+```
+
+### 8.5 关键复用点

 可直接复用当前已有能力：
+- `connection_manager.get_point_monitor_data_read_guard()` → 读取实时点值
+- `connection_manager.write_point_values_batch()` → 写点（自动控制也走此接口）
+- `event_manager.send()` → 统一事件入口
+- `ws_manager.send_to_public()` → 推送运行态变更
+- `unit_id + equipment.kind + point.signal_role` 三元组 → 业务映射

- `connection_manager` 的点位实时缓存
- `get_point_monitor_data_read_guard`
- 批量写点能力
- WebSocket 实时推送
- `event.rs` 的统一事件入口
- `unit_id + equipment.kind + point.signal_role` 的业务映射关系
+---

 ## 9. 前端改造方案

-建议在现有通用页面之外新增业务页面，避免混杂。
+### 9.1 已有页面（确认现状）

-### 9.1 新增页面
+| 页面/功能 | 状态 |
+|-----------|------|
+| Unit 列表（含 CRUD Modal） | ✅ 基础实现 |
+| 事件列表 | ✅ 基础实现 |
+| 设备列表（含 Unit 归属绑定） | ✅ 实现 |
+| 点位绑定（equipment/signal_role） | ✅ 实现 |
+| 趋势图 | ✅ 实现 |

- 单元总览页
- 单元详情页
- 设备控制面板
- 事件记录页
- 报警页
- 参数配置页
+### 9.2 待新增页面/功能

-### 9.2 单元总览页内容
-
-每个 `unit` 展示：
-
- 单元名称
- 自动/手动状态
- 当前状态机状态
- 投煤器运行状态
- 布料机运行状态
- 当前累计运行时间
- 故障锁定状态
- 通讯状态
-
-并提供按钮：
-
- 启动自动
- 停止自动
- 故障确认/解除锁定
-
-### 9.3 设备控制页内容
-
-针对单台投煤器/布料机提供：
-
- REM/RUN/FLT/Q/II 实时显示
- 启动按钮
- 停止按钮
+**设备控制面板**（单台投煤器/布料机）：
+- REM / RUN / FLT / Q / II 实时显示
+- 启动 / 停止按钮（灰化逻辑：comm_locked / fault_locked / manual_ack_required）
 - 通讯异常、故障锁定提示
- 最近事件
+- 最近控制事件

-### 9.4 趋势、事件与报警
+**单元总览**（Unit 卡片增强）：
+- 当前状态机状态（STOPPED / RUNNING / DISTRIBUTOR_RUNNING / FAULT_LOCKED / COMM_LOCKED）
+- 自动/手动切换按钮
+- 故障确认按钮（`manual_ack_required == true` 时显示）
+- 累计运行时间进度
+- 投煤器 + 布料机运行状态摘要

-复用已有趋势图能力：
+**参数在线编辑**：
+- 现有 Unit Modal 已有表单
+- 需补充：保存后通知引擎重新加载（或引擎每次 tick 从 DB 读取配置）

- 电流 `II` 趋势
- 运行状态变化曲线
- 事件时间线
+**WebSocket 运行态更新**：
+- 新增 `WsMessage::UnitRuntimeChanged { unit_id, runtime }` 消息类型
+- 前端收到后实时更新 Unit 卡片状态，无需轮询

-后续报警页面基于独立 `alarm` 表实现：
-
- 当前活动报警
- 已确认报警
- 已恢复报警
- 报警确认操作
+---

 ## 10. 分阶段实施建议

-### 第一阶段：最小可用版
+### 第一阶段：补全控制闭环（当前阶段）

-目标：先让系统具备业务闭环，但不追求复杂页面。
+**目标**：让自动控制可以跑起来，故障/通讯保护机制生效。

-内容：
+待完成工作：

- 新增 `unit` 表
- 为 `equipment` 增加 `unit_id`
- 约定设备 `kind` 和点位 `signal_role`
- 新增手动控制接口
- 实现脉冲写入
- 实现故障锁定与通讯冻结
- 实现自动控制状态机
- 基于 `event.rs` 落统一 `event` 表
- 前端增加一个“控制单元”面板和事件列表
+1. **补充运行态检查到 `validator.rs`**
+   - 手动控制时检查 `fault_locked`, `comm_locked`, `manual_ack_required`

-交付后即可验证：
+2. **实现 `control/engine.rs`**
+   - 后台 500ms 轮询任务
+   - 质量检查 → `comm_locked` 更新
+   - FLT 检测 → `fault_locked` 更新
+   - 状态机 tick（STOPPED / RUNNING / DISTRIBUTOR_RUNNING）

- 单台投煤器启停
- 单元级自动启停
+3. **新增接口**
+   - `POST /api/control/unit/{id}/start-auto`
+   - `POST /api/control/unit/{id}/stop-auto`
+   - `POST /api/control/unit/{id}/ack-fault`
+   - `GET /api/unit/{id}/runtime`
+
+4. **扩展 `AppEvent`**
+   - `FaultLocked`, `FaultAcked`, `CommLocked`, `CommRecovered`, `UnitStateChanged`, `AutoControlStarted`, `AutoControlStopped`
+
+5. **WebSocket 运行态推送**
+   - `WsMessage::UnitRuntimeChanged`
+
+6. **前端设备控制面板**
+   - REM/RUN/FLT 展示 + 启停按钮 + 灰化逻辑
+
+7. **前端 Unit 卡片增强**
+   - 状态机状态展示、自动/手动切换、故障确认
+
+交付后可验证：
+- 单台设备手动启停（含故障/通讯拦截）
+- 单元自动定时启停
 - 累计触发布料机运行
- 故障恢复后人工确认
- 关键操作和状态切换可追溯
+- 故障恢复后人工确认才能操作
+- 通讯异常冻结后恢复自动同步

 ### 第二阶段：增强版

-内容：
-
- 单元总览页
- 单元详情页
- 参数在线编辑
- 更丰富的趋势图
- WebSocket 业务事件推送
+- 单元详情页（运行趋势、事件时间线、参数在线编辑）
+- 更丰富的趋势图（电流 II、运行状态变化曲线）
 - 报警规则与 `alarm` 表
 - 报警确认与恢复流程

 ### 第三阶段：现场适配版

-内容：
-
 - 导入导出配置
 - 项目模板
 - 配置校验工具
 - 启停联锁自检
 - 操作权限控制

-## 11. 建议优先落地顺序
+---

-从当前代码基础出发，建议按下面顺序开发：
+## 11. 当前优先落地顺序

-1. 补齐业务数据模型和数据库迁移
-2. 新增 `unit` 表并为 `equipment` 增加 `unit_id`
-3. 规范 `equipment.kind` 与 `point.signal_role`
-4. 实现服务端脉冲写入能力
-5. 实现手动控制接口
-6. 实现 `unit` 自动控制状态机
-7. 扩展 `event.rs` 并实现统一 `event` 表持久化
-8. 实现故障锁定、通讯冻结、人工确认
-9. 增加前端业务页面
-10. 第二阶段再引入独立 `alarm` 表
+从当前代码基础出发，第一阶段建议按下面顺序开发：
+
+1. `validator.rs` 补充运行态检查
+2. `engine.rs` 实现质量检查与 `comm_locked` 更新
+3. `engine.rs` 实现 FLT 检测与 `fault_locked` 更新
+4. `engine.rs` 实现状态机主循环
+5. `handler/control.rs` 新增 `start-auto`, `stop-auto`, `ack-fault`
+6. `handler/control.rs` 新增 `GET /api/unit/{id}/runtime`
+7. 扩展 `AppEvent` 业务事件类型并落库
+8. `websocket.rs` 新增 `UnitRuntimeChanged` 消息
+9. 前端设备控制面板
+10. 前端 Unit 卡片增强
+11. 第二阶段再引入独立 `alarm` 表
+
+---

 ## 12. 对当前代码的具体落点

-基于现有代码，建议主要改动点如下：
+| 文件 | 改动内容 |
+|------|---------|
+| `src/control/engine.rs` | 填充后台轮询任务，实现状态机 tick |
+| `src/control/validator.rs` | 增加运行态检查（fault/comm/ack） |
+| `src/handler/control.rs` | 新增 start-auto, stop-auto, ack-fault, runtime 接口 |
+| `src/event.rs` | 扩展 `AppEvent` 业务事件枚举 |
+| `src/websocket.rs` | 新增 `WsMessage::UnitRuntimeChanged` |
+| `web/js/units.js` | Unit 卡片增加状态机状态、auto 切换、fault ack 按钮 |
+| `web/js/equipment.js` | 增加设备控制面板（REM/RUN/FLT + 启停） |
+| `web/js/app.js` | 绑定新按钮事件，处理 WebSocket 运行态消息 |

- [src/model.rs](D:/projects/plc_control/src/model.rs)
-  - 增加 `ControlUnit` 模型
-  - 为 `Equipment` 增加 `unit_id`
-  - 后续增加 `EventRecord`、`AlarmRecord` 模型
- [src/event.rs](D:/projects/plc_control/src/event.rs)
-  - 扩展 `AppEvent` 业务事件类型
-  - 增加低频关键事件的持久化逻辑
- [src/main.rs](D:/projects/plc_control/src/main.rs)
-  - 注册控制相关路由
-  - 启动控制引擎后台任务
- [src/handler/point.rs](D:/projects/plc_control/src/handler/point.rs)
-  - 保留底层写点接口，不直接承载业务控制
- [src/handler/equipment.rs](D:/projects/plc_control/src/handler/equipment.rs)
-  - 继续作为设备基础资料管理
- [web/index.html](D:/projects/plc_control/web/index.html)
-  - 增加业务控制页面入口或独立面板
- [web/js/app.js](D:/projects/plc_control/web/js/app.js)
-  - 增加控制单元页面事件绑定
+不需要改动的：
+- `src/model.rs`（数据模型完整）
+- `src/control/runtime.rs`（运行态结构体完整）
+- 所有迁移文件（schema 已完整）
+- `src/handler/point.rs`（保留底层写点，不承载业务控制）
+
+---

 ## 13. 本次结论

-当前项目不需要推倒重来，可以直接演进成投煤器与布料机远程监控控制系统。
+当前项目已经完成了业务底座的建设（数据模型、脉冲写入、手动控制、事件持久化、运行态数据结构），具备了较好的基础。

-最合理的路径是：
+下一步核心工作集中在：

- 以现有 OPC UA 与点位平台为底座
- 数据库使用简洁表名 `unit`、`event`
- 代码层保留语义化命名，如 `ControlUnit`、`AppEvent`
- 在 `equipment` 上直接增加 `unit_id`
- 在服务端以内存运行态实现状态机和脉冲控制
- 在现有 [src/event.rs](D:/projects/plc_control/src/event.rs) 上扩展统一事件体系
- 第一阶段先做统一 `event`，第二阶段再拆分独立 `alarm`
+1. **填充 `control/engine.rs`**——这是最核心的缺口，所有自动控制、故障保护、通讯冻结都需要它来驱动
+2. **前端业务控制面板**——让操作员看到并操作设备状态

-如果进入下一步开发，建议先做“第一阶段最小可用版”。
+其余部分（接口、事件、WebSocket）属于连接层，工作量相对可控。