# 视频双后端说明（RTSP / 海康 HCNetSDK）

## 目标容器

- **推荐**：`Linux x86_64` + **glibc**（与当前 `python:3.13-slim-bookworm` 一致）。
- **不推荐**：Alpine（musl）加载海康预编译 `.so` 往往失败。
- 镜像已安装 **ffmpeg** 与 OpenCV 常用系统库，便于 `cv2.VideoCapture(..., cv2.CAP_FFMPEG)` 拉 RTSP。

## RTSP 模式（默认）

1. 配置 **`camera_id` → RTSP URL** 映射，任选其一或组合使用：
   - **`VIDEO_RTSP_URLS_JSON_FILE`**：指向 UTF-8 JSON 文件（对象键为与请求一致的 `camera_id`）。仓库示例：[`app/resources/camera_rtsp_urls.sample.json`](../app/resources/camera_rtsp_urls.sample.json)（示例 ID：`or-cam-01`、`or-cam-02`）。
   - **`VIDEO_RTSP_URLS_JSON`**：内联 JSON 字符串；与文件合并时**覆盖同键**。
   - **`VIDEO_RTSP_URL_TEMPLATE`**：单模板，可用 `{camera_id}`。
2. 调用 `POST /client/surgeries/start` 时，`camera_ids` 必须能在上述配置中解析出 RTSP 地址。
3. **开录确认**：每路摄像头在超时内成功打开并读到**首帧**后，才认为该路已开录。

## 海康官方 SDK 模式（可选）

SDK **不作为构建期依赖**：将厂商提供的 Linux x86_64 动态库挂载到容器内（例如 `/opt/hikvision/lib/libhcnetsdk.so`），并设置：

- `HIKVISION_SDK_ENABLED=true`
- `HIKVISION_DEVICE_IP` / `HIKVISION_USER` / `HIKVISION_PASSWORD`（以及可选端口）
- `HIKVISION_PREVIEW_RTSP_TEMPLATE` 或 `HIKVISION_CAMERA_RTSP_URLS_JSON`：登录成功后仍通过 **RTSP** 取帧送模型（与常见部署一致：SDK 负责设备会话，码流仍走 RTSP）。

行为概要：

1. 进程内对 `NET_DVR_Init` 使用引用计数；每路使用 SDK 的工作线程在登录后 `NET_DVR_Logout`，线程结束时配对 `NET_DVR_Cleanup`。
2. 若 `HIKVISION_SDK_FALLBACK_TO_RTSP=true`（默认），在**无法加载动态库**、**登录失败**或**未配置凭据**时，自动回退到 `VIDEO_RTSP_*` 映射拉流。

**注意**：`NET_DVR_Login_V30` 的设备信息结构体在不同 SDK 版本上可能存在差异；若登录异常，请优先使用 RTSP 回退或按厂商文档校对 ctypes 绑定。

## 推理与结果查询

- 开录后按 `VIDEO_INFERENCE_INTERVAL_SEC` 抽帧，依次调用耗材分类与撕扯动作模型。
- **候选耗材清单**（开始手术请求体中的 `candidate_consumables`）为**硬约束**：若为空，服务端**不会**写入任何消耗明细（仅拉流推理）；非空时仅允许清单内标签自动记账。
- 当分类 Top1 置信度 ≥ `VIDEO_AUTO_CONFIRM_CONFIDENCE` 且标签在候选清单内时，自动写入一条 `source=vision` 的消耗明细。
- 置信度在 \[`VIDEO_VOICE_CONFIRM_MIN_CONFIDENCE`, `VIDEO_AUTO_CONFIRM_CONFIDENCE`\) 且存在可向医生展示的候选时，会生成一条**待确认**任务（不阻塞后续帧）；客户端通过 `GET /client/surgeries/{surgery_id}/pending-confirmation` 拉取话术并播报，确认后 `POST .../pending-confirmation/{id}/resolve`。
- 已有至少一条消耗明细后，`GET /client/surgeries/{surgery_id}/result` 返回 200；若已开录但尚未产生任何明细，返回 503 `RESULT_NOT_READY`。
- 同类物品写入受 `VIDEO_DETAIL_COOLDOWN_SEC` 节流。
- RTSP 读帧连续失败达到 `VIDEO_READ_FAILURE_RECONNECT_THRESHOLD` 时会 `release` 并尝试重连，间隔 `VIDEO_RECONNECT_BACKOFF_SECONDS`。

## 相关环境变量

详见仓库根目录 `.env.example` 中「视频：RTSP + 可选海康 HCNetSDK」一节。