2d9a2be185
背景：文档停在 Node.js 时代或甲骨文 8123 部署，与生产（NAS :8124 + Flask + auth-hub + ai-gateway）严重脱节，曾导致凭旧记忆误判'无线上环境'。 - CLAUDE.md 重写：技术栈/结构/命令/部署事实/关键坑（F7 button、UTC 日期、 429 退避以 DB 为准、迁移幂等、AI 生成耗时） - docs/ARCHITECTURE.md 重写为 Flask 蓝图+services+可插拔数据层 + NAS 部署 - docs/DEVELOPMENT.md 重写为 Flask/CRA 开发指南 + push.sh 部署流程 - docs/REQUIREMENTS.md：部署条目改 NAS 8124；补 auth-hub/AI 教练/新修复 - docs/AUTH_HUB_INTEGRATION.md 新增（补 .env.example 悬空引用） - README.md：技术栈/DB/auth-hub/API 清单/部署节修正 - backend/config.py 与 .env.example：AUTH_HUB_REDIRECT_URI 默认 8123→8124， MariaDB 注释 Oracle→NAS - tests：GatewayCourtesy 并发测试对齐 MAX_CONCURRENT(AI_JOB_CONCURRENCY=2)； conftest 禁用 create_app 后台队列线程，修整库测试 flaky（585 passed）
5.7 KiB
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/garmin_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()、SSEstream()、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://ai.zichuan.xyz/v1），实测走通 -
生产者/消费者队列（
services/jobs.py）：优先级队列 + 多 worker 互斥锁 -
数据同步后自动预取所有页面洞察（
prefetch_insights） -
每日总结和运动详情在后台持续排队生成，不限量（
refill_backlog+ 空闲时自动补充）
实测数据（2026-09-01）：网关一次晨报生成 273 秒（上游 nvidia）， 缓存命中 18 毫秒。网关的流式通道比阻塞通道更不可靠——同一条提示词 流式 139 秒后返回「所有模型均不可用」，阻塞则成功，因此
stream_chat()在流式无输出时会对同一模型退回非流式重试。
Copilot 浮窗 UI 修复与文档同步（2026-09-02）
-
Copilot 浮窗 UI 修复：Framework7 全局
button { width: 100% }把面板内 ✕ / 发送按钮拉满父容器，挤坏 flex 布局（输入框缩到 21px、✕ 跑到面板中间）。Copilot.css显式width: auto覆盖，重构产物已部署到 NAS :8124 验证。 -
文档与代码对齐生产现状：CLAUDE.md / README.md / docs/* 全部更新为 Python/Flask + NAS :8124 + auth-hub + ai-gateway（清除 Node.js 时代与 甲骨文 8123 的过时描述）；
config.py/.env.example默认值同步。
待办
功能完善
-
仪表板数据可视化组件完善
-
健康建议 / AI 解读功能（AI 教练，见下）
-
数据分析报告生成
-
多用户支持完善
运维
-
deploy.sh自动复制前端构建到backend/static/，避免部署旧版 -
监控与告警
-
日志轮转与清理
-
数据库备份策略
-
HTTPS 证书配置（Let's Encrypt）
文档
-
ARCHITECTURE.md 已重写为 Python/Flask 架构 + NAS :8124 部署（2026-09-02）
-
DEVELOPMENT.md 已重写为 Flask/CRA 开发指南（2026-09-02）
-
REQUIREMENTS.md 已更新部署位置与新增需求（2026-09-02）
-
CLAUDE.md / README.md 同步为最新技术栈与部署现状（2026-09-02）