feat: surgery pipeline API, video inference, voice confirm, and tests

- Add FastAPI routes for surgery start/end, results, pending confirmation (WAV upload), and health checks.
- Implement RTSP/Hikvision capture, consumable classification, session manager, MinIO/Baidu voice resolution, and DB persistence.
- Add documentation (client API, video backends, staging checklist) and sample camera/RTSP config.
- Add pytest suite (API contract, session manager, voice, repositories, pipeline persistence) and httpx dev dependency.
- Replace deprecated HTTP_422_UNPROCESSABLE_ENTITY with HTTP_422_UNPROCESSABLE_CONTENT.
- Fix SurgeryPipeline DB reads to use an explicit transaction with autobegin disabled.

Made-with: Cursor

.env.example

@@ -1,8 +1,94 @@
-# Copy to .env and adjust. Used by local `start.sh` and Docker Compose.
+# Copy to `.env` and adjust. Loaded by pydantic-settings (field names → UPPER_SNAKE_CASE env vars).
+# Used by local `start.sh` and Docker Compose. See also docs/video-backends.md.
 
+# --- PostgreSQL ---
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
 POSTGRES_DB=operation_room
+POSTGRES_HOST=localhost
+POSTGRES_PORT=35432
 
-# Async SQLAlchemy URL (asyncpg). For local dev against docker-compose.dev.yml:
-DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/operation_room
+# Optional: full async SQLAlchemy URL (overrides POSTGRES_* when set and matches defaults logic — see Settings).
+# DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:35432/operation_room
+
+# --- YOLO inference (internal, not exposed as HTTP) ---
+# Weights default to bundled paths under app/resources/ if unset.
+# CONSUMABLE_CLASSIFIER_WEIGHTS=/absolute/path/to/consumable_classifier.pt
+CONSUMABLE_CLASSIFIER_IMGSZ=224
+CONSUMABLE_CLASSIFIER_DEVICE=
+CONSUMABLE_CLASSIFIER_TOPK=5
+# TEAR_ACTION_WEIGHTS=/absolute/path/to/tear_action.pt
+TEAR_ACTION_IMGSZ=224
+TEAR_ACTION_DEVICE=
+TEAR_ACTION_TOPK=5
+# Device: empty → auto (macOS MPS if available; Linux CUDA if available). Docker image uses CPU torch unless you change it.
+
+# --- Surgery recording API retries ---
+# SURGERY_RECORDING_MAX_ATTEMPTS=3
+# SURGERY_RECORDING_RETRY_DELAY_SECONDS=1.0
+
+# --- Video: RTSP + optional Hikvision HCNetSDK (Linux x86_64 + glibc recommended) ---
+# Client `camera_ids` must match keys in your RTSP map (sample IDs: or-cam-01, or-cam-02).
+#
+# VIDEO_DEFAULT_BACKEND=rtsp
+# Values: rtsp | hikvision_sdk | auto  (auto: SDK .so loaded and HIKVISION_SDK_ENABLED=true → prefer SDK)
+#
+# Per-camera backend override (JSON object):
+# VIDEO_CAMERA_BACKEND_OVERRIDES_JSON={"or-cam-01":"rtsp","or-cam-02":"hikvision_sdk"}
+#
+# RTSP URL resolution (first match wins per camera_id):
+# 1) VIDEO_RTSP_URLS_JSON_FILE — JSON file: {"or-cam-01":"rtsp://...","or-cam-02":"rtsp://..."}
+# 2) merged with VIDEO_RTSP_URLS_JSON (inline JSON string; overrides same keys from file)
+# 3) else VIDEO_RTSP_URL_TEMPLATE with {camera_id}
+# Example file (committed): app/resources/camera_rtsp_urls.sample.json
+# VIDEO_RTSP_URLS_JSON_FILE=app/resources/camera_rtsp_urls.sample.json
+# In Docker (WORKDIR /app): VIDEO_RTSP_URLS_JSON_FILE=/app/app/resources/camera_rtsp_urls.sample.json
+# WARNING: if VIDEO_RTSP_URLS_JSON_FILE is set but the path is missing, the app will fail to start.
+#
+# VIDEO_RTSP_URL_TEMPLATE=rtsp://user:pass@192.168.1.64:554/Streaming/Channels/101
+# VIDEO_RTSP_URLS_JSON={"or-cam-01":"rtsp://user:pass@192.168.1.101:554/Streaming/Channels/101","or-cam-02":"rtsp://user:pass@192.168.1.102:554/Streaming/Channels/101"}
+#
+# VIDEO_OPEN_TIMEOUT_SEC=15
+# 连续读帧失败次数达到阈值后释放 RTSP 并重连。
+# VIDEO_READ_FAILURE_RECONNECT_THRESHOLD=15
+# VIDEO_RECONNECT_BACKOFF_SECONDS=1.0
+# VIDEO_INFERENCE_INTERVAL_SEC=2
+# VIDEO_INFERENCE_CONFIDENCE_THRESHOLD=0.35
+# 置信度 >= 此值且命中候选清单时自动记账（vision）。
+# VIDEO_AUTO_CONFIRM_CONFIDENCE=0.55
+# 置信度处于 [VIDEO_VOICE_CONFIRM_MIN_CONFIDENCE, VIDEO_AUTO_CONFIRM_CONFIDENCE) 时入队待确认（客户端拉取 pending-confirmation）。
+# VIDEO_VOICE_CONFIRM_MIN_CONFIDENCE=0.35
+# 是否启用低置信度人工确认（客户端播报 + resolve 回传；服务端无麦克风/扬声器要求）。
+# VOICE_CONFIRMATION_ENABLED=true
+# VIDEO_VOICE_CONFIRM_DOCTOR_ID=voice
+# （已弃用）服务端本机录音 / ffmpeg 音频输入；当前闭环不依赖。
+# VOICE_RECORD_SECONDS=5
+# VOICE_FFMPEG_INPUT=
+# 停录后写库失败时，后台重试落库间隔（秒）。
+# ARCHIVE_PERSIST_RETRY_INTERVAL_SECONDS=30
+# VIDEO_DETAIL_COOLDOWN_SEC=15
+# VIDEO_JPEG_QUALITY=85
+# VIDEO_RESULT_DOCTOR_ID=vision
+
+# --- Hikvision: mount vendor Linux x86_64 .so at runtime (do not commit proprietary binaries) ---
+# HIKVISION_LIB_DIR=/opt/hikvision/lib
+# Optional: single library path (overrides directory search in code)
+# HIKVISION_LIB_PATH=
+# HIKVISION_SDK_ENABLED=false
+# HIKVISION_DEVICE_IP=
+# HIKVISION_DEVICE_PORT=8000
+# HIKVISION_USER=
+# HIKVISION_PASSWORD=
+# HIKVISION_CHANNEL=1
+# After SDK login, OpenCV still pulls frames via RTSP; template placeholders: {ip} {user} {password} {channel} {camera_id}
+# HIKVISION_PREVIEW_RTSP_TEMPLATE=rtsp://{user}:{password}@{ip}:554/Streaming/Channels/101
+# Per-camera RTSP when using SDK path (same shape as VIDEO_RTSP_URLS_JSON):
+# HIKVISION_CAMERA_RTSP_URLS_JSON={"or-cam-01":"rtsp://...","or-cam-02":"rtsp://..."}
+# HIKVISION_SDK_FALLBACK_TO_RTSP=true
+
+# --- Baidu Speech（可选，遗留；当前手术闭环由客户端完成 TTS/ASR，服务端可不配置）---
+# BAIDU_SPEECH_APP_ID=
+# BAIDU_SPEECH_API_KEY=
+# BAIDU_SPEECH_SECRET_KEY=
+# BAIDU_SPEECH_CONNECTION_TIMEOUT_MS=
+# BAIDU_SPEECH_SOCKET_TIMEOUT_MS=