GarminHealthLab/PROGRESS.md

Garmin Health Lab — 项目进度

已完成

部署

• 后端从 Node.js 重构为 Python/Flask
• 数据层可插拔：开发用 SQLite，生产用 MariaDB
• Gunicorn 生产服务器配置（2 workers / 4 threads）
• 部署到本地 NAS（/volume1/web/garmin-health-lab），端口 8124
• frp 隧道配置，通过甲骨文公网 IP 外网访问（http://129.146.26.249:8124）
• 开机自启脚本（deploy/S99garmin.sh）
• 甲骨文 iptables 放行 8124 端口

认证

• auth-hub 统一登录接入（OAuth2 / OIDC）
• 新建 NAS 专用 client（client_id: 996aLPw4T5gl-rYZ）
• 注册 NAS 回调地址 http://192.168.50.64:8124/auth/callback 和公网地址 http://129.146.26.249:8124/auth/callback
• JWT 令牌签发与验证
• Garmin OAuth 令牌授权（密码不入库，令牌约一年有效）

后端功能

• Garmin 数据同步核心逻辑（services/garmin.py）
• 后台自动同步调度器（services/scheduler.py）
• 用户设置：身高/体重/出生日期/性别/单位/同步频率/历史范围（services/settings.py）
• 健康数据分析服务（services/analysis.py）
• 身体年龄计算（services/fitness_age.py）
• 运动详情与全天曲线同步（services/extras.py）
• 可插拔数据层（db.py，支持 SQLite ↔ MariaDB 切换）
• 集中配置管理（config.py，从 .env 读取）
• 自动同步调度器读取用户 history_days 设置（修复前固定 2 天）

前端功能

• 仪表板：健康数据概览
• 趋势分析：数据可视化与趋势图（Recharts）
• 数据同步页：同步最新数据 / 同步历史 / 补齐详细数据
• 同步进度轮询与状态展示
• 设置页：个人资料、单位、自动同步、历史范围
• 评分依据：每个评级分段的公开参考值来源
• 数据绑定页：Garmin 邮箱+密码输入
• 历史范围选项：自上次同步 / 全部历史 / N 天 / N 年

同步逻辑修复

• 自动同步调度器认用户设置的 history_days，不再固定 2 天
• 前端 0（全部历史）不再被 || 吞掉，改为 ?? 处理
• 后端路由和 sync_data 中 0 不再被当成 falsy 回退默认值
• sync_data 中 0 → 730 天（全部历史=最大范围）
• 调度器 0 → 730 天转换
• 「已同步天数」显示数据库实际总天数（totalDays），而非上次同步记录数

数据库

• MariaDB 数据库创建（garmin_health_lab）
• 完整表结构：health_data / daily_series / activities / activity_details / users / user_settings / garmin_tokens / sync_status 等
• 257 天健康数据已同步（2025-12-19 ~ 2026-09-01）

AI 教练（2026-09-01）

• 特征工程层 services/insights.py：z 分数（28 天个人基线）、13 个月趋势 斜率、近 7 天活动量对比，全部服务端算好再交给模型
• 提示词与解析层 services/coach.py：晨报 / 趋势归因 / Copilot 三套提示词， 每套都有对应的规则引擎兜底版本
• services/ai.py 扩展：多轮 chat()、SSE stream()、extract_json() （从推理模型的思维链里取最后一个 JSON）
• 接口：GET /analysis/briefing、GET /analysis/trend-insight、 POST /analysis/copilot（SSE）
• 缓存表 ai_insights（按 user + kind + subject，数据指纹失效）
• 前端：今日页 AI 晨报卡片（后台生成 + 轮询升级）、全局 Copilot 浮窗、 指标详情页 AI 归因面板；features.ts 的 ai 开关已打开
• 接入自建 ai-gateway（https://oracle.zichuan.xyz/ai/v1），实测走通
• 生产者/消费者队列（services/jobs.py）：优先级队列 + 多 worker 互斥锁
• 数据同步后自动预取所有页面洞察（prefetch_insights）
• 每日总结和运动详情在后台持续排队生成，不限量（refill_backlog + 空闲时自动补充）

实测数据（2026-09-01）：网关一次晨报生成 273 秒（上游 nvidia）， 缓存命中 18 毫秒。网关的流式通道比阻塞通道更不可靠——同一条提示词 流式 139 秒后返回「所有模型均不可用」，阻塞则成功，因此 stream_chat() 在流式无输出时会对同一模型退回非流式重试。

待办

功能完善

• 仪表板数据可视化组件完善
• 健康建议 / AI 解读功能（AI 教练，见下）
• 数据分析报告生成
• 多用户支持完善

运维

• 监控与告警
• 日志轮转与清理
• 数据库备份策略
• HTTPS 证书配置（Let's Encrypt）

文档

• ARCHITECTURE.md 需更新（当前仍为 Node.js 架构描述）
• DEVELOPMENT.md 需更新（当前仍为 Node.js 开发指南）
• REQUIREMENTS.md 需更新