259 lines
8.7 KiB
Markdown
259 lines
8.7 KiB
Markdown
# Web 接口调用说明
|
||
|
||
本文档基于 `backend/main.py` 中注册的路由，整理对外提供的 Web API 调用方式、参数与返回示例，便于前端或第三方系统集成。
|
||
|
||
## 总览
|
||
|
||
- 基础与健康检查
|
||
- `GET /health`
|
||
- `GET /api/health`
|
||
- 授权相关
|
||
- `GET /api/license/info`
|
||
- `POST /api/license/activation-request`
|
||
- `POST /api/license/verify`
|
||
- `POST /api/license/activate-package`
|
||
- 认证与用户
|
||
- `POST /api/auth/login`
|
||
- `POST /api/auth/register`
|
||
- `POST /api/auth/logout`
|
||
- `GET /api/auth/verify`
|
||
- `POST /api/auth/forgot-password`
|
||
- `GET /api/users`
|
||
- `POST /api/users/<user_id>/approve`
|
||
- `DELETE /api/users/<user_id>`
|
||
- 设备与配置
|
||
- `GET /api/devices/status`
|
||
- `POST /api/devices/refresh`
|
||
- `GET /api/config/devices`
|
||
- `POST /api/config/devices/all`
|
||
- `POST /api/devices/calibrate`
|
||
- `POST /api/devices/calibrate/imu`
|
||
- 患者管理
|
||
- `GET /api/patients`
|
||
- `GET|PUT|DELETE /api/patients/<patient_id>`
|
||
- 检测流程
|
||
- `POST /api/detection/start`
|
||
- `GET /api/detection/<session_id>/has_data`
|
||
- `POST /api/detection/<session_id>/start_record`
|
||
- `POST /api/detection/<session_id>/stop_record`
|
||
- `POST /api/detection/<session_id>/save-data`
|
||
- `POST /api/detection/<session_id>/save-info`
|
||
- `GET /api/detection/<session_id>/status`
|
||
- `POST /api/detection/<session_id>/stop`
|
||
- 历史与数据查询
|
||
- `GET /api/history/sessions`
|
||
- `GET /api/history/sessions/<session_id>`
|
||
- `GET /api/detection/data/details?ids=<id1,id2,...>`
|
||
- 删除操作
|
||
- `DELETE /api/detection/data/<data_id[,data_id2,...]>`
|
||
- `DELETE /api/detection/video/<video_id[,video_id2,...]>`
|
||
- `DELETE /api/detection/sessions/<session_id>`
|
||
|
||
## 统一响应约定
|
||
|
||
- 成功：`{ "success": true, ... }`
|
||
- 失败：`{ "success": false, "error": "错误信息" }`
|
||
- 时间字段统一使用 ISO 文本或 `YYYY-MM-DD HH:mm:ss` 字符串。
|
||
|
||
## 基础与授权
|
||
|
||
### GET /health | GET /api/health
|
||
- 功能：健康检查与服务存活状态。
|
||
- 示例响应：
|
||
```json
|
||
{ "status": "healthy", "timestamp": "2024-01-01T12:00:00", "version": "1.0.0" }
|
||
```
|
||
|
||
### GET /api/license/info
|
||
- 功能：获取授权状态与基础信息。
|
||
- 响应字段：`valid`, `message`, `license_type`, `license_id`, `expires_at`, `features`, `machine_id`。
|
||
|
||
### POST /api/license/activation-request
|
||
- 功能：生成离线激活请求文件。
|
||
- Body：`{ "company_name": "公司名", "contact_info": "联系方式" }`
|
||
- 返回：`request_file` 路径与 `content` 文本。
|
||
|
||
### POST /api/license/verify
|
||
- 功能：上传并验证授权文件。
|
||
- Form-Data：`license_file`（文件）。
|
||
- 返回：授权验证结果与解析出的授权信息。
|
||
|
||
### POST /api/license/activate-package
|
||
- 功能：上传激活包进行离线激活。
|
||
- 细节见服务端实现，返回激活状态与信息。
|
||
|
||
## 认证与用户
|
||
|
||
### POST /api/auth/login
|
||
- 功能：用户登录。
|
||
- Body：`{ "username": "string", "password": "string" }`
|
||
|
||
### POST /api/auth/register
|
||
- 功能：用户注册。
|
||
- Body：包含用户名、密码、手机号等注册信息。
|
||
|
||
### POST /api/auth/logout
|
||
- 功能：登出当前会话。
|
||
|
||
### GET /api/auth/verify
|
||
- 功能：登录状态校验。
|
||
|
||
### POST /api/auth/forgot-password
|
||
- 功能：忘记密码，根据用户名和手机号找回。
|
||
- Body：`{ "username": "string", "phone": "string" }`
|
||
|
||
### GET /api/users
|
||
- 功能：获取用户列表。
|
||
- Query 可选：分页参数。
|
||
|
||
### POST /api/users/<user_id>/approve
|
||
- 功能：批准用户，使其 `is_active = 1`。
|
||
- Body 可选：`{ "approved_by": 123 }`
|
||
|
||
### DELETE /api/users/<user_id>
|
||
- 功能：删除用户。
|
||
|
||
## 患者管理
|
||
|
||
### GET /api/patients
|
||
- 功能：获取患者列表。
|
||
- Query 可选：分页筛选。
|
||
|
||
### POST /api/patients
|
||
- 功能：创建新患者。
|
||
- Body：患者基本信息字段（姓名、性别、出生日期等）。
|
||
- 必填字段：`name`（姓名）、`gender`（性别）、`birth_date`（出生日期）
|
||
- 可选字段：`phone`（电话）、`email`（邮箱）、`height`（身高）、`weight`（体重）、`nationality`（民族）、`residence`（居住地）、`occupation`（职业）、`workplace`（工作单位）、`idcode`（身份证号）、`medical_history`（病史）、`notes`（备注）
|
||
|
||
### GET|PUT|DELETE /api/patients/<patient_id>
|
||
- 功能：获取/更新/删除单个患者。
|
||
- PUT Body：患者基本信息字段（姓名、性别、出生日期、联系方式等）。
|
||
|
||
## 设备与配置
|
||
|
||
### GET /api/devices/status
|
||
- 功能：获取各设备连接与工作状态。
|
||
|
||
### POST /api/devices/refresh
|
||
- 功能：刷新设备状态（重扫/重连）。
|
||
|
||
### GET /api/config/devices
|
||
- 功能：获取当前设备配置。
|
||
|
||
### POST /api/config/devices/all
|
||
- 功能：批量设置设备配置。
|
||
- Body：设备配置对象集合。
|
||
|
||
### POST /api/devices/calibrate
|
||
- 功能：触发设备标定（通用）。
|
||
|
||
### POST /api/devices/calibrate/imu
|
||
- 功能：仅触发 IMU 设备标定。
|
||
|
||
## 检测流程
|
||
|
||
### POST /api/detection/start
|
||
- 功能：创建检测会话并启动设备连接监控。
|
||
- Body：`{ "patient_id": "string", "creator_id": "string" }`
|
||
- 返回：`session_id`。
|
||
|
||
### GET /api/detection/<session_id>/has_data
|
||
- 功能：会话是否存在检测数据，用于判断单次检测是否有效。
|
||
- 返回：`{ "has_data": true|false }`
|
||
### GET /api/detection/<session_id>/status
|
||
- 功能：获取会话最新状态与聚合数据（源自 `get_session_data`）。
|
||
|
||
### POST /api/detection/<session_id>/stop
|
||
- 功能：结束检测并写入总结信息（自动计算时长与结束时间）。
|
||
- Body 可选：
|
||
```json
|
||
{
|
||
"diagnosis_info": "string",
|
||
"treatment_info": "string",
|
||
"remark_info": "string"
|
||
}
|
||
```
|
||
- 说明：服务端已统一走 `update_session_endcheck` 数据库流程。
|
||
### POST /api/detection/<session_id>/start_record
|
||
- 功能：开始同步录制（屏幕/相机/设备流）。
|
||
- Body 示例：
|
||
```json
|
||
{
|
||
"patient_id": "p001",
|
||
"screen_location": [0,0,1920,1080],
|
||
"femtobolt_location": [0,0,640,480],
|
||
"camera1_location": [0,0,640,480],
|
||
"camera2_location": [0,0,640,480]
|
||
}
|
||
```
|
||
- 返回：`recording` 含 `database_updates.video_paths`；服务端会自动调用 `save_detection_video` 记录视频路径（`screen_video_path`, `femtobolt_video_path`, `camera1_video_path`, `camera2_video_path`）。
|
||
|
||
### POST /api/detection/<session_id>/stop_record
|
||
- 功能：停止同步录制。
|
||
|
||
### POST /api/detection/<session_id>/save-data
|
||
- 功能：采集检测数据与截图并持久化。
|
||
- Body：检测数据载荷（结构由实际采集模块决定）。
|
||
- 返回：`timestamp` 与是否采集成功。
|
||
|
||
### POST /api/detection/<session_id>/save-info
|
||
- 功能：保存会话信息（诊断、处理、建议、状态）。
|
||
- Body：
|
||
```json
|
||
{
|
||
"diagnosis_info": "string",
|
||
"treatment_info": "string",
|
||
"remark_info": "string",
|
||
"status": "completed|running|..."
|
||
}
|
||
```
|
||
|
||
|
||
|
||
## 历史与数据查询
|
||
|
||
### GET /api/history/sessions
|
||
- 功能：分页获取检测会话历史。
|
||
- Query：`page`（默认 1）、`size`（默认 10）、`patient_id`（可选）。
|
||
- 返回：`sessions` 与 `total`。
|
||
|
||
### GET /api/history/sessions/<session_id>
|
||
- 功能：获取会话详细数据（聚合会话、检测数据、视频）。
|
||
|
||
### GET /api/detection/data/details?ids=<id1,id2,...>
|
||
- 功能：根据多个逗号分隔的 ID 批量获取检测数据详情。
|
||
- Query：`ids` 逗号分隔字符串。
|
||
|
||
## 删除操作
|
||
|
||
### DELETE /api/detection/data/<data_id[,data_id2,...]>
|
||
- 功能：删除检测数据记录，支持多个 ID 逗号分隔。
|
||
- 返回：`deleted_ids` 列表。
|
||
|
||
### DELETE /api/detection/video/<video_id[,video_id2,...]>
|
||
- 功能：删除检测视频记录，支持多个 ID 逗号分隔。
|
||
- 返回：`deleted_ids` 列表。
|
||
|
||
### DELETE /api/detection/sessions/<session_id>
|
||
- 功能：删除检测会话，同时清理关联的检测数据与视频记录。
|
||
|
||
## 错误码与常见失败
|
||
|
||
- 400：缺少必要参数或请求体格式错误。
|
||
- 403：授权校验失败或未授权功能。
|
||
- 404：会话或资源不存在。
|
||
- 500：服务内部错误（设备不可用、数据库失败等）。
|
||
|
||
## 典型调用序列（示例）
|
||
|
||
1. 创建会话：`POST /api/detection/start`
|
||
2. 开始录制：`POST /api/detection/<session_id>/start_record`
|
||
3. 采集数据：多次 `POST /api/detection/<session_id>/save-data`
|
||
4. 停止录制：`POST /api/detection/<session_id>/stop_record`
|
||
5. 保存诊断建议：`POST /api/detection/<session_id>/save-info`
|
||
6. 结束检测：`POST /api/detection/<session_id>/stop`
|
||
7. 校验有效性：`GET /api/detection/<session_id>/has_data`
|
||
8. 查询历史：`GET /api/history/sessions`
|
||
9. 查看详情：`GET /api/history/sessions/<session_id>`
|
||
|
||
> 注：具体字段与数据结构以采集模块与数据库模型为准，本文档以主干流程为纲要，建议结合实际返回进行前端适配与校验。 |