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

```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 `<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)**:
  ```json
  {
      "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)**:
  ```json
  {
      "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)**:
  ```json
  {
      "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`**: 提交修正后的事件标记，后端将重新计算并返回更新后的数据。
  - **请求体**:
    ```json
    {
        "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="..."`