operating-room-monitor-server/docs/client-api-integration.md

手术室监控服务 — 客户端 HTTP API 对接说明

本文档面向集成我方 FastAPI 后端的客户系统（HIS、手麻、护理工作站、自研终端等），说明如何通过 HTTP 调用完成「手术开始 / 结束」「耗材结果查询」「低置信度耗材语音确认」等能力。

说明：仓库内 scripts/demo_client/ 等演示页面仅用于内部联调与测试，不代表生产对接规范；生产环境请按本文档与 OpenAPI 契约自行实现客户端。

---

1. 服务与发现

项目	说明
默认监听	应用默认 0.0.0.0:38080（以实际部署为准，可能经反向代理改写路径或端口）
基础路径	路由无全局前缀；下文路径均为相对服务根路径
OpenAPI	服务启动后可访问 **/docs（Swagger UI）、**/redoc 获取实时 Schema 与试调
健康检查	GET /health：探活与数据库连通性（降级时可能返回 503）
跨域 CORS	仅当服务端开启演示用 CORS 配置时对浏览器页面生效；服务端对接通常不受 CORS 限制

认证方式以部署约定为准；当前公开路由未在文档层强制 API Key，若贵方环境增加了网关鉴权，请在请求头中按网关要求携带。

---

2. 客户端 API 一览（/client/...）

所有「客户集成」接口均位于 **/client** 命名空间下。

方法	路径	摘要
POST	/client/surgeries/start	开始手术：确认摄像头开录成功后返回
POST	/client/surgeries/end	结束手术：确认停录成功后返回
GET	/client/surgeries/{surgery_id}/result	查询该台手术的耗材明细与汇总
GET	/client/surgeries/{surgery_id}/pending-confirmation	拉取一条待确认项（含 TTS 音频 Base64）
POST	/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve	上传医生语音 WAV，完成确认或否认

路径参数 **surgery_id**：固定 6 位数字（正则 ^\d{6}$）。

---

3. 端到端业务流程（推荐时序）

以下为客户系统与手术室监控服务之间的推荐调用顺序与并行关系。

sequenceDiagram
    participant Client as 客户系统
    participant API as 监控服务 API

    Client->>API: POST /client/surgeries/start
    Note over Client,API: body: surgery_id, camera_ids, candidate_consumables
    API-->>Client: 200 accepted（开录已确认）

    par 术中轮询
        loop 按需轮询
            Client->>API: GET .../result
            API-->>Client: 200 明细+汇总 或 503 RESULT_NOT_READY
        end
        loop 语音确认闭环（若启用）
            Client->>API: GET .../pending-confirmation
            API-->>Client: 200 待确认+MP3 或 404 无待确认
            opt 有待确认
                Client->>Client: 播放 prompt_audio_mp3_base64
                Client->>API: POST .../resolve（multipart audio）
                API-->>Client: 200 accepted
            end
        end
    end

    Client->>API: POST /client/surgeries/end
    API-->>Client: 200 accepted（停录已确认）

    Client->>API: GET .../result
    API-->>Client: 200 归档后持久化结果（若可查）

3.1 手术生命周期（状态视角）

flowchart LR
    A[未开始] -->|POST start 成功| B[录制中 / 推理中]
    B -->|GET result 可 200| C[可查消耗]
    B -->|GET pending 可 200| D[有待确认]
    D -->|POST resolve| B
    B -->|POST end 成功| E[已结束]
    E -->|GET result| C

---

4. 接口说明与请求/响应要点

4.1 POST /client/surgeries/start

Content-Type：application/json

请求体（摘要）

字段	类型	说明
surgery_id	string	6 位数字手术号
camera_ids	string[]	至少 1 个；需与贵方 RTSP/SDK 映射中的 摄像头 ID 一致
candidate_consumables	string[]	可选；本台手术可能用到的耗材名称清单。服务端仅对该清单内耗材做自动记账与待确认追问；为空则只做拉流推理、不写入消耗

成功（200）：SurgeryApiResponse — status 一般为 accepted，表示服务端已确认开录完成。

失败：常见 **503 Service Unavailable，detail 内含业务 code（如录制子系统未就绪、开录未确认等）。开录/停录类错误会按服务端配置自动重试**；仍失败则返回最后一次错误信息。

4.2 POST /client/surgeries/end

Content-Type：application/json

请求体：{ "surgery_id": "123456" }

成功（200）：停录已确认。

失败：503 同 start，表示未能在确认摄像头全部停录后完成请求。

4.3 GET /client/surgeries/{surgery_id}/result

幂等只读。术中返回当前内存已记账结果；结束后返回数据库持久化结果（以服务端实现为准）。

成功（200）：SurgeryResultResponse

• details：多行消耗明细，字段顺序为 **item_id → item_name → qty → doctor_id → timestamp**
• summary：按 item_id 汇总的 total_quantity

**503**：detail.code === "RESULT_NOT_READY" — 尚无该手术可查询结果（未开始、未成功开录或暂无可返回数据）。

4.4 GET /client/surgeries/{surgery_id}/pending-confirmation

用于低置信度识别的人工确认闭环（需服务端启用语音确认及相关配置）。

成功（200）：包含 confirmation_id、prompt_text、候选项 options、prompt_audio_mp3_base64（与话术一致的 MP3 标准 Base64，无换行）、模型 Top1 等。

**404**：当前无待确认或手术未在进行（NO_PENDING_CONFIRMATION）。

**422 / 503**：话术为空、音频无效、ASR/TTS/MinIO/百度语音等异常时返回，详见响应 detail.code。

4.5 POST /client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve

Content-Type：multipart/form-data

表单字段

字段	说明
audio	单个 **.wav** 文件；建议 16 kHz 单声道 PCM；其他格式服务端可能尝试 ffmpeg 转码

成功（200）：SurgeryPendingConfirmationResolveResponse — 含 resolved_label、rejected、asr_text、audio_object_key 等。

常见 HTTP 状态：404（确认项不存在或已失效）、409（已处理）、422（音频/解析问题）、503（外部依赖故障）。

---

5. 错误约定

FastAPI 对 HTTPException 的 JSON 外形一般为：

{
  "detail": {
    "code": "业务错误码",
    "message": "人类可读说明",
    "surgery_id": "123456"
  }
}

部分错误可能在 detail 中附带额外字段（如重试剩余次数），请以实际响应与 OpenAPI 为准。

校验错误（422）：请求体或路径不符合 Pydantic 校验时，FastAPI 可能返回标准 422 验证错误结构（与上表「对象型 detail」不同），请客户端分别解析。

---

6. 与内部演示能力的关系（非客户必选）

以下路由用于内部一键联调，客户生产系统无需依赖：

路径	说明
GET /internal/demo/orchestrator-status	探测演示编排是否开启、RTSP 配置文件是否设置等
POST /internal/demo/orchestrate-and-start	仅在服务端开启 DEMO_ORCHESTRATOR_ENABLED 时注册；用于演示环境串联开录

客户正式对接应直接调用 **/client/...**，并在贵方环境中配置真实的 camera_ids 与视频后端映射。

---

7. 联调建议

1. 先调用 **GET /health** 确认服务与数据库可用。
2. 用 **POST /client/surgeries/start** 验证 camera_ids 与现场 RTSP/SDK 配置一致，避免 503。
3. **candidate_consumables** 与实际手术耗材名称尽量与院内目录或模型标签对齐，减少待确认次数。
4. 结果查询 **503** 时建议退避重试（术中数据尚未就绪属正常现象）。
5. 以 **/docs** 导出或对照契约测试，与贵方 CI 中的契约测试对齐。

---

8. 文档修订

接口行为以部署实例的 OpenAPI（/docs） 与代码为准；字段含义补充见仓库内 app/schemas.py 中各模型的 description。