# 项目架构说明

## 整体架构

```
┌─────────────────────────────────────────────────────┐
│                 浏览器 (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 (同时运行前后端) │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│   Production 生产环境           │
│ ├─ Docker 容器化                │
│ ├─ Nginx 反向代理               │
│ ├─ Node.js 后端服务             │
│ └─ SQLite 数据持久化            │
└─────────────────────────────────┘
```