kevin/operating-room-monitor-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: align surgery API with schemas and extend client tooling

Browse Source 
- Refactor app API and schemas; adjust surgery pipeline, repository, and session manager.

- Improve consumption TSV logging and consumable vision integration; trim voice resolution.

- Add Baidu Face 1:N search script, .env.example entries, and client API integration doc.

- Update demo client, staging checklist, surgery interface doc, and related tests; add sample face image.

Made-with: Cursor
This commit is contained in:
Kevin
2026-04-23 16:09:20 +08:00
parent 0c05463617
commit 69980d8073
20 changed files with 994 additions and 610 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -7,11 +7,11 @@
## 1. 概述
| 能力 | 说明 |
| ---- | ---------------------------------------------------- |
| 开始手术 | 请求开始手术；服务端启动摄像头录制，**仅在确认开录完成后**返回 HTTP 200。 |
| 结束手术 | 请求结束手术；服务端停止摄像头录制，**仅在确认停录完成后**返回 HTTP 200。 |
| 查询结果 | 根据手术 6 位号查询消耗明细与汇总；**仅在已开录且至少已有一条消耗明细后**返回 HTTP 200。 |
| 能力 | 说明 |
| ----- | ------------------------------------------------------ |
| 开始手术 | 请求开始手术；服务端启动摄像头录制，**仅在确认开录完成后**返回 HTTP 200。 |
| 结束手术 | 请求结束手术；服务端停止摄像头录制，**仅在确认停录完成后**返回 HTTP 200。 |
| 查询结果 | 根据手术 6 位号查询消耗明细与汇总；**仅在已开录且至少已有一条消耗明细后**返回 HTTP 200。 |
| 待确认耗材 | 低置信度时服务端排队一条待确认任务；客户端拉取话术（TTS）并在医生确认后回传，**不阻塞**后续视频推理。 |
@@ -42,13 +42,13 @@
## 3. 接口列表
| 序号 | 方法 | 路径 | 说明 |
| --- | ------ | --------------------------------------- | ------ |
| 1 | `POST` | `/client/surgeries/start` | 开始手术 |
| 2 | `POST` | `/client/surgeries/end` | 结束手术 |
| 3 | `GET` | `/client/surgeries/{surgery_id}/result` | 查询手术结果 |
| 4 | `GET` | `/client/surgeries/{surgery_id}/pending-confirmation` | 拉取一条待确认耗材 |
| 5 | `POST` | `/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve` | 提交医生确认结果 |
| 序号 | 方法 | 路径 | 说明 |
| --- | ------ | ------------------------------------------------------------------------------- | --------- |
| 1 | `POST` | `/client/surgeries/start` | 开始手术 |
| 2 | `POST` | `/client/surgeries/end` | 结束手术 |
| 3 | `GET` | `/client/surgeries/{surgery_id}/result` | 查询手术结果 |
| 4 | `GET` | `/client/surgeries/{surgery_id}/pending-confirmation` | 拉取一条待确认耗材 |
| 5 | `POST` | `/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve` | 提交医生确认结果 |
---
@@ -71,15 +71,15 @@
**请求体字段：**
| 字段名 | 类型 | 必填 | 说明 |
| ----------------------- | ---------- | --- | ---------------------- |
| `surgery_id` | `string` | 是 | 手术 6 位号，必须为 6 位数字。 |
| `camera_ids` | `string[]` | 是 | 摄像头 ID 列表，至少 1 个元素；须与服务端配置的 RTSP 映射键一致（示例见 `app/resources/camera_rtsp_urls.sample.json`）。 |
| `candidate_consumables` | `string[]` | 否 | 本台手术允许记账的耗材名称清单。**为空或未传则不会写入任何消耗**（仅拉流推理）；非空时自动记账与待确认仅针对清单内名称。 |
| 字段名 | 类型 | 必填 | 说明 |
| ----------------------- | ---------- | --- | ----------------------------------------------------------------------------------------- |
| `surgery_id` | `string` | 是 | 手术 6 位号，必须为 6 位数字。 |
| `camera_ids` | `string[]` | 是 | 摄像头 ID 列表，至少 1 个元素；须与服务端配置的 RTSP 映射键一致（示例见 `app/resources/camera_rtsp_urls.sample.json`）。 |
| `candidate_consumables` | `string[]` | 否 | 本台手术允许记账的耗材名称清单。**为空或未传则不会写入任何消耗**（仅拉流推理）；非空时自动记账与待确认仅针对清单内名称。 |
**说明：** 若该 `surgery_id` 在服务端仍存在**尚未写入数据库**的上一台手术内存归档，开始新会话前会先尝试落库；落库失败则返回 **503**（`RECORDING_CANNOT_START`），避免静默丢失数据。
**请求示例：**
```json
@@ -223,7 +223,7 @@ Host: <主机>:<端口>
| `quantity` | `integer` | 是 | 本条记录对应的消耗数量（非负整数）。 |
| `doctor_id` | `string` | 是 | 医生 ID。 |
| `timestamp` | `string` | 是 | 记录时间，**ISO 8601**（JSON 中为 ISO 格式字符串，与 OpenAPI 中 `date-time` 一致）。 |
| `source` | `string` | 否 | `vision` 自动识别；`voice` 医生通过待确认接口确认。 |
| `source` | `string` | 否 | `vision` 自动识别；`voice` 医生通过待确认接口确认。 |
`**summary[]` 中每一项（汇总行）：**
@@ -285,10 +285,12 @@ Host: <主机>:<端口>
**失败（HTTP 404）：** 无待确认项或手术未在进行。`detail.code` 示例：`NO_PENDING_CONFIRMATION`。
| 项目 | 内容 |
| --- | --- |
| 方法 | `GET` |
| 路径 | `/client/surgeries/{surgery_id}/pending-confirmation` |
| 项目 | 内容 |
| --- | ----------------------------------------------------- |
| 方法 | `GET` |
| 路径 | `/client/surgeries/{surgery_id}/pending-confirmation` |
**响应字段（节选）：** `confirmation_id`、`prompt_text`、`options[]`（`label` + `confidence`）、`model_top1_label`、`model_top1_confidence`、`created_at`。
@@ -298,17 +300,21 @@ Host: <主机>:<端口>
**用途：** 客户端采集医生回答的 **WAV 音频**并上传；服务端将音频存入 MinIO、调用百度 ASR 识别、解析 4.4 返回的候选项；**确认**则记一条 `source=voice` 的消耗明细，**否认**则关闭该待确认项且不记账。
| 项目 | 内容 |
| --- | --- |
| 方法 | `POST` |
| 路径 | `/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve` |
| `Content-Type` | `multipart/form-data` |
| 项目 | 内容 |
| -------------- | ------------------------------------------------------------------------------- |
| 方法 | `POST` |
| 路径 | `/client/surgeries/{surgery_id}/pending-confirmation/{confirmation_id}/resolve` |
| `Content-Type` | `multipart/form-data` |
**请求体（multipart）：**
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `audio` | 文件 | 是 | 医生语音 **`.wav`**；建议 16 kHz 单声道 PCM，其他格式服务端可尝试用 ffmpeg 转码。 |
| 字段 | 类型 | 必填 | 说明 |
| ------- | --- | --- | -------------------------------------------------------- |
| `audio` | 文件 | 是 | 医生语音 `**.wav`**；建议 16 kHz 单声道 PCM，其他格式服务端可尝试用 ffmpeg 转码。 |
**成功响应（HTTP 200）：** `SurgeryPendingConfirmationResolveResponse`：`resolved_label`、`rejected`、`asr_text`、`audio_object_key` 等（与 OpenAPI 一致）。
@@ -367,7 +373,7 @@ Host: <主机>:<端口>
| 版本 | 日期 | 说明 |
| --- | ---------- | ---------------------------------------------------------------- |
| 1.6 | 2026-04-21 | 待确认耗材接口；候选清单硬约束；查询结果需至少一条明细；客户端侧人工确认。 |
| 1.6 | 2026-04-21 | 待确认耗材接口；候选清单硬约束；查询结果需至少一条明细；客户端侧人工确认。 |
| 1.5 | 2026-04-21 | 开始/结束手术：录制流水线失败时重试，仍失败再 503；可配置 `SURGERY_RECORDING_`*。 |
| 1.4 | 2026-04-21 | 与 OpenAPI 对齐：开始/结束/查询的 200/503 条件及 `SurgeryClientErrorResponse`。 |
| 1.3 | 2026-04-21 | 结束手术：仅在实际停录确认后返回 HTTP 200；否则 503。 |