178 lines
8.4 KiB
Markdown
178 lines
8.4 KiB
Markdown
# 身体平衡评估系统
|
||
|
||
一个基于多传感器融合的身体平衡评估与分析系统，提供姿态检测、视频录制、数据采集与评估报告等功能。
|
||
|
||
## 系统特性
|
||
|
||
- 实时姿态检测与数据采集
|
||
- 多设备管理（摄像头、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映射）。
|
||
|
||
## 软件使用授权（License）
|
||
|
||
本系统支持基于数字签名的授权控制：客户端只持有公钥验证授权文件，授权签发（私钥）与密钥管理已从本项目剥离至外部项目 `D:/Trae_space/LicenseMange`。
|
||
|
||
### 授权概述
|
||
- 授权文件为 JSON，包含 `product`、`license_type`、`expires_at`、`machine_id`、`features` 等字段及数字签名。
|
||
- 签名算法：RSA-PSS + SHA256；客户端使用公钥验证签名，拒绝被篡改的授权文件。
|
||
- 机器绑定：`machine_id` 绑定授权到特定设备；不绑定可使用 `*`（视具体策略与后端实现而定）。
|
||
|
||
### 使用者流程（客户端获取 machine_id）
|
||
- 界面激活：在“激活/授权”界面生成激活请求，系统会显示并保存本机 `machine_id`，同时生成 `activation_request_<machine_id>.json`。
|
||
- API：
|
||
- `GET /api/license/info` 返回 `data.machine_id`
|
||
- `POST /api/license/activation-request`（Body 包含 `company_name`、`contact_info`），返回并写入激活请求文件。
|
||
- 将 `company_name`、`contact_info`、`machine_id` 提交给授权签发方（LicenseMange）。
|
||
|
||
### 授权者流程（在 LicenseMange 签发授权）
|
||
- 在 `D:/Trae_space/LicenseMange` 执行授权签发，生成授权文件（JSON）与交付包；详细见 `LicenseMange_开发文档.md`。
|
||
- 私钥仅保存在 LicenseMange 环境，不随客户端分发；客户端只需接收授权文件与公钥。
|
||
|
||
### 客户端部署授权
|
||
1. 将授权文件和公钥复制到客户端机器（推荐放置在 `backend/` 目录或你指定的配置路径）。
|
||
2. 在配置文件中设置 `[LICENSE]` 段（就近选择 `backend/config.ini` 或项目根 `config.ini`）：
|
||
|
||
```ini
|
||
[LICENSE]
|
||
path = d:/Trae_space/BodyBalanceEvaluation/backend/thb_license.json
|
||
public_key = d:/Trae_space/BodyBalanceEvaluation/backend/license_public_key.pem
|
||
grace_days = 7
|
||
dev_mode = False
|
||
```
|
||
|
||
3. 重启后端或应用，调用 `GET /api/license/info` 验证授权状态，应看到 `valid: true` 与授权详情。
|
||
4. 也可通过 `POST /api/license/verify` 上传授权文件，后端验证签名并保存至 `[LICENSE].path`。
|
||
|
||
### API 快速参考（与授权相关）
|
||
- `GET /api/license/info`：返回授权有效性、类型、到期时间、功能集和本机 `machine_id`。
|
||
- `POST /api/license/activation-request`：生成激活请求文件（包含 `machine_id`）。
|
||
- `POST /api/license/verify`：上传授权文件进行验证并保存。
|
||
|
||
### 安全注意事项
|
||
- 客户端不持有私钥，私钥不应存在于本项目与发布包中。
|
||
- 授权文件生成后不可手动编辑任何字段，否则签名验证将失败。
|
||
- 公钥需与签发私钥成对；轮换密钥后需更新客户端公钥并重新签发授权文件。
|
||
|
||
### 与 LicenseMange 的关系
|
||
- 本项目仅负责授权验证与业务运行；签发、密钥生成/管理、交付均在 `LicenseMange` 承担。
|
||
- 如需查看签发流程、CLI、目录结构与审计规范，请参考：`D:/Trae_space/LicenseMange/LicenseMange_开发文档.md`。 |