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 当前代码实现差异”文档，专门帮你找现在代码和你脑中业务之间的偏差。