BodyBalanceEvaluation/README.md

# 身体平衡评估系统

一个基于多传感器融合的身体平衡评估与分析系统，提供姿态检测、视频录制、数据采集与评估报告等功能。

## 系统特性

- 实时姿态检测与数据采集
- 多设备管理（摄像头、IMU、压力传感器）
- 视频录制与文件存储规范化
- 本地数据库管理与历史记录
- 静态文件HTTP访问映射
- 开发与打包环境兼容
- 数据安全：本地存储，保护用户隐私

## 目录结构（当前）

```
BodyBalanceEvaluation/
├── backend/
│   ├── main.py                  # AppServer 后端入口（推荐）
│   ├── app.py                   # 备用后端入口（历史版本）
│   ├── database.py              # 数据库管理
│   ├── device_manager.py        # 设备统一管理（旧版）
│   ├── check_monitor_status.py  # 设备连接状态检查脚本
│   ├── build_app.py             # 打包相关脚本
│   ├── config.ini               # 后端配置文件（可选）
│   ├── data/                    # 默认数据目录（开发环境）
│   ├── devices/
│   │   ├── camera_manager.py
│   │   ├── screen_recorder.py
│   │   ├── imu_manager.py
│   │   ├── pressure_manager.py
│   │   ├── femtobolt_manager.py
│   │   ├── device_coordinator.py
│   │   └── utils/
│   │       └── config_manager.py  # 配置管理器（设备侧）
│   ├── requirements.txt          # 运行依赖
│   └── requirements_build.txt    # 打包依赖
├── frontend/
│   └── src/renderer/             # Electron + 前端资源
├── config.ini                     # 顶层配置（可选，优先就近）
├── data/
│   └── patients/                 # 示例数据目录
└── README.md
```

## 安装与运行

### 后端（开发）

- 创建并激活虚拟环境
  - `python -m venv venv`
  - `venv\Scripts\activate`（Windows）
- 安装依赖
  - `pip install -r backend/requirements.txt`
- 启动后端服务（推荐入口）
  - `python backend/main.py --host 0.0.0.0 --port 5000 --debug`

说明：`main.py` 使用 `AppServer` 类，启动时会初始化 `ConfigManager`、数据库管理器、设备协调器及相关路由。


### 前端与打包

- Electron 在 `frontend/src/renderer/main/main.js` 中启动本地静态服务器，并在打包环境下拉起后端可执行文件：
  - `resources/backend/BodyBalanceBackend/BodyBalanceBackend.exe`
- 前端调用后端 API 与静态文件路由相互独立。

## 配置说明

系统配置由设备侧 `ConfigManager` 统一读取（`backend/devices/utils/config_manager.py`）。常用节：

- `[FILEPATH]`
  - `path`：文件存储根目录。支持绝对路径或相对路径。
    - 绝对路径示例：`D:/BodyCheck/file`
    - 相对路径示例：`data` 或 `../data`（相对 `main.py` 所在目录或打包 `exe` 同级目录）
- `[DATABASE]`
  - `path`：数据库文件路径（支持相对/绝对）。

示例（`backend/config.ini` 或项目根 `config.ini`）：

```
[FILEPATH]
path = D:/BodyCheck/file

[DATABASE]
path = data/body_balance.db
```

## 静态文件访问

- 后端提供静态文件映射路由（`backend/main.py`）：
  - `GET /<path:filename>`
  - 访问路径会在服务端拼接至 `[FILEPATH].path` 指定的存储根目录下。
  - 例如：配置 `path = D:/BodyCheck/file`，则访问 `http://host:port/202508190001/20251014111329/video_111331358/screen.mp4`
    会映射到 `D:/BodyCheck/file/202508190001/20251014111329/video_111331358/screen.mp4`。
- 安全校验：
  - 路径规范化与越界拦截（拒绝 `..`、绝对路径、UNC 路径）。
  - 仅允许访问 `[FILEPATH].path` 根目录内的资源。
  - 视频类文件设置正确的 `Content-Type` 与 `Accept-Ranges`（流式播放友好）。

注：如果需要固定前缀路由（如 `/data/<path:filename>`），可以在 `main.py` 中将路由前缀改为 `/data`，逻辑保持不变。

## 录制与数据存储

- `screen_recorder.py` 在类初始化时注入 `ConfigManager`，并在录制/采集流程中统一从 `[FILEPATH].path` 读取文件根目录。
- 目录规范建议：`<root>/<patient_id>/<session_id>/<timestamp>`，业务层可按需要扩展子目录与文件命名。
- 当配置为相对路径时，开发环境相对 `backend/` 目录，打包环境相对 `exe` 同级目录。

## 主要 API（摘录）

- `GET /health`：健康检查
- `POST /api/detection/start`：开始检测（创建会话）
- `POST /api/detection/<session_id>/stop`：停止检测并保存录制内容
- `GET /<path:filename>`：静态文件映射至 `[FILEPATH].path`

说明：更多设备管理、状态广播与检测过程接口，参见 `backend/main.py` 内路由与 SocketIO 事件注册。

## 开发建议

- 统一通过 `ConfigManager` 访问配置，避免硬编码路径。
- 读取与写入文件路径时使用 `os.path.normpath/abspath/realpath` 进行规范化。
- 对外提供文件访问统一通过静态路由，确保安全校验与越界防护。
- 开发与打包环境下路径基础目录不同，尽量通过配置与规范化处理屏蔽差异。

## 数据安全

- 所有数据采用本地存储，避免敏感信息外泄。
- 静态文件访问包含越界保护，限制访问至配置的存储根目录内。
- 建议对患者身份信息进行匿名化处理（如ID映射）。