# 整改计划

日期：2026-05-11

本文档只保留以下内容：

- 当前确认存在的问题和风险
- 对应的修改方案、影响范围和代码落点

执行项已单独整理到 `docs/todo.md`。

## 1. 推理进程重启链路失效

### 问题

当前启动和重启使用了两套不同的端口管理器：

- 启动阶段：`connect.GlobalPortManager`
- 心跳重启阶段：`portmanager.GlobalPortManager`

结果是：

- 初次启动能分到端口
- 心跳超时后重启拿不到原端口
- `yolov5` 重启流程会失败

### 风险

- 推理进程挂掉后无法自恢复
- 设备会长期失去 `fire_leave` / `fire_check` 检测能力

### 准备怎么改

统一端口管理实现，只保留一套端口管理器。

建议方案：

1. 以当前 `main.go` 正在使用的 `connect.GlobalPortManager` 为准，统一所有调用
2. 重写或合并 `connect/heartbeat.go` 中的端口获取逻辑
3. 清理重复的 `portmanager` 包引用，避免两套状态并存

### 需要修改的代码

- `main.go`
- `connect/heartbeat.go`
- `connect/port_manager.go`
- `portmanager/portmanager.go`
- `portmanager/types.go`

## 2. `service.conf` 读写 schema 不一致

### 问题

当前配置读取和写回不是同一套结构：

- `LoadServiceConfig()` 按 `[]ServiceConfig` 读取
- `SaveServiceConfig()` / `SaveSingleServiceConfig()` 按 `[]DeviceData` 写回

### 风险

- WebSocket 或其它更新路径一旦写回配置
- 下次启动可能无法按原 schema 正确读取
- 配置字段可能丢失或错位

### 准备怎么改

统一配置文件模型，明确：

- `service.conf` 是“部署输入配置”
- `device_*.json` 是“运行态持久化”

建议方案：

1. `service.conf` 始终只用 `ServiceConfig` 读写
2. 运行态状态继续写入 `/data/devices/device_{uuid}.json`
3. 如果确实需要从 WebSocket 更新配置，先把 `DeviceData` 映射回 `ServiceConfig` 再写入

### 需要修改的代码

- `connect/device_storage.go`
- `connect/ws_channel.go`

## 3. `fire_leave` 参数映射不完整

### 问题

当前 `fire_leave` 主判定读的是：

- `deviceData.DetectionTime`
- `deviceData.AlarmTime`

但新配置的真实值在：

- `deviceData.FireLeaveParam.DetectionTime`
- `deviceData.FireLeaveParam.AlarmTime`

另外 `person_count`、双模型 `confidence` 也存在未完整映射的问题。

### 风险

- 离岗报警持续时间可能一直用默认值
- 冷却时间可能一直用默认值
- 前端/平台配置和实际行为不一致

### 准备怎么改

在配置初始化阶段统一完成映射，不在运行主循环里到处兜底。

建议方案：

1. `LoadServiceConfig()` 时完成 `param.fire_leave` 到运行字段的转换
2. `ProcessDeviceDataForInference()` 或专门的 normalize 逻辑里统一补齐
3. 后续主循环尽量只读规范化后的字段

### 需要修改的代码

- `connect/device_storage.go`
- `main.go`

## 4. `/dhlr/forbid_time` 还没真正接入 `fire_leave` 暂停上报

### 问题

按当前确认后的业务：

- `/dhlr/forbid_time` 是控制 `fire_leave` 暂停上报窗口
- `fire_check` 仍要继续正常上报

但当前代码主要做的是：

- 缓存 `minute`
- 缓存 `fire_leave_timeout` / `fire_check_timeout`
- 服务于 `reporter` 里的事件周期逻辑

没有真正控制 `fire_leave` 主报警判定。

### 风险

- 按钮按下后，现场期待的“暂时允许离岗”不会真正生效
- 现场仍可能连续收到不符合预期的 `fire_leave` 报警

### 准备怎么改

把 `/dhlr/forbid_time` 从“事件周期配置”改为“主报警暂停窗口控制”。

建议方案：

1. 在设备级状态里增加 `fire_leave` 暂停截止时间
2. 收到 `/dhlr/forbid_time` 后更新这个截止时间
3. 在 `fire_leave` 报警判定前先检查暂停窗口
4. 暂停期内继续更新人数、温度，但跳过 `fire_leave` 上报
5. `fire_check` 保持独立

### 需要修改的代码

- `main.go`
- `reporter/reporter.go`
- `gpio_monitor/gpio_monitor.go`
- 可能涉及 `connect/ws_channel.go` 的控制消息分发

## 5. GPIO 按钮逻辑和真实业务存在偏差

### 问题

当前按钮逻辑更接近“切换事件周期”，而不是“暂停 `fire_leave` 上报”。

### 风险

- 代码行为和现场业务理解不一致
- 后续维护时容易误判

### 准备怎么改

将 GPIO 按钮逻辑收敛为：

- 触发本地允许离岗窗口
- 或配合 `/dhlr/forbid_time` 完成暂停控制

### 需要修改的代码

- `gpio_monitor/gpio_monitor.go`
- `reporter/reporter.go`
- `main.go`

## 6. WebSocket 协议需要整体切换到 protobuf binary frame

### 问题

当前协议层是：

- JSON
- 文本帧
- `method + params + result + error`

目标协议是：

- protobuf
- binary frame
- `REQUEST / REPLY / CAST`

### 风险

- 现有 `ws_channel.go` 不能局部修补
- 如果只改部分字段，会造成协议不兼容

### 准备怎么改

按“先替换协议层，尽量少动业务层接口”的原则改。

建议方案：

1. 保留上层调用接口：
   - `RegisterService`
   - `SubscribeTopic`
   - `SendAsync`
2. 内部把 JSON 封装替换为 protobuf 编解码
3. 下行从 `publish` 改为 `topic_event`
4. 上行从 JSON `metric_data` 改为 `ServiceCast.metric_data`
5. 内层业务 payload 继续保留当前 JSON 结构

### 需要修改的代码

- `connect/ws_channel.go`
- `reporter/reporter.go`
- 可能新增 `connect/pb/` 或 `connect/protocol/`

## 7. 主动 ping 建议保留，失败立即重连

### 问题

如果不主动 ping：

- 死连接发现会变慢
- 空闲连接可能被网络设备静默回收
- 只有下次读写时才发现断连

### 风险

- `/dhlr/alert`
- `/dhlr/forbid_time`
- 事件上报链路

以上三类能力恢复变慢。

### 准备怎么改

继续保留主动 ping。

建议方案：

1. 定时发送 websocket ping frame
2. ping 失败时立即标记断连
3. 触发重连
4. 重连后重新 register / subscribe

### 需要修改的代码

- `connect/ws_channel.go`

## 8. 业务上报仍然是“只发不确认”

### 问题

当前：

- `register`
- `subscribe`

这类请求有协议层确认。

但：

- 报警事件上报
- 数据快照上报

仍然是单向发送。

### 风险

- 只能确认本地是否成功写出 websocket 消息
- 不能确认 efka 是否真正处理成功
- 不能确认上层平台是否真正收到、入库、展示

### 当前处理决定

这一项先不解决，只记录风险。

### 相关代码

- `connect/ws_channel.go`
- `reporter/reporter.go`

## 9. 运行中配置更新链路未闭环

### 问题

当前有：

- `ConfigUpdateChan` 生产者

但没有看到清晰的消费者和热更新执行链路。

### 风险

- 代码让人以为支持实时热更新
- 实际运行中可能并不会生效

### 准备怎么改

先做一次取舍：

- 要么补齐热更新
- 要么明确去掉这条未完成链路

### 需要修改的代码

- `connect/ws_channel.go`
- `main.go`

## 10. 自动化验证不足

### 问题

当前环境没有 `go`，也没有看到覆盖关键链路的自动化测试。

### 风险

- 协议层改造、重启链路改造、报警暂停逻辑改造容易引入回归

### 准备怎么改

至少补最小化验证路径。