Add heartbeat endpoint message schema

docs/2026-07-06-heartbeat-and-message-type.md

@@ -0,0 +1,91 @@
+# 2026-07-06 修改记录
+
+## 推理程序心跳
+
+新增独立心跳上报：
+
+```text
+POST http://127.0.0.1:<upload-port>/heartbeat
+```
+
+心跳只在启动参数指定了有效 `-p <upload-port>`，且 `-c <processUUID>` 非空时发送。当前发送周期沿用 `HEARTBEAT_SECS = 60`。
+
+心跳包结构：
+
+```json
+{
+  "message_type": "heartbeat",
+  "schema_version": 1,
+  "serial": "<processUUID>",
+  "process_uuid": "<processUUID>",
+  "status": "running",
+  "timestamp": 1778826272
+}
+```
+
+其中 `serial` 和 `process_uuid` 都来自启动参数 `-c`。例如 `fire_check` 进程应传入 `deviceUUID_fire_check`。
+
+心跳发送点放在解码帧完成 RGA 转换之后、时间段判断之前。因此即使 `-P/--time-period` 当前不执行识别，只要推理程序仍在读流解码，也会继续刷新心跳。
+
+## 推理结果业务包
+
+业务结果仍然走原接口：
+
+```text
+POST http://127.0.0.1:<upload-port>/video/post
+```
+
+本次只新增顶层区分字段，不改变原有业务字段：
+
+```json
+{
+  "message_type": "inference_result",
+  "schema_version": 1,
+  "serial": "<processUUID>",
+  "type": 19,
+  "at": 1778826272,
+  "params": [
+    {
+      "class_idx": 1,
+      "name": "person",
+      "number": 1
+    }
+  ]
+}
+```
+
+管理程序可按以下规则区分：
+
+```text
+/heartbeat + message_type=heartbeat          -> 只刷新心跳
+/video/post + message_type=inference_result  -> 业务推理结果
+```
+
+## 未修改内容
+
+- 未修改识别阈值、workspace 过滤、类别判断、NMS、模型后处理逻辑。
+- 未修改 `/video/post` 中 `serial/type/at/params` 原有字段含义。
+- 未恢复旧的 `number=0` 心跳业务包。
+- 当前推理程序缓存文件仍是 `.h264`，没有改成 `.mp4`。
+
+## mp4-merge 代码确认
+
+已查看本地 `mp4-merge/` 源码。该项目是 MP4 box 级合并工具，依赖输入文件已有 `moov/mdat/stbl` 等 MP4 容器结构，当前不能直接合并裸 `.h264`。
+
+如果要支持 `.h264`，推荐在 `mp4-merge` 命令入口增加预处理：
+
+```text
+.h264 -> ffmpeg 无损封装为临时 .mp4 -> 复用现有 join_files 合并
+```
+
+不建议直接在现有 MP4 box 合并逻辑里解析裸 H264。
+
+## 构建验证
+
+已使用 WSL + Linaro 交叉编译通过，生成产物：
+
+```text
+C:\Users\Smos.DESKTOP-6MT98U8\Desktop\yolov5-inference\build-aarch64\yolov5
+```
+
+构建输出为 ARM aarch64 ELF。构建过程中出现 Windows/WSL 时间戳导致的 `Clock skew` warning，但目标文件已成功生成。