38 KiB

Raw Permalink Blame History

📌 软件框架概述

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

📋 页面1：用户注册页面 (扫码)

说明: 此页面通过二维码引导用户进行自助注册，适用于现场排队等候的场景。管理员可在管理后台生成或展示此注册页面的二维码。
跳转条件:
- 新用户注册成功后跳转到基本信息确认页面
路由: /api/v3/register
访问方式：POST
注意事项:
- 新用户填写完毕后也需要跳信息确认，确认前不要弹给后端
- 确认后等待后端返回，除非确认成功否则不跳转，提示用户修改对应字段
- 后端在确认无误后会插入数据库的patient_info表单。
请求参数:

{
    "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"                // 备注 (可选)
}

响应格式:

// 注册成功响应
{
    "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
请求参数：

{
    "username": "string",  // 用户名
    "password": "string"   // 密码
}

响应格式：

// 管理员用户响应
{
    "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

请求参数：无
响应：

// 开始推流成功响应
{
    "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

响应：

// 停止推流成功响应
{
    "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后，负责根据该标识查找并显示对应的提示文本，以及播放对应的语音提示。所有提示内容（文本、音频文件名）都预置在前端。

服务端推送数据:

{
    "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}
```
响应:

// 成功响应
{
    "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}
```
请求参数 (可选)：

{
    "system_prompt": "你是一个聊天机器人，请根据用户需求进行回应。",
    "max_history": 10
}

响应:

// 开始会话成功响应
{
    "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):

// 成功接收请求
{
    "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}
```
响应:

// 成功响应
{
    "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}
```
响应:

// 结束会话成功响应
{
    "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}

// 成功响应
{
    "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
返回:

// 成功响应
{
    "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}
说明: 进入步态分析页面时调用，获取该记录中所有行走分段的步态分析结果。一次记录可能包含多次行走，每次行走都是一个独立的分析单元。
响应:

{
    "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事件）。后端接收到新的事件列表后，将立即执行重新计算，并返回更新后的完整步态分析数据。
请求体:

{
    "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 }
    ]
}

响应:


- 成功响应：返回更新后的完整步态分析数据，结构同`功能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分数。
响应:

// 成功响应
{
    "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）。
请求体:

{
    "rating": 2
}

响应:

// 成功响应
{
    "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}
说明: 获取指定记录的眼动追踪视频和当前已有的评级分数。
响应:

// 成功响应
{
    "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）。
请求体:

{
    "rating": 3
}

响应:

// 成功响应
{
    "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}
说明: 获取用于分析的手写笔迹视频和当前已有的评级分数。
响应:

// 成功响应
{
    "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）。
请求体:

{
    "rating": 2
}

响应:

// 成功响应
{
    "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}
说明: 获取用于分析的语音文件和当前已有的评级分数。
响应:

// 成功响应
{
    "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）。
请求体:

{
    "rating": 3
}

响应:

// 成功响应
{
    "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}
说明: 获取指定记录的文本内容和当前已有的认知评级分数。
响应:

// 成功响应
{
    "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）。
请求体:

{
    "rating": 1
}

响应:

// 成功响应
{
    "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."
    }
}

38 KiB Raw Permalink Blame History