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. 端到端业务流程（推荐时序）

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

```mermaid
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 手术生命周期（状态视角）

```mermaid
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 外形一般为：

```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`。