BodyBalanceEvaluation/README.md

# 身体平衡评估系统

一个基于多传感器融合技术的专业身体平衡评估与分析系统，为用户提供准确的平衡能力评估和康复指导。

## 系统特性

### 🎯 核心功能
- **实时姿态检测**: 基于MediaPipe的高精度人体姿态识别
- **多传感器融合**: 整合摄像头、IMU传感器和压力传感器数据
- **智能分析引擎**: 多维度平衡能力评估算法
- **实时视频流**: WebSocket实时视频传输和显示
- **检测数据采集**: 一键采集当前检测状态的数据快照
- **视频录制功能**: 支持检测过程的视频录制和回放
- **可视化报告**: 直观的数据图表和分析报告
- **历史数据管理**: 完整的检测记录存储和对比分析

### 🔧 技术特点
- **现代化架构**: Vue 3 + Python Flask 前后端分离
- **实时通信**: WebSocket 实时数据传输和视频流
- **多媒体支持**: 集成视频录制、截图和数据采集功能
- **跨平台支持**: Windows、macOS、Linux
- **模块化设计**: 清晰的目录结构，易于扩展和维护
- **数据安全**: 本地存储，保护用户隐私
- **开发友好**: 独立的前后端开发环境，支持热重载
- **部署简化**: 一键安装和启动脚本，降低部署复杂度

## 系统架构

```
身体平衡评估系统/
├── backend/                 # 后端服务
│   ├── main.py             # 主启动脚本
│   ├── app.py              # Flask 主应用
│   ├── database.py         # 数据库管理
│   ├── device_manager.py   # 设备管理
│   ├── detection_engine.py # 检测引擎
│   ├── data_processor.py   # 数据处理
│   ├── utils.py            # 工具函数
│   └── requirements.txt    # Python 依赖
├── frontend/               # 前端应用
│   └── src/renderer/       # 前端源码
│       ├── src/
│       │   ├── views/      # 页面组件
│       │   ├── stores/     # 状态管理
│       │   ├── services/   # API 服务
│       │   └── router/     # 路由配置
│       ├── package.json    # Node.js 依赖
│       └── vite.config.js  # 构建配置
├── data/                   # 数据目录
├── logs/                   # 日志目录
├── venv/                   # Python 虚拟环境
├── install.bat             # 安装脚本
├── start_dev.bat           # 开发模式启动脚本
└── start_prod.bat          # 生产模式启动脚本
```

## 快速开始

### 环境要求

- **Python**: 3.8 或更高版本
- **Node.js**: 16.0 或更高版本 (开发模式)
- **操作系统**: Windows 10/11, macOS 10.15+, Ubuntu 18.04+

### 安装步骤

#### 方式一：一键安装 (Windows 推荐)

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd BodyBalanceEvaluation
   ```

2. **运行安装脚本**
   ```bash
   install.bat
   ```
   
   安装脚本会自动完成：
   - 检查 Python 和 Node.js 环境
   - 创建 Python 虚拟环境
   - 安装后端依赖
   - 安装前端依赖
   - 创建必要的目录结构

#### 方式二：手动安装

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd BodyBalanceEvaluation
   ```

2. **创建虚拟环境**
   ```bash
   python -m venv venv
   venv\Scripts\activate  # Windows
   # source venv/bin/activate  # macOS/Linux
   ```

3. **安装 Python 依赖**
   ```bash
   pip install -r backend/requirements.txt
   ```

4. **安装前端依赖** (开发模式)
   ```bash
   cd frontend/src/renderer
   npm install
   cd ../../..
   ```

### 启动应用程序
   
   **Windows 用户 (推荐)**:
   ```bash
   # 一键安装 (首次使用)
   install.bat
   
   # 开发模式
   start_dev.bat
   
   # 生产模式
   start_prod.bat
   ```
   
   **手动启动**:
   ```bash
   # 激活虚拟环境
   venv\Scripts\activate
   
   # 进入后端目录
   cd backend
   
   # 开发模式
   python main.py --mode development
   
   # 生产模式
   python main.py --mode production
   ```

### 命令行参数

```bash
cd backend
python main.py [选项]

选项:
  --mode {development,production}  运行模式 (默认: development)
  --host HOST                     服务器主机 (默认: 127.0.0.1)
  --port PORT                     服务器端口 (默认: 5000)
  --no-browser                    不自动打开浏览器
  --log-level {DEBUG,INFO,WARNING,ERROR}  日志级别 (默认: INFO)
```

## 使用指南

### 1. 系统设置

首次使用前，请进入「系统设置」页面配置：

- **设备配置**: 选择摄像头、配置串口设备
- **检测参数**: 设置默认检测时长、采样频率等
- **数据管理**: 配置数据存储路径和清理策略

### 2. 患者管理

- 添加患者基本信息（姓名、年龄、性别等）
- 记录患者病史和康复目标
- 管理患者档案和检测记录

### 3. 姿态检测

1. **选择患者**: 从患者列表中选择或新建患者
2. **设备准备**: 确保摄像头和传感器正常连接
3. **开始检测**: 点击开始按钮进行实时检测
4. **实时监控**: 通过实时视频流观察检测过程
5. **数据采集**: 在检测过程中点击"检测数据采集"按钮获取当前状态数据
6. **视频录制**: 使用"开始录制"/"停止录制"按钮记录检测过程
7. **停止检测**: 完成检测并自动计算检测时长
8. **查看结果**: 检测完成后查看分析结果和建议

### 4. 数据分析

- **单次分析**: 查看单次检测的详细数据和图表
- **对比分析**: 比较多次检测结果，观察变化趋势
- **报告生成**: 生成 PDF 格式的专业评估报告
- **数据导出**: 导出原始数据用于进一步分析

### 5. 历史记录

- 浏览所有历史检测记录
- 按患者、日期、状态等条件筛选
- 批量导出和删除操作
- 时间线视图查看检测历史

## 设备支持

### 摄像头
- USB 摄像头 (推荐 1080p 30fps)
- 内置摄像头
- 网络摄像头

### IMU 传感器
- 支持串口通信的 9 轴 IMU
- 波特率: 9600, 115200, 230400
- 数据格式: 加速度、陀螺仪、磁力计

### 压力传感器
- 多点压力传感器阵列
- 串口通信接口
- 支持 1-16 个传感器点

## 开发指南

### 后端开发

后端使用 Flask 框架，主要模块：

- `main.py`: 主启动脚本和进程管理
- `app.py`: 主应用和 API 路由
- `database.py`: SQLite 数据库操作
- `device_manager.py`: 硬件设备管理和视频流处理
- `detection_engine.py`: 检测算法引擎
- `data_processor.py`: 数据分析和处理

### 主要API端点

- `POST /api/detection/start`: 开始检测会话
- `POST /api/detection/{session_id}/stop`: 停止检测会话
- `POST /api/detection/{session_id}/collect`: 采集检测数据
- `WebSocket /ws`: 实时数据和视频流传输

### 前端开发

前端使用 Vue 3 + Element Plus，主要特性：

- **组合式 API**: 使用 Vue 3 Composition API
- **状态管理**: Pinia 状态管理库
- **UI 组件**: Element Plus 组件库
- **图表库**: ECharts 数据可视化
- **构建工具**: Vite 快速构建

### 添加新功能

1. **后端 API**:
   ```python
   @app.route('/api/new-feature', methods=['POST'])
   def new_feature():
       # 实现新功能逻辑
       return jsonify({'status': 'success'})
   ```

2. **前端服务**:
   ```javascript
   // frontend/src/renderer/src/services/api.js
   export const newFeatureAPI = {
     doSomething: (data) => api.post('/new-feature', data)
   }
   ```

3. **前端组件**:
   ```vue
   <template>
     <!-- 新功能界面 -->
   </template>
   
   <script setup>
   import { newFeatureAPI } from '../services/api'
   </script>
   ```

### 项目结构优势

新的项目结构带来以下优势：

1. **清晰分离**: 前后端代码完全分离，便于团队协作开发
2. **独立部署**: 前后端可以独立部署和扩展
3. **开发效率**: 前后端可以并行开发，提高开发效率
4. **维护性**: 模块化结构便于代码维护和功能扩展
5. **版本管理**: 前后端可以独立进行版本控制
6. **技术栈**: 前后端可以选择最适合的技术栈

### 开发环境配置

**后端开发**:
```bash
# 激活虚拟环境
venv\Scripts\activate

# 进入后端目录
cd backend

# 启动开发服务器
python main.py --mode development --log-level DEBUG
```
python debug_server.py

**前端开发**:
```bash
# 进入前端目录
cd frontend/src/renderer

# 启动开发服务器
npm run dev
```

**同时开发** (推荐):
```bash
# 使用开发脚本同时启动前后端
start_dev.bat
```

## 故障排除

### 常见问题

**Q: 摄像头无法识别**
A: 检查摄像头连接，确保没有被其他应用占用，在设备设置中刷新摄像头列表。

**Q: 传感器连接失败**
A: 确认串口设置正确，检查设备驱动是否安装，尝试不同的波特率设置。

**Q: 前端页面无法加载**
A: 检查后端服务是否正常启动，确认防火墙设置，查看浏览器控制台错误信息。

**Q: 检测结果不准确**
A: 确保设备已正确校准，检查环境光线条件，调整检测参数设置。

**Q: 视频录制失败**
A: 检查磁盘空间是否充足，确认录制权限设置，查看后端日志中的错误信息。

**Q: WebSocket连接断开**
A: 检查网络连接稳定性，确认防火墙未阻止WebSocket连接，尝试刷新页面重新连接。

### 日志查看

系统日志保存在 `logs/` 目录下：

- `app.log`: 应用程序主日志
- `device.log`: 设备管理日志
- `detection.log`: 检测引擎日志
- `error.log`: 错误日志

### 性能优化

1. **硬件要求**:
   - CPU: Intel i5 或同等性能
   - 内存: 8GB RAM
   - 存储: 10GB 可用空间

2. **软件优化**:
   - 关闭不必要的后台程序
   - 使用 SSD 存储提高 I/O 性能
   - 定期清理历史数据和日志

## 数据格式

### 检测数据结构

```json
{
  "session_id": "uuid",
  "patient_id": "patient_uuid",
  "timestamp": "2024-01-01T12:00:00Z",
  "duration": 60,
  "data": {
    "camera": {
      "landmarks": [...],
      "confidence": 0.95
    },
    "imu": {
      "acceleration": [x, y, z],
      "gyroscope": [x, y, z],
      "magnetometer": [x, y, z]
    },
    "pressure": {
      "sensors": [p1, p2, p3, p4],
      "center_of_pressure": [x, y]
    }
  },
  "recording": {
    "video_path": "path/to/video.mp4",
    "screenshots": ["path/to/screenshot1.png"]
  }
}
```

### 分析结果格式

```json
{
  "session_id": "uuid",
  "analysis_time": "2024-01-01T12:01:00Z",
  "overall_assessment": "good",
  "balance_score": 85,
  "posture_score": 78,
  "metrics": {
    "sway_area": 2.5,
    "sway_velocity": 1.2,
    "postural_stability": 0.85
  },
  "recommendations": [
    "建议加强核心肌群训练",
    "注意保持正确站姿"
  ]
}
```

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 支持

如果您遇到问题或有建议，请：

- 查看 [FAQ](docs/FAQ.md)
- 提交 [Issue](issues)
- 发送邮件至: support@example.com

## 更新日志

### v1.2.0 (2024-01-20)
- **检测功能增强**: 新增检测数据采集功能，支持实时数据快照
- **视频录制**: 集成视频录制功能，支持检测过程的完整记录
- **实时视频流**: 优化WebSocket视频传输，提供流畅的实时监控
- **API优化**: 重构检测相关API，使用RESTful设计模式
- **用户体验**: 改进检测界面，添加录制控制和数据采集按钮
- **生命周期管理**: 完善组件生命周期处理，确保资源正确释放

### v1.1.0 (2024-01-15)
- **项目重构**: 前后端完全分离，优化项目结构
- **新增脚本**: 添加一键安装和启动脚本 (install.bat, start_dev.bat, start_prod.bat)
- **开发体验**: 改进开发环境配置，支持独立的前后端开发
- **文档更新**: 完善 README 文档，添加详细的安装和使用说明
- **路径优化**: 统一使用虚拟环境，规范化依赖管理

### v1.0.0 (2024-01-01)
- 初始版本发布
- 基础检测功能
- 患者管理系统
- 数据分析和报告生成

---

**身体平衡评估系统** - 专业的平衡能力评估解决方案