# 上传链路修复与项目结构说明

## 本次修改

本次修改目标是让推理程序只负责当前帧识别结果上报，不在推理侧处理抖动、持续时间或漏报补偿。

- 只有 `prop >= conf_threshold` 且目标在 workspace 内，才进入 upload 候选。
- `0.30 <= prop < conf_threshold` 只记录为 `weak_present`，不上传。
- `prop < 0.30` 只记录为 `filtered_low_conf`，不上传。
- 低置信截图功能已停用：`maybe_trigger_low_conf_snapshot` 仍保留在代码中，但当前没有调用点。
- 取消推理侧三帧稳定门槛，抖动和持续时间判断交给管理程序。
- 取消 500ms upload 节流逻辑，当前帧满足上传条件就尝试上报；如果已有上传线程正在运行，则记录 `upload_skip_busy`。
- 保留同一 `class_idx` 的多 label 合并上传逻辑。
- upload 日志保留复查字段：`label`、`number`、`prop`、`box`、`edge_touch`、`left_edge`、`boxes`、`rga`。
- upload busy 状态改为创建线程前预约、线程结束后释放，避免连续帧在上传线程尚未置位前重复创建多个上传线程。

## 命令行与日志

命令行输出恢复为主分支风格，不再受日志采样影响：

- 低于阈值：`skip prop = ... for class ...`
- workspace 内且超过阈值：`in result ...`
- workspace 外：`not in result ...`

日志系统与命令行输出分离：

- `.log` 里的详细检测事件如 `frame_seen`、`strong_present`、`weak_present`、`filtered_workspace`、`filtered_low_conf` 仍按采样策略记录。
- `upload_positive` 和 `upload_positive_payload` 每次真实上传都会记录。
- `edge_touch=1` 表示目标框贴到 640x640 模型输入边界，`left_edge=1` 表示贴左边界；这两个字段只用于复查，不影响上传判断。
- `rga=` 记录最近一次 RGA 输入输出信息，如源宽高、stride、640x640 目标区域和上下填充位置，便于对照 RTSP 现场流和回放视频。
- `frame=` 是推理回调序号，不等同于主循环中的 `handling [N]th frame`。

## 心跳包

管理程序源码已拉到本地 `rk1808-tool/` 用于对照。

当前管理程序的 `/video/post` 入口在 `rk1808-tool/controllers/report.go`，接收 JSON 结构为：

```text
serial
at
type
params[].name
params[].class_idx
params[].number
```

推理程序保留 60 秒本地心跳日志，但不再通过 `/video/post` 上传心跳：

- `HEARTBEAT_SECS = 60`
- 如果 60 秒内没有正例 upload，只记录 `heartbeat_log_only ... upload=0`。
- 心跳不会生成 `heartbeat_payload`，也不会进入 `/video/post`。
- 推理程序禁止主动上传 `number=0`；`upload_info` 也会防御性跳过 `total_number <= 0`。
- 原因：当前 `rk1808-tool` 的 `InsertEvent` 用 `class_idx` 作为全局缓存 key，不区分摄像头；任意摄像头的 `number=0` 都可能取消同一 `class_idx` 的真实事件。

当前这份 `rk1808-tool` 代码里，重启推理程序主要依赖子进程退出后的 `RunAsDaemon` finalizer 触发 `CheckNeedRestart`；未看到独立的“收不到心跳就重启”逻辑。

## 当前项目结构

主要源码：

- `main.cpp`：参数解析、RTSP 读取、视频分段保存、解码主循环。
- `rknn.cpp` / `rknn.h`：推理回调、检测结果过滤、日志、upload 和心跳逻辑。
- `yolov5.cc` / `yolov5.h`：RKNN 模型初始化与推理调用。
- `postprocess.cc` / `postprocess.h`：后处理、label/code 加载。
- `vertix.cpp` / `vertix.h`：workspace 多边形过滤。
- `utils.cpp` / `utils.h`：HTTP JSON 上传、时间工具等。

依赖目录：

- `rknn/`：RKNN 头文件和库。
- `mpp/`：Rockchip MPP 头文件和库。
- `rga/`：RGA 头文件和库。
- `ffmpeg/`：FFmpeg 头文件和库。
- `cjson/`：JSON 处理库。

文档与辅助：

- `docs/cross_compile_wsl_linaro.md`：WSL + Linaro 交叉编译说明。
- `docs/debounce_positive_upload_plan.md`：早期去抖和日志方案记录，仅作历史参考。
- `rk1808-tool/`：本地拉取的管理程序源码，用于对照 `/video/post` 和重启逻辑。

## 构建产物

按 Linaro 路线构建：

```powershell
wsl -d Ubuntu bash -lc "mkdir -p /home/smos/yolov5-linaro-build && cd /home/smos/yolov5-linaro-build && cmake /mnt/c/Users/Smos.DESKTOP-6MT98U8/Desktop/yolov5-inference && make -j16 && file yolov5"
```

当前产物位置：

```text
/home/smos/yolov5-linaro-build/yolov5
```

验证要点：

- 产物是 `ARM aarch64` ELF。
- 链接 `librknn_api.so`。
- 不应出现 `GLIBC_2.33`、`GLIBC_2.34`、`GLIBCXX_3.4.29` 依赖。