BodyBalanceEvaluation/document/Web接口调用说明.md

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

> 注：具体字段与数据结构以采集模块与数据库模型为准，本文档以主干流程为纲要，建议结合实际返回进行前端适配与校验。