# 数据采集规则说明

## 概述

本文档详细说明了身体平衡评估系统的数据采集规则，包括从各种传感器设备采集数据、生成图片并存储到指定路径的完整流程。

## 数据库表结构

### detection_data 表结构

```sql
CREATE TABLE IF NOT EXISTS detection_data (
    id TEXT PRIMARY KEY,                               -- 记录唯一标识(YYYYMMDDHHMMSS)年月日时分秒
    session_id TEXT NOT NULL,                          -- 检测会话ID（外键）
    head_pose TEXT,                                    -- 头部姿态数据（JSON格式）
    body_pose TEXT,                                    -- 身体姿态数据（JSON格式）
    body_image TEXT,                                   -- 身体视频截图存储路径
    foot_data TEXT,                                    -- 足部姿态数据（JSON格式）
    foot_image TEXT,                                   -- 足部监测视频截图存储路径
    foot_data_image TEXT,                              -- 足底压力数据图存储路径
    screen_image TEXT,                                 -- 屏幕录制视频截图存储路径
    timestamp TIMESTAMP,                               -- 数据记录时间戳
    FOREIGN KEY (session_id) REFERENCES detection_sessions (id)  -- 检测会话表外键约束
)
```

## 数据采集方法

### 方法签名

```python
def collect_data(self, session_id: str, patient_id: str, screen_image_base64: str = None) -> Dict[str, Any]
```

### 参数说明

- `session_id`: 检测会话ID，用于关联检测会话
- `patient_id`: 患者ID，用于构建存储路径
- `screen_image_base64`: 前端界面截图的base64编码数据（可选）

## 数据采集详细规则

### 1. 头部姿态数据 (head_pose)

**数据源**: IMU传感器设备
**存储格式**: JSON字符串
**数据内容**:
- `roll`: 翻滚角度 (-30° 到 30°)
- `pitch`: 俯仰角度 (-30° 到 30°)
- `yaw`: 偏航角度 (-180° 到 180°)
- `acceleration`: 三轴加速度数据 (x, y, z)
- `gyroscope`: 三轴陀螺仪数据 (x, y, z)
- `timestamp`: 数据采集时间戳

**示例数据**:
```json
{
    "roll": 15.2,
    "pitch": -8.7,
    "yaw": 45.3,
    "acceleration": {
        "x": 0.5,
        "y": -0.2,
        "z": 9.8
    },
    "gyroscope": {
        "x": 1.2,
        "y": -0.8,
        "z": 2.1
    },
    "timestamp": "2024-01-15T10:30:45.123"
}
```

### 2. 身体姿态数据 (body_pose)

**数据源**: FemtoBolt深度相机
**存储格式**: JSON字符串
**数据内容**:
- `keypoints`: 身体关键点坐标和置信度
  - 头部、颈部、肩膀、肘部、手腕
  - 脊柱、髋部、膝盖、脚踝
- `balance_score`: 平衡评分 (0.0-1.0)
- `center_of_mass`: 重心坐标
- `timestamp`: 数据采集时间戳

**示例数据**:
```json
{
    "keypoints": {
        "head": {"x": 320, "y": 100, "confidence": 0.95},
        "neck": {"x": 320, "y": 150, "confidence": 0.92},
        "left_shoulder": {"x": 280, "y": 180, "confidence": 0.88},
        "right_shoulder": {"x": 360, "y": 180, "confidence": 0.90}
    },
    "balance_score": 0.85,
    "center_of_mass": {"x": 320, "y": 350},
    "timestamp": "2024-01-15T10:30:45.123"
}
```

### 3. 身体视频截图 (body_image)

**数据源**: FemtoBolt深度相机
**存储路径**: `data/patients/{患者ID}/{sessionID}/{采集时间}/body_image.jpg`
**文件格式**: JPG图片
**图片尺寸**: 640x480像素

### 4. 足部压力数据 (foot_data)

**数据源**: 压力传感器 (pressure_sensor)
**存储格式**: JSON字符串
**数据内容**:
- `left_foot`: 左脚各区域压力值
  - `heel`: 脚跟压力
  - `arch`: 足弓压力
  - `ball`: 前脚掌压力
  - `toes`: 脚趾压力
  - `total_pressure`: 总压力
- `right_foot`: 右脚各区域压力值
- `balance_ratio`: 左右脚压力平衡比例
- `timestamp`: 数据采集时间戳

**示例数据**:
```json
{
    "left_foot": {
        "heel": 45.2,
        "arch": 12.8,
        "ball": 38.5,
        "toes": 22.1,
        "total_pressure": 118.6
    },
    "right_foot": {
        "heel": 42.8,
        "arch": 15.2,
        "ball": 35.9,
        "toes": 19.7,
        "total_pressure": 113.6
    },
    "balance_ratio": 0.51,
    "timestamp": "2024-01-15T10:30:45.123"
}
```

### 5. 足部监测视频截图 (foot_image)

**数据源**: 摄像头 (camera)
**存储路径**: `data/patients/{患者ID}/{sessionID}/{采集时间}/foot_image.jpg`
**文件格式**: JPG图片
**图片尺寸**: 640x480像素

### 6. 足底压力数据图 (foot_data_image)

**数据源**: 基于压力传感器数据生成的可视化图片
**存储路径**: `data/patients/{患者ID}/{sessionID}/{采集时间}/foot_data_image.jpg`
**文件格式**: JPG图片
**图片内容**: 足底压力分布热力图
**图片尺寸**: 400x600像素

### 7. 屏幕录制截图 (screen_image)

**数据源**: 前端界面截图（base64编码数据）
**存储路径**: `data/patients/{患者ID}/{sessionID}/{采集时间}/screen_image.jpg`
**文件格式**: JPG图片
**数据传输**: 通过参数 `screen_image_base64` 传入

## 目录结构规则

### 数据存储目录结构

```
data/
└── patients/
    └── {患者ID}/
        └── {sessionID}/
            └── {采集时间}/
                ├── body_image.jpg          # 身体视频截图
                ├── foot_image.jpg          # 足部监测视频截图
                ├── foot_data_image.jpg     # 足底压力数据图
                └── screen_image.jpg        # 屏幕录制截图
```

### 采集时间格式

- 格式: `YYYYMMDD_HHMMSS_mmm`
- 说明: 年月日_时分秒_毫秒
- 示例: `20240115_103045_123`

## 数据采集流程

1. **初始化**: 接收 `session_id`、`patient_id` 和可选的 `screen_image_base64` 参数
2. **生成时间戳**: 创建精确到毫秒的时间戳作为采集标识
3. **创建目录**: 根据患者ID、会话ID和时间戳创建存储目录
4. **设备状态检查**: 检查各设备连接状态
5. **数据采集**: 按顺序采集各设备数据
   - IMU传感器 → 头部姿态数据
   - FemtoBolt深度相机 → 身体姿态数据和身体截图
   - 压力传感器 → 足部压力数据和压力分布图
   - 摄像头 → 足部监测截图
   - 前端界面 → 屏幕截图
6. **数据存储**: 将采集的数据保存到数据库和文件系统
7. **日志记录**: 记录采集过程和结果

## 错误处理

- 设备连接失败时，对应数据字段设为 `None`
- 文件保存失败时，记录错误日志并继续其他数据采集
- 采集过程中的异常不会中断整个流程
- 所有错误信息都会记录到系统日志中

## 数据质量保证

- 所有时间戳使用统一格式
- 图片文件使用相对路径存储
- JSON数据格式验证
- 文件完整性检查
- 设备状态实时监控

## 性能优化

- 并发数据采集（在设备支持的情况下）
- 图片压缩优化
- 内存使用监控
- 磁盘空间管理
- 数据采集超时控制

## 注意事项

1. 确保所有设备在采集前已正确初始化
2. 定期检查存储空间，避免磁盘满载
3. 采集频率应根据实际需求调整
4. 敏感数据需要加密存储
5. 定期备份重要数据
6. 遵循数据隐私保护规定

---

*本文档版本: 1.0*  
*最后更新: 2025年8月*  
*维护人员: 系统开发团队*