Add heartbeat endpoint message schema

README.md

@@ -179,16 +179,18 @@ h264 分段文件会写到：
 
 ## 上报逻辑
 
-程序向本地管理程序发送：
+推理结果业务包向本地管理程序发送：
 
 ```text
 POST http://127.0.0.1:<upload-port>/video/post
 ```
 
-JSON 结构保持兼容：
+JSON 结构：
 
 ```json
 {
+  "message_type": "inference_result",
+  "schema_version": 1,
   "serial": "camera001",
   "type": 19,
   "at": 1778826272,
@@ -202,7 +204,59 @@ JSON 结构保持兼容：
 }
 ```
 
-当前版本只主动上传 `number > 0` 的正例。目标未检出时不上传 `number=0`，只写日志。
+字段说明：
+
+- `message_type` 固定为 `inference_result`，用于和心跳包区分。
+- `schema_version` 当前为 `1`。
+- `serial` 来自启动参数 `-c`，在管理程序中可作为推理进程身份。
+- `type` 来自启动参数 `-t`。
+- `at` 为推理端当前时间戳。
+- `params[].class_idx` 来自模型目录下 `<model>_code.txt`。
+- `params[].name` 来自模型目录下 `<model>.txt`。
+- `params[].number` 为当前帧同一 `class_idx` 的检测数量；多个 label 映射到同一个 `class_idx` 时会合并数量。
+
+当前版本只主动上传 `number > 0` 的正例。目标未检出时不上传 `number=0`，只写日志。业务包不会承担心跳职责。
+
+## 心跳机制
+
+推理程序新增独立心跳接口：
+
+```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": "camera001",
+  "process_uuid": "camera001",
+  "status": "running",
+  "timestamp": 1778826272
+}
+```
+
+字段说明：
+
+- `message_type` 固定为 `heartbeat`。
+- `schema_version` 当前为 `1`。
+- `serial` 来自启动参数 `-c`，必填且非空。
+- `process_uuid` 同样来自启动参数 `-c`，用于管理程序校验端口对应的推理进程。
+- `status` 当前固定为 `running`。
+- `timestamp` 为推理端当前时间戳。
+
+心跳发送点在解码帧完成 RGA 转换之后、`-P/--time-period` 时间段判断之前。因此即使当前时间段不执行识别，只要程序仍在正常读流解码，也会继续发送心跳。
+
+管理程序建议按以下规则区分：
+
+```text
+/heartbeat + message_type=heartbeat          -> 只刷新心跳，不进入业务判断
+/video/post + message_type=inference_result  -> 推理业务结果
+```
 
 ## G1000 截图通知客户端