Intelligent_Health_Evaluation_System_4_Civilian_Health_Monitoring/前端开发对接文档.md

前端开发对接文档

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)，以便在各个页面和组件中使用。

"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 来实现精细化的错误提示。

// 示例：参数验证失败
{
    "status": "error",
    "code": 400,
    "message": "Invalid Parameters",
    "error_details": {
        "type": "validation_error",
        "description": "参数验证失败",
        "fields": {
            "field_name": "错误描述"
        }
    }
}

---

3. API 接口参考

页面1: 用户注册 (扫码)

POST /api/v3/register

• 说明: 创建一个新患者用户。
• 认证: 无需
• 请求体:

  {
      "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。

  {
      "status": "success",
      "code": 200,
      "data": {
          "access_token": "...",
          "token_type": "Bearer",
          "is_admin": false,
          "user_info": { ... }
      },
      "message": "注册成功并自动登录"
  }
  

---

页面2: 登录

POST /api/v3/login

• 说明: 用户登录。
• 认证: 无需
• 请求体:

  {
      "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):

  {
      "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 接口返回。
• 后端 -> 前端: 后端会持续推送视频分析数据。

  {
      "video_frame": "base64_encoded_image", // Base64编码的视频帧
      "timestamp": "...",
      "stream_id": "...",
      "analysis_data": {
          "stage": "stand_up" // 当前阶段标识
      }
  }
  

• 前端职责: 接收到新的 stage 后，根据该标识显示对应的提示文本和播放语音。所有提示内容（文本、音频文件）预置在前端。

---

页面5: 视频交互

GET /api/v3/videos (获取视频及问卷列表)

• 说明: 一次性获取所有视频及其关联的问题。
• 认证: 需要
• 成功响应 (200 OK):

  {
      "status": "success",
      "code": 200,
      "data": {
          "videos": [
              {
                  "video_id": "video_123456",
                  "title": "...",
                  "description": "...",
                  "questions": [ ... ]
              }
          ]
      }
  }
  

GET /api/v3/videos/{video_id}.mp4 (获取视频文件)

• 说明: 用于HTML <video> 标签的 src 属性，播放视频。
• 认证: 无需

多模态实时交互 (WebSocket)

• 说明: 此页面的眼动、面部表情、手写数据采集是并行的。前端主要通过WebSocket与 手写服务 交互。
• WebSocket URL: 由 POST /api/v3/video-sessions 接口动态返回（注意：此API尚未在文档中明确定义，需与后端确认）。
• 前端 -> 后端:
  • 发送手写数据: {"type": "handwriting_stroke", "payload": ...}
  • 结束会话: {"command": "end_session"}

---

页面6: 语音交互 (异步流程)

此页面交互是异步的，前端需要使用 SSE (Server-Sent Events) 来接收实时进度。

1. POST /api/v3/audio-sessions (开始会话)

• 说明: 创建一个语音交互会话。
• 认证: 需要
• 成功响应 (200 OK): 返回 session_id。

2. POST /api/v3/audio-sessions/{session_id}/interact (上传音频并发起处理)

• 说明: 上传用户录音，这是一个异步接口，会立即返回。
• 认证: 需要
• 请求: multipart/form-data，包含名为 audio 的文件。
• 成功响应 (202 Accepted):

  {
      "status": "accepted",
      "code": 202,
      "data": {
          "request_id": "req_abc123",
          "events_url": "/api/v3/audio-sessions/{session_id}/events/{request_id}",
          "message": "请求已接收，请连接到events_url获取实时进度"
      }
  }
  

3. GET /api/v3/audio-sessions/{session_id}/events/{request_id} (监听事件)

• 说明: 前端使用上一步返回的 events_url 建立SSE连接。
• 协议: text/event-stream
• 服务端推送事件:
  • 语音识别(ASR)完成:

    event: asr_result
    data: {"status": "success", "text": "用户说的话"}
    

  • AI回复完成:

    event: ai_result
    data: {"status": "success", "text": "AI的回复文本"}
    

  • 语音合成(TTS)完成:

    event: tts_result
    data: {"status": "success", "audio_url": "/api/v3/audios/audio_xyz.wav"}
    

  • 任务结束:

    event: done
    data: {"status": "success", "message": "处理完成"}
    

  • 错误:

    event: error
    data: {"status": "error", "stage": "asr", "message": "ASR处理失败"}
    

4. GET /api/v3/audios/{audio_id}.wav (获取音频文件)

• 说明: 用于播放TTS合成的语音。
• 认证: 无需

---

页面7: 历史测试记录查询

GET /api/v3/admin/logs

• 说明: 获取所有历史测试记录的批次列表。仅管理员可访问。
• 认证: 需要
• 成功响应 (200 OK):

  {
      "status": "success",
      "code": 200,
      "data": {
          "tables": [
              {
                  "table_name": "test_20240315_1",
                  "created_at": "2024-03-15T14:30:00Z",
                  "description": "2024年3月15日第一次测试"
              },
              {
                  "table_name": "test_20240315_2",
                  "created_at": "2024-03-15T16:30:00Z",
                  "description": "2024年3月15日第二次测试"
              }
          ]
      }
  }
  

---

页面8: 单次测试记录列表

GET /api/v3/admin/logs/{table_name}

• 说明: 查询指定批次下的所有测试者记录。
• 认证: 需要
• Query参数:
  • page (number, optional, default: 1): 页码
  • page_size (number, optional, default: 50): 每页数量
• 成功响应 (200 OK):

  {
      "status": "success",
      "code": 200,
      "data": {
          "total": 100,
          "total_pages": 2,
          "current_page": 1,
          "page_size": 50,
          "records": [
              {
                  "log_id": 1,
                  "medical_record_number": "J0012345",
                  "name": "张三",
                  "created_at": "2024-03-15T08:30:00Z",
                  "status": "completed"
              }
          ]
      }
  }
  

• status 字段说明:
  • initialized: 已初始化
  • processing: 数据处理中
  • pending_review: 待专家审核
  • completed: 已完成

---

页面9: 分析模块详情与编辑

所有此部分的API都需要认证，并使用路径参数 /api/v3/admin/logs/{table_name}/{log_id}/...

步态分析 (Gait)

• GET .../gait: 获取步态分析数据（包含事件、分段和计算指标）。
• POST .../gait/events: 提交修正后的事件标记，后端将重新计算并返回更新后的数据。
  • 请求体:

    {
        "events": [
            { "event": "stand_up", "frame": 85 },
            { "event": "walk_start", "frame": 180 },
            { "event": "walk_end", "frame": 840 }
        ]
    }
    

面部表情分析 (Facial)

• GET .../facial: 获取面部表情视频URL及当前UPDRS评级。
• POST .../facial/rating: 提交或更新UPDRS评级。
  • 请求体: {"rating": 2} (评级范围: 0-4)

眼动分析 (Eyetracking)

• GET .../eyetracking: 获取眼动分析视频URL及当前评级。
• POST .../eyetracking/rating: 提交或更新评级。
  • 请求体: {"rating": 3} (评级范围: 0-4)

手写笔迹分析 (Handwriting)

• GET .../handwriting: 获取手写数据视频URL及当前评级。
• POST .../handwriting/rating: 提交或更新评级。
• 请求体: {"rating": 1} (评级范围: 0-4)

语音分析 (Speech)

• GET .../speech: 获取语音样本URL及当前评级。
• POST .../speech/rating: 提交或更新评级。
• 请求体: {"rating": 3} (评级范围: 0-4)

语义分析 (Semantics)

• GET .../semantics: 获取文本内容及当前评级。
• POST .../semantics/rating: 提交或更新评级。
• 请求体: {"rating": 1} (评级范围: 0-4)

原始数据下载

• GET .../raw: 下载原始时序数据 (CSV文件)。
• 说明: 后端直接返回文件流，前端需处理下载。
  • 响应头: Content-Type: text/csv, Content-Disposition: attachment; filename="..."