# 投煤器布料机远程监控与控制功能实现方案

> 最后更新：2026-03-24（基于当前代码重新审阅）

## 1. 目标

基于当前 `plc_control` 项目，扩展出面向投煤器与布料机的业务化远程监控与控制能力，满足以下目标：

- 实时监控投煤器、布料机运行状态
- 支持远程手动启停
- 支持投煤器自动定时运行
- 支持投煤累计触发布料机自动运行
- 支持故障锁定、人工复位、通讯异常冻结
- 支持通过配置适配不同现场，不改代码完成项目复用

---

## 2. 当前系统能力盘点

### 2.1 通用平台基础（已有）

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

### 2.2 业务模型（已有）

- `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 业务逻辑（已有）

- 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. 推荐实现思路

继续在现有平台上"增量扩展"：

- 现有 `unit` / `equipment` / `point` / `event` 底座不动
- 填充 `control/engine.rs` 实现状态机调度
- 新增自动控制和 ack-fault 接口
- `validator.rs` 增加对运行态的检查
- 扩展 `AppEvent` 业务事件，通过 WebSocket 推送运行态变更
- 前端增加业务控制页面

---

## 5. 命名与模型设计（已落地，确认）

### 5.1 设备分类（`equipment.kind`）

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

### 5.2 点位角色规范（`point.signal_role`）

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

### 5.3 Unit 运行态放内存（已确认）

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

### 5.4 统一 `event` 表，预留 `alarm` 表（已落地）

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

---

## 6. 控制逻辑设计

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

当前已实现：
- `rem == 1` 检查
- `flt == 0` 检查
- 通讯质量检查
- 脉冲写入（300ms）

**待补充**：在 `validator.rs` 中增加对 `ControlRuntimeStore` 的检查：
- `fault_locked == true` → 拒绝
- `comm_locked == true` → 拒绝
- `manual_ack_required == true` → 拒绝（等待人工确认）

### 6.2 自动控制状态机（待实现）

每个 `unit` 独立维护状态机，在 `control/engine.rs` 中以后台任务驱动。

#### `STOPPED`

- 累计停止时间 `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` → 进入 `DISTRIBUTOR_RUNNING`

#### `DISTRIBUTOR_RUNNING`

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

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

任意设备检测到 `FLT == 1`：
- 停止该单元自动控制
- `state = FaultLocked`, `fault_locked = true`
- 发送并持久化 `FaultLocked` 事件

当 `FLT` 从 `1 → 0` 恢复：
- 不自动解锁
- `manual_ack_required = true`
- 等待人工调用 `POST /api/control/unit/{id}/ack-fault`

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

当 OPC UA 质量位异常或连接中断：
- `state = CommLocked`, `comm_locked = true`
- 冻结全部控制动作
- 前端按钮灰化

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

---

## 7. 事件体系设计

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

当前 `AppEvent` 已有：
- `SourceCreate/Update/Delete`
- `PointCreateBatch/PointDeleteBatch`
- `EquipmentStartCommandSent/EquipmentStopCommandSent`
- `PointNewValue`（遥测）

**待扩展**：

```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`、高频遥测、内部轮询过程

---

## 8. 后端改造方案

### 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 完整 |

### 8.2 待新增接口

```
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

### 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
```

### 8.4 手动控制补充运行态检查

在 `control/validator.rs: validate_manual_control()` 中增加：

```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` 三元组 → 业务映射

---

## 9. 前端改造方案

### 9.1 已有页面（确认现状）

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

### 9.2 待新增页面/功能

**设备控制面板**（单台投煤器/布料机）：
- REM / RUN / FLT / Q / II 实时显示
- 启动 / 停止按钮（灰化逻辑：comm_locked / fault_locked / manual_ack_required）
- 通讯异常、故障锁定提示
- 最近控制事件

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

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

**WebSocket 运行态更新**：
- 新增 `WsMessage::UnitRuntimeChanged { unit_id, runtime }` 消息类型
- 前端收到后实时更新 Unit 卡片状态，无需轮询

---

## 10. 分阶段实施建议

### 第一阶段：补全控制闭环（当前阶段）

**目标**：让自动控制可以跑起来，故障/通讯保护机制生效。

待完成工作：

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 卡片增强**
   - 状态机状态展示、自动/手动切换、故障确认

交付后可验证：
- 单台设备手动启停（含故障/通讯拦截）
- 单元自动定时启停
- 累计触发布料机运行
- 故障恢复后人工确认才能操作
- 通讯异常冻结后恢复自动同步

### 第二阶段：增强版

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

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

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

---

## 11. 当前优先落地顺序

从当前代码基础出发，第一阶段建议按下面顺序开发：

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`（数据模型完整）
- `src/control/runtime.rs`（运行态结构体完整）
- 所有迁移文件（schema 已完整）
- `src/handler/point.rs`（保留底层写点，不承载业务控制）

---

## 13. 本次结论

当前项目已经完成了业务底座的建设（数据模型、脉冲写入、手动控制、事件持久化、运行态数据结构），具备了较好的基础。

下一步核心工作集中在：

1. **填充 `control/engine.rs`**——这是最核心的缺口，所有自动控制、故障保护、通讯冻结都需要它来驱动
2. **前端业务控制面板**——让操作员看到并操作设备状态

其余部分（接口、事件、WebSocket）属于连接层，工作量相对可控。