ac99c1342d
- backend/.env.example: AI 网关地址 129.146.203.203 → 129.146.26.249； MariaDB 注释段更新为生产实际（garmin 专用账号 @ 127.0.0.1:3306，socket 已不用） - README: 生产数据层/数据库说明改为 Oracle 新机本地 MariaDB 10.3 - docs/REQUIREMENTS: 部署目标 NAS → Oracle 新机；公网方式 frp 隧道 → gunicorn 直绑 8123 - docs/ARCHITECTURE: 部署架构改为真实生产栈（Flask+gunicorn+MariaDB+SPA）
6.0 KiB
6.0 KiB
项目架构说明
整体架构
┌─────────────────────────────────────────────────────┐
│ 浏览器 (React 前端) │
│ ┌────────────┬──────────────┬──────────┬──────────┐ │
│ │ 仪表板 │ 数据同步 │ 数据分析 │ 设置 │ │
│ └────────────┴──────────────┴──────────┴──────────┘ │
└──────────────────────────┬──────────────────────────┘
│ HTTP/REST
▼
┌──────────────────────────────────────────────────────┐
│ Node.js/Express 后端服务器 │
│ ┌──────────────────────────────────────────────┐ │
│ │ API 路由层 │ │
│ │ ├─ /auth - 用户认证 │ │
│ │ ├─ /garmin - Garmin 数据同步 │ │
│ │ ├─ /health - 健康数据查询 │ │
│ │ └─ /analysis - 数据分析 │ │
│ └──────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ 服务层 │ │
│ │ ├─ GarminService - Garmin API 集成 │ │
│ │ ├─ HealthService - 健康数据业务逻辑 │ │
│ │ ├─ AuthService - 认证授权 │ │
│ │ └─ AnalysisService - 数据分析 │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ SQLite 数据库 │
│ ├─ users │
│ ├─ health_data │
│ ├─ activities │
│ └─ sync_status │
└──────────────────────────────┘
┌──────────────────────────────┐
│ Garmin Cloud API │
│ ├─ 用户认证 │
│ ├─ 数据获取 │
│ └─ 数据同步 │
└──────────────────────────────┘
核心模块
1. 前端 (Client)
- 框架: React 18 + TypeScript
- 路由: React Router
- UI 组件: 自定义 + CSS
- 数据可视化: Recharts
- API 通信: Axios
主要页面:
- Dashboard (仪表板)
- DataSync (数据同步)
- Analysis (数据分析)
- Recommendations (健康建议)
- Settings (设置)
2. 后端 (Server)
- 框架: Express.js
- 语言: TypeScript
- 数据库: SQLite3
- 认证: JWT
主要服务:
- AuthService: 用户认证和授权
- GarminService: Garmin API 集成和数据获取
- HealthService: 健康数据管理
- AnalysisService: 数据分析和建议生成
3. 数据库 (SQLite)
表结构:
users: 用户信息和 Garmin 凭证health_data: 每日健康数据汇总activities: 运动活动记录sync_status: 数据同步状态追踪
数据流
1. Garmin 数据同步流程
用户点击"同步"
↓
POST /api/garmin/sync
↓
GarminService.syncData()
↓
获取 Garmin 授权 Token
↓
调用 Garmin API 获取数据
↓
转换数据格式
↓
存储到本地 SQLite
↓
更新 sync_status
↓
返回同步结果
2. 数据分析流程
GET /api/health/summary (日期范围)
↓
从数据库查询健康数据
↓
计算统计指标
↓
生成趋势分析
↓
返回分析结果
↓
前端绘制图表
3. 健康建议生成流程
GET /api/analysis/recommendations
↓
AnalysisService.generateRecommendations()
↓
分析历史数据
↓
识别异常和趋势
↓
根据规则引擎生成建议
↓
按优先级排序
↓
返回建议列表
关键特性
安全性
- Garmin 密码使用加密存储
- JWT 令牌验证所有请求
- CORS 配置限制来源
- 环境变量管理敏感配置
扩展性
- 模块化的服务设计
- 易于添加新的分析算法
- 支持数据导出功能
- 可扩展的 API 端点
性能
- 数据库索引优化查询
- API 缓存策略
- 异步处理长运行任务
- 增量数据同步支持
部署架构
- Development 本地开发：
npm run dev同时启动前后端 —— Vite/React (3000/5173) + Flask (5000, SQLite)。 - Production 生产环境（Oracle 云服务器 129.146.26.249）：
- Flask + gunicorn 直绑
0.0.0.0:8123（systemdgarmin-health-lab.service，开机自启） - React SPA 静态包由后端
STATIC_DIR提供 - MariaDB 10.3（
127.0.0.1:3306，专用账号garmin，库garmin_health_lab） - AI 网关
129.146.26.249:5100/v1
- Flask + gunicorn 直绑