feat: 站点 JSON、语音终端 WebSocket 指派与客户端联调

- 用 OR_SITE_CONFIG_JSON_FILE 统一术间配置（video_rtsp_urls + voice_or_room_bindings）
- VoiceTerminalHub：assignment、WS 推送与 HTTP 查询；开录/停录后 notify
- 一键联调 orchestrate-and-start 与 /client/surgeries/start 共用指派逻辑，修复 demo 路径不发 WS
- 语音桌面端：SIGINT 退出、shutdown 清理、仅 WS 指派、固定 pending 轮询间隔、界面仅保留录音时长
- 新增/调整契约与绑定测试，文档与示例配置同步

Made-with: Cursor

docs/客户端手术通信接口说明.md

@@ -41,8 +41,18 @@ RTSP 地址、账号、口令等由客户端对接工程师提供给服务端运
 | 4      | `GET`  | `/client/surgeries/{surgery_id}/result`                                         | 查询手术结果  |
 | 5      | `GET`  | `/client/surgeries/{surgery_id}/pending-confirmation`                           | 拉取待确认耗材 |
 | 6      | `POST` | `/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve` | 提交医生答复  |
+| 7      | `GET`  | `/client/voice-terminals/{terminal_id}/assignment`                              | 可选：查询当前指派（调试或简易集成；**官方桌面客户端仅用 WebSocket**） |
+| 8      | `WS`   | `/client/voice-terminals/ws?terminal_id=...`                                    | 语音桌面终端长连接，接收开录/停录指派（**推荐**） |
 |        |        |                                                                                 |         |
 
+**术间与语音终端绑定（服务端配置）**
+
+- **唯一配置源**：环境变量 **`OR_SITE_CONFIG_JSON_FILE`** 指向手术室 **站点 JSON**（UTF-8），须同时包含 `video_rtsp_urls` 与 `voice_or_room_bindings`（见仓库 `app/resources/or_site_config.sample.json`）。`voice_or_room_bindings` 为数组，每项含 `or_room_id`、`camera_ids`、`voice_terminal_id`；`camera_ids` 在数组内须唯一，`voice_terminal_id` 全局唯一。
+- **`POST /client/surgeries/start`** 在 **HTTP 200 且开录已成功** 后：用请求体中的 `camera_ids` 在 `voice_or_room_bindings` 中解析终端（**精确匹配**术间 camera 集合，或 **开录路集为某术间 camera 集合的子集** 时匹配该术间）；命中则向对应 `voice_terminal_id` 推送 **`action":"start"`**（并更新 assignment）；未配置站点文件、或数组为空、或未命中则仅打日志，不影响 200。
+- **`POST /client/surgeries/end`** 在停录 **HTTP 200** 后：向该手术会话记录的终端推送 **`action":"end"`**（并清除 assignment）。
+- 推送 JSON 形如：`{"type":"voice_assignment","action":"start"|"end","surgery_id":"123456"}`。
+- **多 worker**：当前实现为进程内内存；多 Uvicorn worker 时需 sticky session 或 Redis 等另行同步。
+
 ## 4. 流程
 
 ### 4.1 时序图
@@ -421,4 +431,27 @@ flowchart LR
 curl -sS -X POST \
   "http://<主机>:38080/client/surgeries/123456/pending-confirmation/<confirmation_id>/resolve" \
   -F "audio=@/path/to/voice.wav;type=audio/wav"
-```
+```
+
+### 5.7 语音终端 assignment（HTTP，可选）
+
+**路径** `GET /client/voice-terminals/{terminal_id}/assignment`
+
+仓库内 **手术室耗材语音确认桌面客户端** 仅通过 **§5.8 WebSocket** 接收指派，**不调用**本接口。此处供运维脚本、未实现 WS 的第三方临时拉取 `active_surgery_id`。
+
+**响应 200**
+
+| **字段** | **类型** | **说明** |
+| -------- | -------- | -------- |
+| `voice_terminal_id` | `string` | 与路径一致 |
+| `active_surgery_id` | `string \| null` | 当前指派手术 6 位号；无指派时为 `null` |
+
+### 5.8 语音终端 WebSocket
+
+**路径** `GET ws://<主机>:<端口>/client/voice-terminals/ws?terminal_id=<终端ID>`（HTTPS 部署时使用 `wss://`）
+
+**说明**
+
+- 连接成功后，若服务端已有该终端的 assignment，会立即收到一条 **`action":"start"`** 的 JSON（与下文推送格式一致）。
+- 术中由服务端在 **`start` / `end` 成功后** 向已连接终端推送 JSON：`{"type":"voice_assignment","action":"start"|"end","surgery_id":"123456"}`。
+- 客户端可发送任意文本作心跳；服务端当前仅依赖 WebSocket 协议级 ping（由网关或客户端库实现）。