fire_leave_tool/docs/业务逻辑梳理.md

# 动火离人微服务业务逻辑梳理

本文档基于当前代码整理，目标是帮助快速回忆这个微服务现在“实际在做什么”，以及哪些逻辑是设计上存在但当前代码里已经弱化或未真正生效的。

## 1. 项目定位

当前仓库是“动火离人”项目中的微服务管理程序，职责不是前端展示，也不是后端总控，而是：

- 接收后端/平台下发的设备配置
- 为每个设备启动并管理本地推理程序
- 接收推理结果和测温结果
- 按规则判断是否触发报警
- 回溯报警前后视频，拼接并上传
- 通过 WebSocket 将报警事件和数据快照发给后端，再由后端转给前端

整体链路可以理解为：

`前端配置 -> 后端下发配置 -> 微服务启动/管理推理 -> 推理结果回流微服务 -> 微服务判定报警 -> 上传视频 + websocket上报 -> 后端转发前端展示`

## 2. 当前代码里的三类核心进程

每个设备启动时，实际上会拉起 3 条本地能力：

1. `fire_leave` 推理程序
   - 模型参数：`./yolov5 -m model`
   - 主要用途：统计人员数量
   - 结果通过本地 HTTP 服务回传

2. `fire_check` 推理程序
   - 模型参数：`./yolov5 -m fire_check -R`
   - 主要用途：检测火焰
   - 结果通过另一套本地 HTTP 服务回传

3. 测温程序
   - 启动脚本：`./release/run_thermometry.sh`
   - 结果通过本地 TCP 服务回传

也就是说，当前“动火离人”并不是单模型，而是：

- 一套模型做人数量判断
- 一套模型做火焰检测
- 一套测温程序提供温度值

## 3. 配置来源与初始化

### 3.1 启动时配置来源

程序启动后先从 `/usr/local/etc/service.conf` 读取设备配置。

配置结构已经是多设备形式，核心字段包括：

- `device_uuid`
- `task_id`
- `camera_rtsp`
- `camera_ip`
- `confidence`
- `detect_area.fire_leave`
- `detect_area.fire_check`
- `param.fire_leave`
- `param.fire_check`

其中：

- `fire_leave` 检测区给人员检测使用
- `fire_check` 检测区给火焰检测使用
- 两套检测区彼此独立

### 3.2 配置落盘

初始化后，每个设备还会落盘到：

- `/data/devices/device_{deviceUUID}.json`

用于后续读取和状态持久化。

## 4. 每个设备启动时的完整流程

`main.go` 中每个设备会进入 `processDevice()`，当前流程如下：

1. 设备加入全局 `DeviceManager`
2. 为 `fire_leave` 分配一个端口
3. 为 `fire_check` 再分配一个端口
4. 分别启动两个本地 HTTP 接收服务
5. 等待 HTTP `/health` 就绪
6. 把前端配置的检测区域转换成推理程序需要的点串格式
7. 启动 `fire_leave` 推理进程
8. 启动 `fire_check` 推理进程
9. 启动测温程序
10. 等待测温 TCP 服务就绪
11. 创建 TCP 客户端读取温度
12. 进入主循环，持续处理：
   - `fire_leave` 推理结果
   - `fire_check` 推理结果
   - 周期性温度读取和报警判定

## 5. 两条检测链路的当前职责

## 5.1 fire_leave 链路

当前代码里，`fire_leave` 推理结果主要只负责更新人数。

处理逻辑：

- 微服务接收 `/video/post`
- 解析 `params`
- 找 `ClassIdx == 1`
- 将 `Number` 作为当前人数 `PersonCount`
- 写回设备状态

也就是说，当前“离人”判断本身不是由模型直接报“报警/不报警”，而是：

- 模型只提供人数
- 微服务结合温度再做二次判定

## 5.2 fire_check 链路

当前代码里，`fire_check` 推理结果专门负责火焰报警。

处理逻辑：

- 微服务接收 `fire_check` 的 `/video/post`
- 遍历结果
- 当 `ClassIdx == 0 && Number > 0` 时，认为检测到火焰
- 连续满足 `detection_time` 秒后触发火焰报警

火焰报警完全独立于“无人 + 高温”逻辑，不依赖温度和人数。

## 6. 动火离人报警的当前判定逻辑

这是你现在代码里的主报警逻辑，运行在定时器分支里，每 2 秒检查一次。

### 6.1 输入条件

判定使用两个实时量：

- `PersonCount == 0`
- `Temperature > TemperatureThreshold`

其中温度还做了一个简化的防抖：

- 高于阈值 `+0.5`：稳定超温
- 低于阈值 `-0.5`：稳定未超温
- 落在中间：按当前是否大于阈值判断

### 6.2 触发条件

只有同时满足以下条件才会计时：

- 无人
- 温度超阈值

满足后开始累计持续时间，达到 `DetectionTime` 后触发报警。

默认值：

- `DetectionTime` 默认 `20` 秒
- `AlarmTime` 默认 `300` 秒

### 6.3 冷却时间

报警触发后会进入冷却：

- `AlarmPauseUntil = now + AlarmTime`

冷却期内，即使条件继续满足，也不会重复触发。

### 6.4 当前本质

当前“动火离人报警”实际规则可以概括成一句话：

`人员检测结果为 0 + 测温超过阈值 + 持续达到设定秒数 -> 触发 fire_leave 报警`

## 7. 火焰检测报警的当前判定逻辑

火焰检测走另一套状态机。

### 7.1 输入条件

- `fire_check` 结果中出现 `ClassIdx == 0 && Number > 0`

### 7.2 持续时间

持续时间取自：

- `deviceData.FireCheckParam.DetectionTime`

默认值：

- 如果没配，默认 `2` 秒

### 7.3 触发结果

持续检测到火焰达到时长后，触发：

- `GlobalReporter.TriggerFireCheckAlarm(deviceData, alarmTime)`

### 7.4 当前本质

当前“火焰检测报警”可以概括成：

`火焰模型连续检测到火焰达到设定秒数 -> 触发 fire_check 报警`

## 8. 报警后做了什么

无论是 `fire_leave` 还是 `fire_check`，触发后总体都会走这几步：

1. 防止同一告警重复处理
2. 去录像目录找报警前后视频
3. 拼接成一个完整 MP4
4. 复制到 `/data/upload`
5. 上传到 Nginx/后端文件接口
6. 通过 WebSocket 上报事件消息
7. 再上报一份数据快照消息

## 9. 视频回溯与拼接逻辑

当前录像目录：

- 普通动火离人视频：`/usr/data/camera/{deviceUUID}`
- 火焰检测视频：`/usr/data/camera/{deviceUUID}_fire_check`

拼接逻辑：

1. 先把报警时间对齐到最近的 10 秒片段
2. 取 `前10秒`、`当前10秒`、`后10秒` 三段视频
3. 如果缺段，会从同目录找最接近的 mp4 作为替代
4. 至少要找到 2 段视频才继续
5. 用 `mp4_merge` 进行拼接
6. 输出到 `/data/upload/{deviceUUID}-{日期-时间}.MP4`

所以当前上报视频本质上是“报警时刻前后约 30 秒的回溯片段”。

## 10. WebSocket 在当前系统里的作用

WebSocket 地址写死为：

- `ws://172.17.0.1:18080/ws`

主要承担 4 件事：

1. 服务注册
2. 订阅平台 topic
3. 接收配置更新
4. 上报事件与数据

### 10.1 启动后注册

启动后会注册一个服务：

- `containerName = fireleave-container`
- `serviceID = fireleave-service-{timestamp}`

### 10.2 订阅的 topic

当前代码里会订阅：

- `/dhlr/alert`
- `/dhlr/forbid_time`

### 10.3 当前业务上真正需要接收的不是设备配置

这里要和“设备配置来源”明确区分。

设备基础配置当前应以本地文件为准：

- `/usr/local/etc/service.conf`

也就是说：

- 摄像头
- 检测区域
- 置信度
- 各类基础参数

这些设备配置不是依赖 WebSocket 实时下发来生效，而是直接读取本地 `service.conf`。

WebSocket 在这块更应该承担的是“控制类消息”的接收，例如：

- 报警暂停时长
- 延迟报警/允许离岗时长
- 声光报警控制

补充说明：

- 当前代码里 `ws_channel.go` 仍保留了把 `publish.data` 解析成 `DeviceData` 并写回本地的逻辑
- 但按你确认后的业务，这部分不应视为当前核心业务链路
- 也就是说，代码现状和业务认知这里存在偏差，文档以你刚确认的业务为准

## 11. 按钮状态控制的当前真实逻辑

这是你提到“有点忘了”的重点之一。

当前 GPIO 按钮监控在 `gpio_monitor` 包里，监听：

- 按钮 GPIO：`111`
- 蜂鸣器 GPIO：`109`

### 11.1 按钮不是启动/停止按钮

当前业务里，按钮按下后不会：

- 启动推理
- 停止推理
- 直接触发报警

按钮的真实业务含义是：

- 临时关闭“人员离开”这一类报警的上报
- 但火焰检测报警仍然保持正常上报

### 11.2 为什么要有这个按钮

这是为了解决现场的特殊用工场景。

例如后厨煲汤：

- 厨师需要很早开始生火
- 但不可能在整个过程中始终守在灶台旁
- 现场管理允许短时间离开
- 如果仍严格套用“动火离人”规则，就会不断产生不符合现场管理实际的报警

所以按钮的业务意义是：

- 在允许短暂离岗的场景下，临时屏蔽人员离开报警
- 同时保留火焰检测能力，避免真正的火焰风险漏报

### 11.3 按钮按下后的目标行为

按你的描述，正确业务应该是：

- `fire_leave` 报警在暂停窗口内不再上报
- `fire_check` 报警仍然是每次检测到火焰后都正常上报

### 11.4 当前代码和目标业务的偏差

当前代码里，按钮实际上是在切换 `reporter` 里的事件周期状态：

- `fire_leave`
- `fire_check`

并带有：

- 200ms 去抖
- 5 秒冷却

但这和你描述的真实业务目标并不一致。

也就是说：

- 现在代码实现的是“事件周期切换”
- 你要的业务其实是“人员离开报警进入暂停期”

这部分应视为待修正逻辑。

## 12. 蜂鸣器逻辑

蜂鸣器不由本地报警自动触发，而是来自平台 topic：

- 订阅 `/dhlr/alert`

收到消息后，如果内容里的：

- `type == 1`

则触发本地蜂鸣器响指定秒数，默认 3 秒。

所以当前蜂鸣器逻辑是：

- 平台推送声光报警命令
- 微服务本地点响 GPIO109

不是“本地一检测到报警就必然自己响”。

## 13. `/dhlr/forbid_time` 的真实业务目标与当前问题

按你刚补充的业务，这个 topic 的核心作用不是“事件周期切换”，而是：

- 当前端在按钮按下后，下发一个“允许人员短暂离开”的暂停时长
- 微服务收到后，进入一个人员离开报警暂停窗口
- 在这个窗口内，即使检测到人员离开，也不要触发 `fire_leave` 上报
- 但 `fire_check` 火焰报警仍然要照常上报

### 13.1 真实业务目标

`/dhlr/forbid_time` 应该承载的是：

- 暂停人员离开报警的时长
- 或与之等价的延迟/禁止上报控制

### 13.2 当前代码现状

当前代码收到 `/dhlr/forbid_time` 后，主要做的是：

1. 保存 `minute` 到 `/data/cache/forbid_time_config.json`
2. 保存 `fire_leave_timeout` / `fire_check_timeout` 到 `/data/cache/event_cycle_timeout.json`
3. 继续服务于 `reporter` 里的事件周期逻辑

### 13.3 当前存在的问题

这和你描述的真实业务不一致，问题点在于：

- 订阅逻辑没有真正控制 `fire_leave` 报警暂停窗口
- 没有把“按钮触发的允许离岗时长”落到主报警判定里
- 暂停期内是否跳过 `fire_leave` 上报，当前主流程没有真正接进去
- `fire_check` 与 `fire_leave` 的差异化处理没有按这个业务目标落地

### 13.4 应有的目标行为

这部分后续应改成：

1. 前端按钮按下
2. 后端通过 `/dhlr/forbid_time` 下发暂停时长
3. 微服务记录 `fire_leave` 报警暂停截止时间
4. 在暂停窗口内：
   - 人员离开检测继续运行
   - 但不触发 `fire_leave` 报警上报
5. 火焰检测逻辑不受影响，继续正常上报

## 14. 推理程序保活与异常恢复

代码里做了基础保活。

### 14.1 心跳来源

每次推理程序向本地 `/video/post` 发结果时，都会更新一次心跳时间。

也就是说：

- 心跳不是单独接口
- 心跳就是“推理结果持续回传”

### 14.2 超时判断

如果超过 `85` 秒没有收到某个推理程序的数据，就认为需要重启。

主循环每 `30` 秒检查一次：

- `fire_leave`
- `fire_check`

如果超时，则：

1. 杀掉旧进程
2. 复用原端口重启 `yolov5`
3. 立即刷新心跳

## 15. 当前代码里值得特别记住的几个事实

### 15.1 动火离人报警不是“火焰+离人”

当前代码里 `fire_leave` 报警依赖的是：

- 无人
- 温度超阈值

不是火焰检测结果。

### 15.2 火焰报警是完全独立的第二条链路

`fire_check` 只看火焰检测结果，单独触发 `fire_check` 级别事件。

### 15.3 两套检测区域是独立配置

- `FireLeaveDetectArea`
- `FireCheckDetectArea`

前端可以分别配置。

### 15.4 前端参数里真正参与当前判定的关键值

动火离人链路：

- `param.fire_leave.detection_time`
- `param.fire_leave.temperature_threshold`
- `param.fire_leave.alarm_time`
- 人数结果来自 `fire_leave` 模型

火焰链路：

- `param.fire_check.detection_time`
- 火焰结果来自 `fire_check` 模型

### 15.5 置信度当前是共用的

当前两个 `yolov5` 进程启动时都使用：

- `deviceData.Confidence`

没有看到两套模型分别使用不同置信度字段的实现。

## 16. 结合当前代码后的业务总结

如果用最贴近当前实现的话来概括：

- 前端负责配置设备、检测区和阈值
- 后端负责配置转发、消息汇总和给前端展示
- 微服务负责拉起两套推理和一套测温程序
- `fire_leave` 模型负责人数统计
- 测温程序负责温度
- 微服务把“无人 + 超温 + 持续时长”判定为动火离人报警
- `fire_check` 模型负责火焰检测
- 微服务把“持续检测到火焰”判定为火焰报警
- 两类报警都会回溯视频、上传视频、再通过 WebSocket 上报后端

## 17. 当前代码里可能需要你后续再确认的点

这几项不是我猜测，而是从代码现状看出来“可能存在设计与实现不完全一致”的地方：

1. `ConfigUpdateChan` 已有生产者，但未看到消费者
   - 说明配置热更新链路可能没做完，或在当前仓库外

2. GPIO 按钮当前实现的是事件周期切换，但真实业务需要的是“暂停 fire_leave 上报”
   - 说明这部分现在是实现偏差，不只是保留能力

3. `/dhlr/forbid_time` 当前没有真正接入 `fire_leave` 报警暂停控制
   - 说明“按钮按下后允许短时离岗”的核心业务还没真正落地

4. `fire_leave` 的 `person_count` 参数没有直接用于报警判断
   - 当前代码写死判断 `PersonCount == 0`
   - 如果业务上原本支持“少于 N 人也报警”，那这部分目前没有实现

5. `param.fire_leave.confidence` 与 `param.fire_check.confidence`
   - 配置结构里有
   - 但实际启动命令仍统一使用 `deviceData.Confidence`

---

如果后面你继续描述前端和后端的预期业务，我可以再基于这份文档继续补一版“设计业务逻辑 vs 当前代码实现差异”文档，专门帮你找现在代码和你脑中业务之间的偏差。