## 📌 软件框架概述 该架构是一个单机前后端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." } } ```