operating-room-monitor-server/docs/video-backends.md

# 视频双后端说明（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** 映射：
  - `**OR_SITE_CONFIG_JSON_FILE**`（推荐）：UTF-8 JSON 文件，**仅支持**站点对象：`{"video_rtsp_urls":{...},"voice_or_room_bindings":[...]}`。根级只允许这两个键；`voice_or_room_bindings` 可为 `[]`。见 `[app/resources/or_site_config.sample.json](../app/resources/or_site_config.sample.json)`。服务每次解析映射时会重新读文件，便于联调覆盖 `video_rtsp_urls`。
  - `**VIDEO_RTSP_URL_TEMPLATE**`（可选）：单模板字符串，可用 `{camera_id}`；在 `video_rtsp_urls` 未给出某路时使用。
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`（默认），在**无法加载动态库**、**登录失败**或**未配置凭据**时，自动回退到 **OR 站点配置**中的 `video_rtsp_urls` 或 `VIDEO_RTSP_URL_TEMPLATE` 拉流。

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

## 推理与结果查询

- 开录后按 `VIDEO_INFERENCE_INTERVAL_SEC` 抽帧，依次调用耗材分类与撕扯动作模型。
- **候选耗材清单**（`candidate_consumables`）：非空时**仅**清单内名称参与自动记账与待确认；**缺省或 `[]`** 时，用 `consumable_classifier_labels.yaml` 的 **全部类名**作为候选；yaml 无有效 `names` 时用分类模型**全部类名**。
- 当分类 Top1 置信度 **≥** `VIDEO_AUTO_CONFIRM_CONFIDENCE`（**默认 0.9**）且标签在候选清单内时，自动写入一条 `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」一节。