# 前端开发对接文档 ## 1. 简介 本文档旨在为前端开发人员提供与后端API交互所需的所有信息。 - **技术栈**: 前端 (Vue) + 后端 (FastAPI) - **API基础路径**: 所有API路由都以 `/api/v3` 为前缀 (具体URL需根据部署情况配置)。 - **认证**: 系统采用JWT (JSON Web Token) 进行认证。 --- ## 2. 核心流程 ### 2.1 认证流程 1. **注册/登录**: - 新用户通过 `POST /api/v3/register` 接口进行注册。 - 已注册用户通过 `POST /api/v3/login` 接口进行登录。 2. **获取Token**: 注册或登录成功后，后端会返回一个 `access_token` 和 `user_info` 对象。 3. **存储Token**: 前端需要安全地存储 `access_token` (例如，使用 `localStorage`、`sessionStorage` 或 `cookie`)。 4. **发送认证请求**: 对于需要认证的接口，前端必须在HTTP请求头中携带 `access_token`。 ``` Authorization: Bearer {your_access_token} ``` ### 2.2 关键数据对象：`user_info` 注册或登录成功后，前端会收到一个 `user_info` 对象，建议将其保存在全局状态管理器中 (如 Pinia/Vuex)，以便在各个页面和组件中使用。 ```json "user_info": { "user_id": "user-abc-123", // 用户的唯一、固定ID，安全 "medical_record_number": "J0012345", // 就诊号，用于登录 "name": "张三", "gender": "男", "dominant_hand": "右", "diagnosis": "无", "dob": "1960-01-15", "height_cm": 175, "weight_kg": 70, "contact": "13800138000", "inpatient_number": "Z67890", "bed_number": "503", "education_level": "本科", "education_years": 16, "remarks": "" } ``` ### 2.3 错误处理 API会返回标准化的错误响应，前端可以根据 `code` 和 `error_details.type` 来实现精细化的错误提示。 ```json // 示例：参数验证失败 { "status": "error", "code": 400, "message": "Invalid Parameters", "error_details": { "type": "validation_error", "description": "参数验证失败", "fields": { "field_name": "错误描述" } } } ``` --- ## 3. API 接口参考 ### 页面1: 用户注册 (扫码) #### `POST /api/v3/register` - **说明**: 创建一个新患者用户。 - **认证**: 无需 - **请求体**: ```json { "medical_record_number": "string", // 就诊号, 将作为登录用户名 "id_last_six": "string", // 身份证后六位, 将作为登录密码 "name": "string", "gender": "string", "dominant_hand": "string", "diagnosis": "string", "dob": "string", // 格式: YYYY-MM-DD "height_cm": "number", "weight_kg": "number", "contact": "string", "inpatient_number": "string", // 可选 "bed_number": "string", // 可选 "education_level": "string", // 可选 "education_years": "number", // 可选 "remarks": "string" // 可选 } ``` - **成功响应 (200 OK)**: 返回 `access_token` 和 `user_info`。 ```json { "status": "success", "code": 200, "data": { "access_token": "...", "token_type": "Bearer", "is_admin": false, "user_info": { ... } }, "message": "注册成功并自动登录" } ``` --- ### 页面2: 登录 #### `POST /api/v3/login` - **说明**: 用户登录。 - **认证**: 无需 - **请求体**: ```json { "username": "string", // medical_record_number 或管理员用户名 "password": "string" // id_last_six 或管理员密码 } ``` - **成功响应 (200 OK)**: - **普通用户**: 返回 `access_token` 和 `user_info`。 - **管理员**: 返回 `access_token` 和 `is_admin: true`。 --- ### 页面3: 基本信息确认 - **说明**: 纯前端页面，用于展示从登录/注册接口获取的 `user_info`。用户确认后，前端负责路由跳转到下一页。 --- ### 页面4: 姿态识别 #### `POST /api/v3/streams` (开始推流) - **说明**: 启动姿态识别服务，并获取WebSocket连接地址。 - **认证**: **需要** - **成功响应 (200 OK)**: ```json { "status": "success", "code": 200, "data": { "stream_id": "stream_123456", "ws_url": "ws://{host}/api/v3/ws/streams/{stream_id}?token={access_token}", "message": "推流服务已启动，请建立WebSocket连接" } } ``` - **前端工作**: 前端获取 `ws_url` 后，立即建立WebSocket连接。 #### `DELETE /api/v3/streams/{stream_id}` (停止推流) - **说明**: 停止指定的姿态识别流。 - **认证**: **需要** #### WebSocket 通信 - **地址**: 由 `POST /api/v3/streams` 接口返回。 - **后端 -> 前端**: 后端会持续推送视频分析数据。 ```json { "video_frame": "base64_encoded_image", // Base64编码的视频帧 "timestamp": "...", "stream_id": "...", "analysis_data": { "stage": "stand_up" // 当前阶段标识 } } ``` - **前端职责**: 接收到新的 `stage` 后，根据该标识显示对应的提示文本和播放语音。所有提示内容（文本、音频文件）预置在前端。 --- ### 页面5: 视频交互 #### `GET /api/v3/videos` (获取视频及问卷列表) - **说明**: 一次性获取所有视频及其关联的问题。 - **认证**: **需要** - **成功响应 (200 OK)**: ```json { "status": "success", "code": 200, "data": { "videos": [ { "video_id": "video_123456", "title": "...", "description": "...", "questions": [ ... ] } ] } } ``` #### `GET /api/v3/videos/{video_id}.mp4` (获取视频文件) - **说明**: 用于HTML `