ThbTech/BodyBalanceEvaluation
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
da2dc38a51
BodyBalanceEvaluation/document/Web接口调用说明.md

8.7 KiB
Raw Blame History

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

  • 功能：健康检查与服务存活状态。
  • 示例响应：
{ "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 可选：
{
  "diagnosis_info": "string",
  "treatment_info": "string",
  "remark_info": "string"
}
  • 说明：服务端已统一走 update_session_endcheck 数据库流程。

POST /api/detection/<session_id>/start_record

  • 功能：开始同步录制（屏幕/相机/设备流）。
  • Body 示例：
{
  "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：
{
  "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>

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