GarminHealthLab/docs/ARCHITECTURE.md

项目架构说明

现状（2026-09-02）：后端为 Python/Flask 单体，生产部署在 NAS :8124。 早期 Node.js/Express + server/ 目录的后端已被整体重写为 backend/（Python），本文件描述的是当前实现。

整体架构

┌──────────────────────────────────────────────────────────┐
│                    浏览器 (React SPA)                     │
│   Framework7 9 (iOS 主题) + Recharts，单端口同源部署        │
│   ┌──────┬──────┬──────┬──────┬──────────────┐           │
│   │ 今日 │ 健康 │ 趋势 │ 运动 │ 设置 / 更多…  │           │
│   └──────┴──────┴──────┴──────┴──────────────┘           │
└───────────────┬──────────────────────────────────────────┘
                │ HTTP/JSON + JWT（Bearer）；Copilot 用 SSE
                ▼
┌──────────────────────────────────────────────────────────┐
│            Flask 单体（gunicorn 2w/4t，NAS :8124）        │
│  ┌────────────────────────────────────────────────────┐  │
│  │ 蓝图层 routes/  /api/auth /api/garmin /api/health  │  │
│  │                 /api/analysis /api/settings        │  │
│  ├────────────────────────────────────────────────────┤  │
│  │ 服务层 services/  业务逻辑（无 Flask 依赖）          │  │
│  │  auth_hub_client  garmin garmin_auth garmin_extras │  │
│  │  scheduler(定时同步)  ai/coach/insights/jobs(AI队列) │  │
│  │  health analysis fitness_age settings scopes       │  │
│  ├────────────────────────────────────────────────────┤  │
│  │ 横切：auth.py(JWT+require_auth)  config.py(配置)    │  │
│  │      db.py(可插拔数据层+幂等迁移)                   │  │
│  └────────────────────────────────────────────────────┘  │
└───────┬──────────────────────────────┬──────────────────┘
        │                              │
        ▼                              ▼
┌──────────────────┐        ┌─────────────────────────────┐
│ SQLite (开发)     │        │ MariaDB (生产, NAS 10.11)   │
│ data/health.db   │        │ garmin_health_lab 库         │
│  DB_TYPE=sqlite  │        │ root@socket mysqld10.sock   │
└──────────────────┘        └─────────────────────────────┘
        ▲                              ▲
        │                              │
        │   外部系统（经 services/ 调用）│
        ▼                              ▼
┌──────────────────────────────────────────────────────────┐
│  auth-hub SSO      Garmin Cloud API    ai-gateway        │
│  129.146.26.249:   (OAuth, 账号级限流  (https://ai.zichuan │
│  5300 OIDC         429 → 退避24h)      .xyz/v1, NVIDIA推理)│
└──────────────────────────────────────────────────────────┘

• 单端口部署：Flask 既出 API 又托管 React 构建产物（STATIC_DIR），前端 API 请求为同源 /api/*（client/.env.production 写死 REACT_APP_API_URL=/api）。
• SPA 路由兜底：404 handler 对非 /api/ 路径回退 index.html，页面刷新不 404。

后端分层

routes/ — 蓝图（只做参数校验与序列化，逻辑在 services）

蓝图	前缀	主要端点
auth	/api/auth	SSO 登录 POST /auth-hub/start、GET /callback；POST /logout、/refresh
garmin	/api/garmin	POST /sync、/sync-latest、/sync-details；GET /auth-status、/login-status、/status、/auto-sync、/activities/<id>/detail；POST /login、/mfa、/disconnect；DELETE /login
health	/api/health	summary steps heart-rate sleep activities fitness-age badges personal-records body-composition blood-pressure race-predictions series challenges devices
analysis	/api/analysis	trends recommendations models ai-recommendations briefing trend-insight copilot(SSE) insight insight/queue
settings	/api/settings	GET/PUT "" GET /options GET /rating-basis

另有 GET /api/health/status（健康检查，app.py 直接定义）。

services/ — 领域逻辑

• garmin 同步族：garmin.py（核心同步 + 429 限流退避，rate_limited_until 持久化到 sync_status，以 DB 为准防多 worker 内存不一致）、garmin_auth.py （OAuth 登录 + MFA 验证码会话，跨 worker 经 garmin_mfa_sessions 表交接）、 garmin_extras.py（身体成分/血压/血氧/全天曲线/设备/徽章/挑战等扩展数据）。
• 调度与队列：scheduler.py（自动同步，DB job_locks 抢占，多 worker 只 跑一次）、jobs.py（AI 生产者/消费者队列，同表互斥，含 refill_backlog）。
• AI 教练：insights.py 特征工程（z 分数 / 趋势斜率 / 活动量对比）→ coach.py 三套提示词 + 规则引擎兜底 → ai.py 多模型链 + 缓存 ai_insights（数据指纹失效）。
• 其余：analysis.py / health.py / fitness_age.py（身体年龄推算）/ settings.py（设置吸附校验）/ auth_hub_client.py（OIDC 客户端）/ scopes.py。

认证链路（auth-hub SSO）

用户点「登录」→ POST /api/auth/auth-hub/start → 302 auth-hub 登录页
  → auth-hub 回调 GET /api/auth/callback?code=… → exchange_code_for_token
  → get_userinfo → find_or_create_user → 后端签 JWT（7 天）→ 前端存 localStorage

• 本地邮箱/密码注册登录已移除；每个账号来自 auth-hub。
• Garmin 账号授权是独立流程（与 Web 登录分开）：/api/garmin/login 起 OAuth 流程，需要验证码时 /api/garmin/mfa 提交，令牌存 garmin_tokens（约一年有效，密码不入库）。
• 所有数据路由经 require_auth 校验 JWT。

数据层（db.py 可插拔）

• DB_TYPE=sqlite（开发默认，backend/data/health.db）↔ DB_TYPE=mariadb （生产 NAS）。config.py 读取，业务代码不分叉。
• 20 张表：users health_data activities sync_status garmin_tokens badges personal_records job_locks garmin_mfa_sessions user_settings activity_details body_composition blood_pressure race_predictions daily_series challenges devices ai_recommendations ai_jobs ai_insights。
• init_db() 幂等（CREATE TABLE IF NOT EXISTS + 按列检测的 ALTER）， 多 gunicorn worker 并发调用安全。id 为 VARCHAR(64)，外键指向 users。

数据流

1. Garmin 同步（手动 + 自动）

用户/调度器触发
  → 检查 sync_status.rate_limited_until（429 冷却 24h，DB 为准）
  → garmin.py 分批拉取（health_data 每日指标、activities、daily_series 等）
  → 库内 upsert → 更新 sync_status → prefetch_insights（AI 洞察预取入队）

• 同步频率与历史范围（history_days）读用户设置；0 表示全部历史 = 730 天上限。
• 全天曲线每天 5 个请求：14 天内同步顺带拉取，更长的历史走「补齐详细数据」 后台任务（POST /api/garmin/sync-details 触发，队列消费）。

2. AI 晨报 / Copilot / 趋势归因

AI 作业入队(ai_jobs，优先级队列) → jobs.py worker 单飞消费(DB 互斥)
  → services/ai.py 调 ai-gateway(https://ai.zichuan.xyz/v1)
  → 结果写 ai_insights(指纹缓存) → 前端轮询 GET /analysis/insight 取回
Copilot: POST /analysis/copilot 走 SSE(stream_chat，失败非流式回退)

• 生产 AI_MODEL_CHAIN=gateway（单上游，网关内部再 fanout NVIDIA/Gemini/Ollama）。
• 队列并发 2、间隔 5s（共享网关，过高会 502）；晨报一次生成 2~5 分钟， 前端一律「后台生成 + 轮询」而非阻塞等待；meta.source 标注 AI 或规则引擎。

部署架构（生产）

• Development 本地：npm run dev = Flask 5000（BACKEND_PORT 固定，避开 PORT 被 CRA 抢占）+ CRA dev server 3000（proxy → 5000）。SQLite。
• Production NAS：192.168.50.64 /volume1/web/garmin-health-lab，root 跑 gunicorn 0.0.0.0:8124（2w/4t，--timeout 300 —— AI 生成可长达分钟级）， 开机自启 DSM 任务调度器 → deploy/S99garmin.sh；MariaDB 10.11 root@/run/mysqld/mysqld10.sock，库 garmin_health_lab。
• 公网：NAS frpc → 甲骨文 129.146.26.249:8124（frp 隧道，重连需数秒）。
• 一键部署：deploy/push.sh（tar-over-ssh 同步 backend+deploy、清空重推 client/build、sudo 重启、pid 变化 + health 200 双校验）；前端先 npm run build。deploy/start.sh / stop.sh 供手工与开机脚本调用。
• auth-hub：回调注册 LAN 192.168.50.64:8124 与公网 129.146.26.249:8124 两个地址（client 996aLPw4T5gl-rYZ）；CORS 白名单含两地址 + localhost。

关键设计约束

1. 阈值来自公开参考值，AI 只解读不定阈值；依据页面逐条列出处。
2. 本地日历日期优先于 UTC（toISOString() 陷阱见 DEVELOPMENT.md）。
3. 单点部署、无反向代理：同端口 API + SPA，减少一个故障面。
4. 多 worker 安全：一切跨进程协调走 DB（job_locks / garmin_mfa_sessions / ai_jobs / sync_status），不做进程内假设。
5. 可插拔数据层：业务代码不分叉 SQLite/MariaDB。