ThbTech/BodyBalanceEvaluation
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dev-v15
BodyBalanceEvaluation/README.md

8.4 KiB
Raw Permalink Blame History

身体平衡评估系统

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

系统特性

  • 实时姿态检测与数据采集
  • 多设备管理（摄像头、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）：
[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
  1. 重启后端或应用，调用 GET /api/license/info 验证授权状态，应看到 valid: true 与授权详情。
  2. 也可通过 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。