chore: upload current project state

2026-05-12 15:45:50 +08:00
parent cd9b199e2c
commit 6056b1fdc5
25 changed files with 4051 additions and 373 deletions
@@ -0,0 +1,332 @@
+# 整改计划
+
+日期：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`，也没有看到覆盖关键链路的自动化测试。
+
+### 风险
+
+- 协议层改造、重启链路改造、报警暂停逻辑改造容易引入回归
+
+### 准备怎么改
+
+至少补最小化验证路径。