Intelligent_Health_Evaluation_System_4_Civilian_Health_Monitoring/软件框架V2.md

## 📌 软件框架概述
该架构是一个单机前后端BS架构，没有并发，而且也不可能并发，因为设备层没有那么多冗余资源。
软件采用前后端分离的架构，前端采用Vue，后端采用FastAPI，数据库选用向量数据库Postgresql。

## 📋 页面1：用户注册页面 (扫码)
- **说明**: 此页面通过二维码引导用户进行自助注册，适用于现场排队等候的场景。管理员可在管理后台生成或展示此注册页面的二维码。
- **跳转条件**:
  - 新用户注册成功后跳转到基本信息确认页面
- **路由**: /api/v3/register
- **访问方式**：POST
- **注意事项**:
    - 新用户填写完毕后也需要跳信息确认，确认前不要弹给后端
    - 确认后等待后端返回，除非确认成功否则不跳转，提示用户修改对应字段
    - 后端在确认无误后会插入数据库的`patient_info`表单。
- **请求参数**:
```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",             // 身高(cm)
    "weight_kg": "number",             // 体重(kg)
    "contact": "string",               // 联系方式
    "inpatient_number": "string",      // 住院号 (可选)
    "bed_number": "string",            // 床号 (可选)
    "education_level": "string",       // 教育程度 (可选)
    "education_years": "number",       // 教育年数 (可选)
    "remarks": "string"                // 备注 (可选)
}
```
- **响应格式**:
```json
// 注册成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "is_admin": false,
        "user_info": {
            "user_id": "user-abc-123",
            "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": ""
        }
    },
    "message": "注册成功并自动登录"
}

// 用户名已存在响应
{
    "status": "error",
    "code": 400,
    "message": "Username Already Exists",
    "error_details": {
        "type": "duplicate_username",
        "description": "该用户名已被注册"
    }
}

// 邮箱已存在响应
{
    "status": "error",
    "code": 400,
    "message": "Email Already Exists",
    "error_details": {
        "type": "duplicate_email",
        "description": "该邮箱已被注册"
    }
}

// 参数验证失败响应
{
    "status": "error",
    "code": 400,
    "message": "Invalid Parameters",
    "error_details": {
        "type": "validation_error",
        "description": "参数验证失败",
        "fields": {
            "email": "邮箱格式不正确",
            "password": "密码长度必须大于6位"
        }
    }
}
```

## 📋 页面2：登录页面
- 功能要求：输入用户名密码，发后端验证
- 跳转条件：登录成功后根据用户类型跳转
  - 管理员用户：跳转到数据库可视化页面
  - 普通用户：跳转到基本信息确认页面
- 路由: /api/v3/login
    - 访问方式：POST
    - 请求参数：
    ```json
    {
        "username": "string",  // 用户名
        "password": "string"   // 密码
    }
    ```
    - 响应格式：
    ```json
    // 管理员用户响应
    {
        "status": "success",
        "code": 200,
        "data": {
            "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "token_type": "Bearer",
            "is_admin": true,
            "active_log_table": "log_20240401_1"
        },
        "message": "管理员登录成功，已创建新的测试会话日志表"
    }

    // 普通用户响应
    {
        "status": "success",
        "code": 200,
        "data": {
            "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "token_type": "Bearer",
            "is_admin": false,
            "user_info": {
                "user_id": "user-abc-123",
                "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": ""
            }
        },
        "message": "登录成功，令牌长期有效，用户信息已包含在令牌中"
    }

    // 错误响应
    {
        "status": "error",
        "code": 401,
        "message": "Unauthorized",
        "error_details": {
            "type": "invalid_credentials",
            "description": "Invalid username or password"
        }
    }
    ```

## 📋 页面3：基本信息确认页面
# 功能1：基本信息确认
- 跳转条件：
  - 普通用户登录或新用户注册成功后直接跳转至此页面
  - 确认信息后跳转到姿态识别页面
- 路由: 无独立后端API。此页面为纯前端页面，用于展示登录时获取的`user_info`，用户确认后前端负责路由跳转。
- 如果页面1验证为普通用户，跳转后让他直接确认

## 📋 页面4：姿态识别页面
- 跳转条件：
  - 基本信息确认完成后跳转至此页面
  - 测试时间结束显示"功能测试1已结束，将在X秒后跳转下一页面"
- 结束方式：时间到自动结束，计时由前端执行。

# 功能1：开始姿态识别推流
- 路由: /api/v3/streams
- 访问：POST
- 请求头：
  ```
  Authorization: Bearer {access_token}  // 登录接口获取的token
  ```
- 请求参数：无
- 响应：
```json
// 开始推流成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "stream_id": "stream_123456",  // 流ID，用于后续停止推流
        "ws_url": "ws://{host}/api/v3/ws/streams/{stream_id}?token={access_token}",
        "message": "推流服务已启动，请建立WebSocket连接"
    }
}

// 错误响应 - 摄像头未就绪
{
    "status": "error",
    "code": 503,
    "message": "摄像头未就绪",
    "error_details": {
        "type": "camera_not_ready",
        "description": "请检查摄像头连接"
    }
}

// 错误响应 - 服务繁忙
{
    "status": "error",
    "code": 503,
    "message": "服务繁忙",
    "error_details": {
        "type": "service_busy",
        "description": "当前服务负载过高，请稍后重试"
    }
}

// 错误响应 - 未授权
{
    "status": "error",
    "code": 401,
    "message": "未授权访问",
    "error_details": {
        "type": "unauthorized",
        "description": "请先登录"
    }
}
```

# 功能2：停止姿态识别推流
- 路由: /api/v3/streams/{stream_id}
- 访问：DELETE
- 请求头：
  ```
  Authorization: Bearer {access_token}  // 登录接口获取的token
  ```
- 响应：
```json
// 停止推流成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "推流服务已停止"
    }
}

// 错误响应 - 无效的流ID
{
    "status": "error",
    "code": 400,
    "message": "无效的流ID",
    "error_details": {
        "type": "invalid_stream_id",
        "description": "指定的流ID不存在或已过期"
    }
}

// 错误响应 - 未授权
{
    "status": "error",
    "code": 401,
    "message": "未授权访问",
    "error_details": {
        "type": "unauthorized",
        "description": "请先登录"
    }
}
```

# 功能3：WebSocket通信
- 连接地址：由`POST /api/v3/streams`响应中的`ws_url`提供
- **说明**: 此WebSocket连接用于实现实时的医患交互引导。后端通过姿态识别算法实时分析视频流，判断用户当前所处的测试阶段，并将阶段标识 (`stage`) 推送给前端。
- **工作流程**:
    1. 后端实时分析视频流中的姿态数据，并维护一个测试流程的状态机。
    2. 当检测到阶段变化时（如用户从"坐姿"变为"站立"），后端向前端推送新的阶段`stage`。
    3. 前端接收到`stage`后，负责根据该标识查找并显示对应的提示文本，以及播放对应的语音提示。所有提示内容（文本、音频文件名）都预置在前端。
- **服务端推送数据**:
    ```json
    {
        "video_frame": "base64_encoded_image",
        "timestamp": "2024-03-15T14:30:00Z",
        "stream_id": "stream_123456",
        "analysis_data": {
            "stage": "stand_up" // 当前阶段。可能的值: 'initial', 'stand_up', 'walk_to_target', 'turn', 'walk_back', 'sit_down', 'complete', 'error'
        }
    }
    ```
## 📋 页面5：视频交互页面
- **说明**: 在这个页面，用户将观看一个预设的视频，并回答相关问题。
- **跳转条件**: 
  - 页面4结束后跳转。

# 功能1：获取视频及问卷列表
- **路由**: /api/v3/videos
- **访问方式**: GET
- **说明**: 一次性获取所有可用的视频及其关联的问卷。前端加载此页面时调用，简化后续API请求。
- **请求头**:
  ```
  Authorization: Bearer {access_token}
  ```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "videos": [
            {
                "video_id": "video_123456",
                "title": "场景一：公园散步",
                "description": "一段描述在公园里散步的视频。",
                "duration": 300,
                "questions": [
                    { "id": "q1", "type": "text", "content": "请描述视频中展示的主要问题是什么？", "required": true, "max_length": 500 },
                    { "id": "q2", "type": "text", "content": "您认为应该如何解决这个问题？", "required": true, "max_length": 1000 }
                ]
            },
            {
                "video_id": "video_789012",
                "title": "场景二：超市购物",
                "description": "一段模拟在超市购物场景的视频。",
                "duration": 240,
                "questions": [
                    { "id": "q3", "type": "text", "content": "您对这个解决方案有什么建议？", "required": false, "max_length": 800 }
                ]
            }
        ]
    }
}
```

# 功能2：获取视频文件
- **路由**: /api/v3/videos/{video_id}.mp4
- **访问方式**：GET
- **描述**: 此接口用于前端播放器实际获取视频文件流。为简化访问，视频ID本身已是不可猜测的，此接口可不要求JWT认证。
- **响应**: 视频文件流 (MIME类型: `video/mp4`)


# 功能3：多模态实时交互 (WebSocket)
- **后端架构**: 为了确保数据采集的独立性和实时性，后端采用多进程架构。当会话启动时，会生成一个主控进程 (`session_manager.py`)，该进程会进一步启动三个独立的子进程：
    - **`eye_data_collector.py`**: 专职采集眼动数据，并实时写入本地CSV文件，不受其他进程干扰。
    - **`face_data_collector.py`**: 专职采集面部表情数据，并实时写入本地CSV文件，不受其他进程干扰。
    - **`handwriting_server.py`**: 专职运行WebSocket服务器，用于处理与前端的手写交互。
- **WebSocket URL**: 由 `POST /api/v3/video-sessions` 接口动态返回，格式类似于 `ws://127.0.0.1:{port}`。前端必须使用此接口返回的URL进行连接。
- **说明**: 此架构确保了不同设备的数据采集（眼动、面部）可以真正并行，避免了因Python的GIL（全局解释器锁）或设备采样率不同导致的时序问题。
- **工作流程与阶段**:
    1.  **会话启动与被动采集**: API (`POST /video-sessions`) 启动后端的 `session_manager.py`，后者立即启动 `eye_data_collector` 和 `face_data_collector` 进程，开始在后台静默采集数据。
    2.  **建立连接**: 前端使用API返回的`ws_url`与 `handwriting_server.py` 建立WebSocket连接。
    3.  **手写交互**: 前端可以随时向WebSocket发送手写数据（例如 `{"type": "handwriting_stroke", "payload": ...}`）。`handwriting_server` 负责接收。
    4.  **会话结束**: 前端发送会话结束指令 (例如: `{"command": "end_session"}`) 给WebSocket。
    5.  **服务关闭**: `handwriting_server` 收到结束指令后，通过进程间通信通知 `session_manager`。`session_manager` 随即安全地关闭所有相关的子进程（眼动、面部和WebSocket），完成数据保存和资源清理。
- **数据格式**:
    -   通信主要由前端发起的指令和数据构成。
    -   **前端 -> 后端 (WebSocket)**:
        -   指令: `{"command": "end_session"}`
        -   数据: `{"type": "handwriting_stroke", "payload": ...}`




## 📋 页面6：语音交互页面
- **说明**: 采用异步处理模式。用户上传录音后，后端立即响应并开始处理。前端通过SSE（服务器发送事件）连接接收处理进度（语音识别 -> AI对话 -> 语音合成），并实时更新UI，为用户提供流畅的交互反馈。
- **跳转条件**: 
  - 页面8提交问卷后，或页面8按下手动结束跳转（这里需要提示内容为空，是否强制跳转）
- **工作流程**:
    1. **创建会话**: 前端通过 `POST /api/v3/audio-sessions` 创建新会话。
    2. **上传音频**: 用户完成录音后，前端调用 `POST /api/v3/audio-sessions/{session_id}/interact` 上传音频。
    3. **启动处理**: 后端立即返回一个 `request_id` 和一个SSE连接地址，并开始在后台异步处理音频。
    4. **监听事件**: 前端使用返回的地址建立SSE连接，开始监听来自服务器的进度事件。
    5. **阶段一：语音识别 (ASR)**: 后端完成ASR后，通过SSE推送 `asr_result` 事件。前端接收到后，在界面上显示识别出的用户文本。
    6. **阶段二：AI对话**: 后端将ASR文本送入AI模型，完成后通过SSE推送 `ai_result` 事件。前端接收后，显示AI的文本回复。
    7. **阶段三：语音合成 (TTS)**: 后端将AI文本进行TTS，完成后通过SSE推送 `tts_result` 事件，包含音频文件的URL。
    8. **播放与结束**: 前端接收到音频URL后，播放AI的语音回复。最后，服务器推送 `done` 事件，关闭SSE连接。

# 功能1：开始语音交互会话
- **路由**: /api/v3/audio-sessions
- **访问方式**：POST
- **请求头**：
  ```
  Authorization: Bearer {access_token}
  ```
- **请求参数 (可选)**：
```json
{
    "system_prompt": "你是一个聊天机器人，请根据用户需求进行回应。",
    "max_history": 10
}
```
- **响应**:
```json
// 开始会话成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "session_id": "session_123456",
        "message": "语音交互会话已启动"
    }
}
```

# 功能2：发起异步语音对话
- **路由**: /api/v3/audio-sessions/{session_id}/interact
- **访问方式**：POST
- **说明**: 这是一个异步接口。它会立即返回，并启动一个后台任务来处理音频。处理进度通过SSE推送。
- **请求头**：
  ```
  Authorization: Bearer {access_token}
  Content-Type: multipart/form-data
  ```
- **请求体**:
  - `audio`: 用户录制的音频文件 (例如 `blob` 或 `.wav` 格式)
- **响应 (HTTP 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：监听处理事件 (SSE)
- **路由**: /api/v3/audio-sessions/{session_id}/events/{request_id}
- **协议**: `text/event-stream`
- **说明**: 前端与此端点建立连接以接收实时事件。
- **服务端推送事件格式**:
    - **ASR完成**:
      ```
      event: asr_result
      data: {"status": "success", "text": "用户说的话", "confidence": 0.95}
      ```
    - **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：获取对话历史
- **路由**: /api/v3/audio-sessions/{session_id}/history
- **访问方式**: GET
- **请求头**:
  ```
  Authorization: Bearer {access_token}
  ```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "conversation_history": [
            { "role": "user", "content": "你好" },
            { "role": "assistant", "content": "你好，有什么可以帮你的吗？" }
        ]
    }
}
```

# 功能5：结束语音交互会话
- **路由**: /api/v3/audio-sessions/{session_id}
- **访问方式**：DELETE
- **请求头**：
  ```
  Authorization: Bearer {access_token}
  ```
- **响应**:
```json
// 结束会话成功响应
{
    "status": "success",
    "code": 200,
    "data": { "message": "语音交互会话已结束" }
}
```

# 功能6：获取音频文件
- **路由**: /api/v3/audios/{audio_id}.wav
- **访问方式**：GET
- **描述**: 此接口用于前端播放器实际获取TTS生成的音频文件。
- **响应**: 音频文件内容 (e.g., `audio/wav`)


## 📋 页面7：历史测试记录查询页面
# 功能1：获取用户的历史测试记录表
- 跳转条件：仅管理员用户可访问。登录成功后，管理员将直接跳转到此页面。普通用户无权访问。
- 路由: /api/v3/admin/logs
- 方法: GET
- 认证: `Authorization: Bearer {access_token}`
- 返回:
    ```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日第二次测试"
                }
            ]
        }
    }

    // 无数据响应
    {
        "status": "success",
        "code": 200,
        "data": {
            "tables": []
        }
    }

    // 失败响应
    {
        "status": "error",
        "code": 403,
        "message": "Forbidden",
        "error_details": {
            "type": "permission_denied",
            "description": "You don't have permission to access test records"
        }
    }
    ```

## 📋 页面8：单次测试记录列表页面
# 功能1：查询单次测试的所有记录
- **说明**: 从历史测试记录页面选择一个批次后，跳转到此页面，展示该批次下的所有测试者记录。
- **路由**: /api/v3/admin/logs/{table_name}
- **方法**: GET
- **认证**: `Authorization: Bearer {access_token}`
- **请求参数 (Query Parameters)**:
  - `page` (number, optional, default: 1): 页码，从1开始
  - `page_size` (number, optional, default: 50): 每页记录数
- **示例**: `/api/v3/admin/logs/log_20240315_1?page=1&page_size=50`
- **返回**:
```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"
            },
            {
                "log_id": 2,
                "medical_record_number": "J0012346",
                "name": "李四",
                "created_at": "2024-03-15T08:31:00Z",
                "status": "pending_review"
            },
            {
                "log_id": 3,
                "medical_record_number": "J0012347",
                "name": "王五",
                "created_at": "2024-03-15T08:32:00Z",
                "status": "initialized"
            }
        ]
    }
}

- **`status` 字段说明**:
  - `initialized`: 已初始化。记录已创建，等待用户录入数据。
  - `processing`: 数据处理中。用户已完成记录，系统正在后台分析数据。
  - `pending_review`: 待专家审核。系统分析完成，等待专家进行评级和确认。
  - `completed`: 已完成。专家已完成确认，记录归档。

// 查询失败响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "invalid_table",
        "description": "Log table does not exist"
    }
}

// 权限失败响应
{
    "status": "error",
    "code": 403,
    "message": "Access Denied",
    "error_details": {
        "type": "permission_denied",
        "description": "You don't have permission to access this test record"
    }
}
```

## 📋 页面9：分析模块详情与编辑
本部分包含所有针对单个测试记录的具体分析模块。用户从记录列表页选择具体项目后，前端访问对应的页面URL进入编辑与查看。

### 4.1 步态分析页面
# 功能1：获取步态分析数据
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/gait`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 进入步态分析页面时调用，获取该记录中所有行走分段的步态分析结果。一次记录可能包含多次行走，每次行走都是一个独立的分析单元。
- **响应**:
```json
{
    "status": "success",
    "code": 200,
    "data": {
        "procedural_events": [
            { "event": "stand_up", "frame": 85 },
            { "event": "turn_around", "frame": 755 },
            { "event": "sit_down", "frame": 1560 }
        ],
        "walk_segments": [
            {
                "segment_id": 1,
                "start_frame": 153,
                "end_frame": 750,
                "calculated_metrics": {
                    "gait_speed": 1.2,
                    "stride_length": 0.75,
                    "step_speed": 1.1,
                    "swing_speed": 2.5,
                    "cadence": 110.0,
                    "single_support_phase_ratio": 0.4,
                    "swing_phase_ratio": 0.4,
                    "double_support_ratio": 0.2,
                    "step_height": 0.15,
                    "step_width": 0.2
                },
                "events": [
                    { "event": "left_heel_strike", "frame": 165 },
                    { "event": "right_toe_off", "frame": 168 },
                    { "event": "double_support", "frame": 170 },
                    { "event": "right_heel_strike", "frame": 180 },
                    { "event": "left_toe_off", "frame": 183 },
                ]
            },
            ...
        ]
    }
}
```

# 功能2：编辑事件并重新计算步态参数
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/gait/events`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 此功能用于提交修正后的所有关键事件标记（包括`stand_up`, `turn_around`, `sit_down`等过程性事件，以及定义行走分段的`walk_start`, `walk_end`事件）。后端接收到新的事件列表后，将立即执行重新计算，并返回更新后的完整步态分析数据。
- **请求体**:
```json
{
    "events": [
        { "event": "stand_up", "frame": 85 },
        { "event": "walk_start", "frame": 180 },
        { "event": "walk_end", "frame": 840 },
        { "event": "turn_around", "frame": 900 },
        { "event": "sit_down", "frame": 1600 }
    ]
}
```
- **响应**:
```json

- 成功响应：返回更新后的完整步态分析数据，结构同`功能1：获取步态分析数据`的响应。

- 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_event_format",
        "description": "The submitted event data is incorrectly formatted or frames are invalid."
    }
}

- 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```

# 功能3：下载原始时序数据 (CSV)
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/raw`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 为支持后续的研究和算法改进，系统需保留原始的时序数据。此接口提供对指定记录的原始数据（包含COCO骨骼节点时序信息的CSV文件）的下载功能。
- **响应**: 
  - 后端直接返回文件流。
  - **响应头 (Headers)**:
    - **Content-Type**: `text/csv`
    - **Content-Disposition**: `attachment; filename="raw_data_{log_id}.csv"`

### 4.2 面部表情分析页面 (UPDRS评级)
此部分提供对视频中的整体面部表情进行UPDRS评级的功能。评级是针对整个视频的单个分数。
- **UPDRS面部表情评级标准**:
  - **0**: 正常
  - **1**: 极轻微的表情异常
  - **2**: 轻度而肯定的表情呆板
  - **3**: 中度的面部表情损害，仍能张口
  - **4**: 呈面具脸，面部表情严重或完全消失

# 功能1：获取面部表情视频及当前评级
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/facial`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 获取用于评级的面部表情视频，以及该记录当前已有的UPDRS分数。
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "log_id": 1,
        "video_url": "/api/v3/videos/facial_expression_video_abc.mp4",
        "updrs_rating": 1 // 当前UPDRS分数，如果未评级则为null
    }
}

// 记录不存在响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "record_not_found",
        "description": "The specified record does not exist."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to access this resource."
    }
}
```

# 功能2：提交/更新UPDRS评级
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/facial/rating`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 为整个视频提交一个UPDRS评级分数（0-4）。
- **请求体**:
```json
{
    "rating": 2
}
```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "UPDRS rating updated successfully."
    }
}

// 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_rating_value",
        "description": "Rating must be an integer between 0 and 4."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```

### 4.3 眼动分析页面 (UPDRS评级)
此部分提供对眼动追踪视频进行评级的功能。评级主要关注扫视和凝视的稳定性。
- **眼动功能评级标准 (参考UPDRS)**:
  - **0**: 正常，眼跳和凝视稳定、准确。
  - **1**: 轻微异常，扫视速度轻度减慢或偶有不准确。
  - **2**: 轻度异常，扫视速度变慢，凝视不稳定。
  - **3**: 中度异常，扫视启动困难，有明显的凝视不稳或眼球震颤。
  - **4**: 严重异常，无法完成扫视任务或持续的凝视不稳。

# 功能1：获取眼动分析数据及当前评级
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/eyetracking`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 获取指定记录的眼动追踪视频和当前已有的评级分数。
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "video_url": "/api/v3/videos/eyetracking_video_abc.mp4",
        "rating": 2 // 当前评级分数，如果未评级则为null
    }
}

// 记录不存在响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "record_not_found",
        "description": "The specified record does not exist."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to access this resource."
    }
}
```

# 功能2：提交/更新眼动功能评级
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/eyetracking/rating`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 提交对眼动功能的评级分数（0-4）。
- **请求体**:
```json
{
    "rating": 3
}
```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "Eyetracking rating updated successfully."
    }
}

// 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_rating_value",
        "description": "Rating must be an integer between 0 and 4."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```

### 4.4 手写笔迹分析页面 (UPDRS评级)
此部分提供对手写笔迹（如螺旋测试）的评级功能，主要评估运动震颤和书写过小症（Micrographia）。
- **手写功能评级标准 (参考UPDRS)**:
  - **0**: 正常，线条流畅，无明显震颤，大小正常。
  - **1**: 轻微异常，线条有极轻微的震颤或轻微的书写变小。
  - **2**: 轻度异常，线条有肯定的震颤，书写大小一致性变差，但仍清晰可辨。
  - **3**: 中度异常，震颤明显，书写过小症显著，辨认有一定困难。
  - **4**: 严重异常，震颤严重导致无法完成绘制，或字迹小到无法辨认。

# 功能1：获取手写数据及当前评级
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/handwriting`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 获取用于分析的手写笔迹视频和当前已有的评级分数。
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "video_url": "/api/v3/videos/handwriting_spiral_abc.mp4",
        "rating": 1 // 当前评级分数，如果未评级则为null
    }
}

// 记录不存在响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "record_not_found",
        "description": "The specified record does not exist."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to access this resource."
    }
}
```

# 功能2：提交/更新手写功能评级
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/handwriting/rating`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 提交对手写功能的评级分数（0-4）。
- **请求体**:
```json
{
    "rating": 2
}
```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "Handwriting rating updated successfully."
    }
}

// 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_rating_value",
        "description": "Rating must be an integer between 0 and 4."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```

### 4.5 语音分析页面 (UPDRS评级)
此部分提供对语音样本的评级，主要评估音量、音调、清晰度等言语功能。
- **言语功能评级标准 (参考UPDRS)**:
  - **0**: 正常，语言清晰，音量正常。
  - **1**: 轻微异常，音量轻度减弱或发音偶有含糊。
  - **2**: 轻度异常，语言单调、含糊，但尚能听懂。
  - **3**: 中度异常，语言严重含糊，听懂有较大困难。
  - **4**: 严重异常，语言基本无法听懂或失语。

# 功能1：获取语音及当前评级
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/speech`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 获取用于分析的语音文件和当前已有的评级分数。
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "audio_url": "/api/v3/audios/speech_sample_abc.wav",
        "rating": 3 // 当前评级分数，如果未评级则为null
    }
}

// 记录不存在响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "record_not_found",
        "description": "The specified record does not exist."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to access this resource."
    }
}
```

# 功能2：提交/更新言语功能评级
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/speech/rating`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 提交对言语功能的评级分数（0-4）。
- **请求体**:
```json
{
    "rating": 3
}
```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "Speech rating updated successfully."
    }
}

// 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_rating_value",
        "description": "Rating must be an integer between 0 and 4."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```

### 4.6 语义分析页面 (认知评级)
此部分提供对文本（例如，语音识别结果）的评级，主要评估思维连贯性、逻辑性和复杂性。
- **认知与语义连贯性评级标准 (自定义)**:
  - **0**: 正常，思维清晰，表达连贯，逻辑性强。
  - **1**: 轻微异常，偶有思维中断或逻辑不连贯之处。
  - **2**: 轻度异常，思维迟缓，表达重复，逻辑性差。
  - **3**: 中度异常，思维混乱，难以组织语言，表达缺乏逻辑。
  - **4**: 严重异常，无法形成有意义的句子或表达与问题完全无关。

# 功能1：获取文本及当前评级
- **路由**: `GET /api/v3/admin/logs/{table_name}/{log_id}/semantics`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 获取指定记录的文本内容和当前已有的认知评级分数。
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "text_content": "今天天气真好，我感觉心情非常愉快，虽然昨天有点不舒服，但现在好多了。",
        "rating": 0 // 当前评级分数，如果未评级则为null
    }
}

// 记录不存在响应
{
    "status": "error",
    "code": 404,
    "message": "Not Found",
    "error_details": {
        "type": "record_not_found",
        "description": "The specified record does not exist."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to access this resource."
    }
}
```

# 功能2：提交/更新认知评级
- **路由**: `POST /api/v3/admin/logs/{table_name}/{log_id}/semantics/rating`
- **认证**: `Authorization: Bearer {access_token}`
- **说明**: 提交对认知与语义连贯性的评级分数（0-4）。
- **请求体**:
```json
{
    "rating": 1
}
```
- **响应**:
```json
// 成功响应
{
    "status": "success",
    "code": 200,
    "data": {
        "message": "Semantic rating updated successfully."
    }
}

// 请求无效响应
{
    "status": "error",
    "code": 400,
    "message": "Bad Request",
    "error_details": {
        "type": "invalid_rating_value",
        "description": "Rating must be an integer between 0 and 4."
    }
}

// 未授权响应
{
    "status": "error",
    "code": 403,
    "message": "Forbidden",
    "error_details": {
        "type": "permission_denied",
        "description": "You do not have permission to modify this resource."
    }
}
```