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）
168 lines
6.0 KiB
Markdown
168 lines
6.0 KiB
Markdown
# 项目架构说明
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 浏览器 (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`（systemd `garmin-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`
|