ericwyuan/GarminHealthLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
78 Commits 1 Branch 0 Tags
7e8e376a6c3676df46f2cda09b02cd0896c8e8ef
Commit Graph

44 Commits

Author SHA1 Message Date
ericwyuan
5e6fc01f76 feat(sync-history): 新增同步结果查询(每次自动/手动/立即同步的记录) 
后端：
- db.py SCHEMA 新增 sync_history 表(不可变,每次同步尝试一行) + 索引
- garmin.py: _log_sync_history() 在 sync_data 全部出口记录; trigger 区分
  auto(调度器)/manual(同步页开始同步)/quick(设置页立即同步); start_sync
  限流拦截分支同样留档; 写入失败只告警不影响同步
- scheduler.py 自动同步传 trigger="auto"; routes 新增 GET /garmin/sync-history
  按时间倒序返回(默认 50 条,上限 200)

前端：
- api.ts 增加 SyncHistoryItem 类型 + getSyncHistory()
- 新页面 /sync-history/ 同步记录: 卡片列表, 状态(成功/失败/被限流)chip 配色,
  时间本地化(今天/昨天/X月X日), 触发类型标签, 范围与耗时
- 同步页与设置页同步区块均加入口链接
 2026-09-02 20:42:26 +08:00
ericwyuan
224144915c fix(sync): 限流拦截不再把'上次同步'刷成现在 + 设置页新增立即同步按钮 
- _set_sync_status 支持保留旧 last_sync_time；两处限流拦截(start_sync /
  sync_data)改为传旧值——被拒的同步零请求发生，不能把 UI 的'上次同步'
  拨快成'刚刚'，掩盖数据早已停更的事实
- SettingsPage 同步区块新增'立即同步'行：走 /garmin/sync-latest(最近2天，
  秒级阻塞返回)，成功/限流/未绑定三种状态都有明确反馈；限流中后端零请求
  拦截并回传恢复倒计时文案
 2026-09-02 20:14:11 +08:00
ericwyuan
68363957ec fix(ui): Copilot 浮窗按钮被 F7 全局 width:100% 撑满，显式覆盖为 width:auto 
Framework7 自带 button { width: 100% } 且打包后排在 Copilot 规则之后，把
面板内 ✕ 与发送按钮拉满父容器，input 被挤成 21px、✕ 跑到面板中部。
在 .copilot-close / .copilot-compose button 上显式 width:auto + flex 固定，
重建并同步 backend/static 产物（main.00d05e81.css）。
 2026-09-02 19:34:24 +08:00
ericwyuan
05f55e695b feat(ai): 设置里加「AI 生成队列」，看得见后台在算什么 
队列本来是完全不可见的：页面上一句「排队生成中」说不出自己是下一个、第二十
个，还是已经放弃了——网关挂掉的时候，「还在生成」和「永远不会好」长得一模
一样。今天排查就是这么排的。

- GET /analysis/insight/queue 返回队列（running 在前，其次按优先级和年龄，
  和 worker 实际取任务的顺序一致）、已生成的解读、scope 名到中文标签的映射
  （前端不必再抄一份），以及消费者的限流配置
- POST /analysis/insight/queue/retry：手动把「已放弃」的重新排队，不等冷却。
  自动重试要等冷却是为了不去捶一个正在抽风的上游；人按下重试是他自己判断值得
  再试一次
- 页面在 设置 → AI 生成队列。插队的任务标「插队」——这是整个界面最想让人看见
  的一件事：为什么是它排在最前面
- 「已生成」单独列：队列空了意味着「没有待办」，不是「什么都没生成过」，
  没有这一节这两件事在界面上没法区分

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 16:02:05 +08:00
ericwyuan
6dd070ec9b fix(ai): subject 里塞了行数，每轮询一次就新建一个任务 
生产上 trends 队列里积了 36 个任务，subject 是 2026-09-01:1033、:1039、
:1044……一路涨。这台账号当时正在补历史，get_summary 的行数每隔几分钟就变，
而我把 len(rows) 写进了 subject——subject 同时是缓存键和任务队列的键，一变
就是一条全新的任务，轮询几次就刷出十几条。

subject 该回答的是「这条解读是关于什么的」，不是「当时有多少行数据」。
数据变化本来就由 fingerprint 负责。

- trends 的 subject 改成快照日期；sleep 用配置的窗口常量而不是实际夜数
  （缺一晚也不该换键）；challenges 用固定键
- 加了不变量测试：补一天历史数据后 subject 不许变；任何 subject 段都不许
  长得像行数

顺带加一层兜底 jobs.supersede()：单实例 scope 只该有一个在跑的 subject，
队列里同 kind 的其它 pending 任务是关于已经不存在的快照的，跑完也没人看。
per_item 的 daily / activity 不受影响——它们本来就一天一条、一次运动一条。
兜底不是机制，机制是 subject 稳定；它存在只是因为这次 subject 不稳定，而
36 条任务堆在那里之前没人发现。

顺带按要求把 AiPanel 改成默认精简：只显示标题、来源和一句话结论，点「展开
详细」才出要点/建议/依据，可再收起——和今日晨报卡片一致。这些面板压在本来
就很密的图表页上面，全部默认展开会把真正的数据一次性挤到屏幕外。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 15:33:49 +08:00
ericwyuan
241ae0d6a3 feat(ai): 每个数据页面都有 AI 解读，靠一条带优先级的生产者/消费者队列 
原来只有今日页有晨报、指标详情页有归因，其余页面一片空白。现在除设置外
的 10 个页面都有：健康、睡眠、运动、趋势、每日、身体成分、成绩预测、
身体年龄、挑战赛、运动详情。

不是给每个页面写一套，而是一个通用管线：
- services/scopes.py：一个页面一个 context builder，返回同一个信封。
  context["highlights"] 是已经算好的白话事实——模型负责解读它们，模型不
  可用时规则引擎原样渲染。两者引用同一批数字，所以降级读起来不像换了个 App。
  没数据的页面返回 None，宁可不出卡片，也不让模型对着空表格发挥。
- coach.scope_messages / parse_scope_insight：一套提示词吃所有页面，页面
  的差异全在 context 里，加页面 = 加一个 builder。
- 前端 <AiPanel scope="…">：一个组件渲染所有页面，轮询逻辑抽成
  lib/insight.ts 的 usePolledInsight，晨报卡也改用它。

## 队列

一次生成 40 秒到 4.5 分钟，所以什么都不能在请求里生成。页面只负责入队，
worker 负责消费（services/jobs.py）。

优先级才是用队列而不是后台线程的理由：同步完成后 prefetch 把所有页面按
背景优先级排进去，可能要跑半小时；而用户一打开某个页面，那个页面的任务
立刻提到队首、下一个就跑。你在看什么，队列就在算什么。

队列放在数据库而不是内存里，因为 gunicorn 有两个 worker：任务带 holder
声明后回读确认，和 scheduler.py 抢 tick 是同一套做法。id 由
user+kind+subject 推导，所以每几秒一次的轮询是幂等的入队，不会每几秒堆一
个任务。

## 网关中断时踩到的两个坑（当场修了）

写完正好赶上 oracle 那台机器不通，于是看到：
- 三次失败后任务被永久标 failed，网关恢复了也不会重试——一次瞬时中断就把
  那个页面的解读判了死刑，直到它的数据碰巧变化。加了冷却期，过期后重置
  尝试次数再排一次。
- 队列已经放弃了，页面还在 pending 转圈，要转满 8 分钟才停。meta.pending
  现在跟着队列状态走，并把失败原因带给卡片。

顺带把 BAND_SOURCES 从 routes/settings.py 下沉到 services/insights.py：
教练要拿它做参照，而 services 不该反向依赖 routes。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 15:17:17 +08:00
ericwyuan
570d1590eb fix(router): 深链接全被塞进「今日」，点底部标签页显示的是别人的内容 
打开 …/sleep/ 之后，底部点「今日」出来的是睡眠，点「健康」出来的健康从来
没去过地址栏说的地方。

原因：browserHistory 只开在主视图（今日）上，而 Framework7 在启动时也会用
它去消费地址栏——它只认识这一个视图。于是不管哪个标签页真正拥有那个路径，
睡眠都被压进了**今日**的栈，还顺手伪造了一份两条记录的 history。

- View 加 browserHistoryOnLoad={false}。注意不是 browserHistoryInitialMatch
  ——那个只决定两条记录里渲染哪一条，伪造的栈照样留着（读 router-class.js
  的 getInitialUrl 才看明白）。之后的导航追踪不受影响。
- routes.ts 加 tabForPath()：冷启动的 URL 归哪个标签页。只有深链接查这张表，
  应用内点击照旧——从今日卡片点进睡眠，仍然留在今日。
- App.tsx 的 useDeepLink 负责派发初始地址，并把目标页压在该标签页自己的根
  之上，这样返回箭头回到的是健康，而不是空栈。

派发要延后一帧再做、并在 unmount 时取消：StrictMode 会把 <View> 挂两次，
第一次挂载的 F7 视图会被销毁重建，在它上面导航的结果全丢——症状是一个睡眠
页孤零零留在 DOM 里，router 却坚称自己在健康。另外比较路径要先归一化斜杠，
每个页面都注册了带斜杠和不带斜杠两种写法，直接比会把趋势压在趋势上面。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 14:31:34 +08:00
ericwyuan
c57c930949 feat(ai): AI 教练 —— 晨间简报、运动处方、趋势归因与 Copilot 
数值全部在服务端算好再交给模型，模型只做解读。让模型从 CSV 里自己推
z 分数，它算错的次数足以让简报引用图表反驳它的数字。

- services/insights.py：z 分数（28 天个人基线，且**排除当天**——用一个
  值参与算出来的均值去衡量它自己，会把真实离群点摊平）、13 个月趋势斜率
  （按序数日期最小二乘，手表放充电器上一周不会压缩 x 轴）、近 7 天活动量
  对比。
- services/coach.py：三套提示词 + 回复解析，每套都配一个规则引擎版本。
  网关一次生成要几分钟，上游被限流时给一个朴素的答案，好过给一张空卡片。
- services/ai.py：多轮 chat()、SSE stream()、complete()/stream_chat()，
  以及 extract_json()——上游是推理模型，可见输出以思维链开头，所以从末尾
  倒着找最后一个配平的 JSON（字符串感知，扛得住引号里的 } 和转义引号）。
- 接口 briefing / trend-insight / copilot(SSE)，缓存表 ai_insights。
- 前端：今日页晨报卡（后台生成 + 轮询升级）、全局 Copilot 浮窗、指标详情
  页归因面板。features.ai 打开。

实测（对着自建 ai-gateway）：晨报一次 273 秒，缓存命中 18 毫秒——所以简报
绝不能同步阻塞首屏。网关的流式通道比阻塞通道更不可靠：同一条提示词流式
139 秒后返回「所有模型均不可用」，阻塞则成功，因此 stream_chat() 在流式零
输出时对同一模型退回非流式重试。Copilot 实测 TTFB 9ms、全程 40 秒。

顺带修两处：refresh 原来只跳过缓存读、不删行，导致「重新生成」后的轮询读
到旧行、看到 cached 就停了，用户一直盯着他刚要求替换掉的那段字；基线零方差
时原来返回 z=0.0，把「和每一条观测都不同」标成「完全正常」，改为 z=null。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 13:57:35 +08:00
ericwyuan
a746327560 fix(ui): 奖励卡片被 Framework7 的 .badge 压成灰色小药丸 
.badge 在三处定义：Screen.css 的奖励卡、Settings.css 的状态药丸、以及
Framework7 自带的消息计数小圆点。F7 的样式表在打包顺序里排最后，于是
它赢了——每张奖励卡都被强制成 display:inline-flex、固定 20px 高、灰底
白字的圆点，名字和日期硬塞在里面。Screen.css 精心写的卡片样式基本全被
覆盖。65 个奖励堆在一起，看着自然不成样子。

* 奖励卡改名 .award/.award-grid/.award-name/.award-meta/.award-count，
  彻底避开 F7 的全局类名。
* Settings.css 里的 .badge/.badge.ok/.badge.off 没有任何地方引用，是
  死规则，唯一作用就是参与撞车——删掉。
* 顺手让卡片等高、日期用等宽数字对齐、×N 做成右侧小标签。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 09:34:53 +08:00
ericwyuan
92ea33b800 feat(sync): 全部历史真的是全部，不再截断在两年 
730 天是个凭空写死的上限。账号有七年数据的人选「全部历史」，拿到的是
最近两年，而且没有任何提示说剩下的被丢掉了。

* 全部历史现在一直回溯到账号最早的数据：连续 EMPTY_RUN_STOP(120) 天
  完全没有内容就停，所以既不会截断，也不会去问手表存在之前的年份。
  MAX_HISTORY_DAYS(3650) 只是兜底，可用环境变量覆盖。
* 已经存过的日期跳过（最近 3 天除外，它们还在写入中）。这让多年的
  回填变成可续传的：撞上限流停下来，冷却过后再点一次就从断点继续，
  而不是每次都从今天重新爬。
* 选择器补上 3 年 / 5 年。
* 前端把每个范围的实际代价写出来，并说明中断可续。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 09:30:03 +08:00
ericwyuan
526ece7d14 refactor(sync): 手动同步与自动同步彻底分开 
「历史范围」原本放在设置页，却只对同步页的一个按钮起作用；而同步页最
显眼的主按钮「同步最新数据」写死 2 天，根本不看这个设置。选了「全部
历史」再点主按钮，表现就是应用无视你 —— 这正是反复出现的「只同步下来
两天」。

现在两条链路各管各的：

* 自动同步：只在设置页配置（开关 + 频率），窗口固定 SYNC_DAYS，不再
  读 history_days。措辞也改成「拉取最近几天」，不再暗示会补历史。
* 手动同步：范围就在同步页当场选，紧挨着用它的按钮，并标出每个范围的
  实际代价（自上次同步 / 7 天 / … / 全部历史约 730 天、20-40 分钟）。
  两个按钮合成一个「开始同步」，写死 2 天的那个删掉。

history_days 保留为「上次手动选的范围」，只有同步页读它；默认值改成
-1（自上次同步），对日常使用是正确的起点。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 09:20:52 +08:00
ericwyuan
41b7ae82e4 fix(sync): 「全部历史」真的拉全部历史，自动同步不再每次静默失败 
四个独立的 bug 叠在一起，表现为「只同步两天、没有进度」：

* 前端 `...(days ? { days } : {})` 把 days=0 当成未传。「全部历史」
  存的就是 0，请求体里根本没有 days，后端退回 7 天默认值。
* scheduler 用 `s[0]` 读 query_one 返回的 dict，抛 KeyError 后被
  per-account 的 except 吞掉。只要用户存过一次设置，每 30 分钟的
  自动同步就一次都没成功过——库里那 2 天全是手动点出来的。
* 增量同步查 `health_daily`（表其实叫 health_data），后台线程直接
  死掉，状态永远卡在 syncing，进度条不动。
* UI 完全不看 /sync 的返回值，rate_limited 时按钮点了没反应；轮询
  结束时又把 rate_limited 归进 else 分支报「同步完成」。

顺带：
* 日循环遇到 429 立即退避并保留已拉到的天数，而不是当成「跳过一天」
  继续往下捶 700 天——这正是之前限流死循环的来源之一。
* 定时循环显式传 SYNC_DAYS。历史范围按 UI 文案只描述手动全量同步，
  让半小时一次的 tick 重拉 730 天必然把限流撞得更深。
* 短同步逐天上报进度（原来每 5 天一次，7 天的同步全程停在 0）。
* /sync 路由重复解析 body，空 body 会 None.get 崩。
* 4 个 StubGarth 缺 configure()，7 个测试在此之前一直是红的。

新增 deploy/push.sh：NAS 只认密码，脚本开一个 ssh 复用连接，密码只
输一次，后面推送 / 重启 / 健康检查全走它。不碰 .env、.venv 和数据库。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-01 08:11:24 +08:00
ericwyuan
15fba8c25c feat: NAS 部署 + auth-hub 认证 + 同步逻辑修复 
部署:
- 后端 Python/Flask，数据层可插拔 SQLite/MariaDB
- NAS 部署路径 /volume1/web/garmin-health-lab，端口 8124
- Gunicorn 生产服务器 (2 workers / 4 threads)
- 开机自启脚本 deploy/S99garmin.sh
- frp 隧道甲骨文 8124 → NAS 8124，外网访问
- 前端构建产物纳入版本管理 (backend/static/)

认证:
- auth-hub OAuth2/OIDC 统一登录接入
- 新建 NAS 专用 client，注册内外网回调地址
- 前端 LoginPage 支持回调路由 /auth/callback
- 数据同步页增加 Garmin 邮箱输入框

同步逻辑修复:
- 自动同步调度器读取用户 history_days 设置，不再固定 2 天
- 前端 0（全部历史）不再被 || 吞掉，改为 ?? 处理
- 后端路由和 sync_data 中 0 不再被当成 falsy 回退默认值
- sync_data 和调度器中 0 → 730 天（全部历史=最大范围）
- 已同步天数显示数据库实际总天数 (totalDays)
- 历史范围新增「自上次同步」增量选项 (days=-1)
- 后端 settings.py HISTORY 添加 -1 值

项目文档:
- 创建 PROGRESS.md 跟踪项目进度
 2026-09-01 07:39:09 +08:00
ericwyuan
9503fca370 feat(auth): 接入 auth-hub 统一登录，网页登录与 Garmin 同步彻底分离 
网页身份改由 auth-hub 做 OAuth2 + PKCE 单点登录，本地邮箱/密码登录与注册整条链路删除
（routes/auth.py、auth.py 的密码哈希、config.py 的 ALLOW_REGISTRATION）。Garmin 账号绑定/
同步保持完全独立、可选：routes/garmin.py 不再直接查 users 表，Garmin 邮箱回退统一走新增
的 services/garmin.py::get_remembered_email()（优先读 garmin_tokens 当前绑定，兼容早期账号
落在 users.garmin_email 的历史值），彻底把「你是谁」和「你绑没绑 Garmin」两件事拆开。

- db.py: users 表新增 auth_hub_sub/auth_hub_username，MIGRATIONS 补上这两列（此前遗漏导致
  已存在的生产 MariaDB 表永远不会自动加列）；同时把历史遗留的 garmin_email/
  garmin_password_hash NOT NULL 约束在线迁移为可空，因为新账号不再在注册时收集这些字段。
- routes/auth.py: 修掉 /callback 路由重复拼接 /api/auth 前缀导致 404 的 bug。
- client: LoginPage 去掉本地登录/注册标签页，只保留 auth-hub 统一登录；登录成功/失败后都
  用 history.replaceState 清理地址栏，修掉 Framework7 browserHistory 读取
  /auth/callback?code=... 导致「找不到页面」的问题。
- 新增 test_auth_hub_client.py 锁定 find_or_create_user 按 auth_hub_sub 幂等——生产上曾经因为
  这个函数在没有该测试保护时被测试触发，误建过一个空账号，靠手工核对 health_data 计数才发现。
- 生产 auth-hub 侧另行为该项目注册了正式 client（未随本次提交变更，凭证只存在服务器 .env）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
 2026-08-31 23:12:17 +08:00
ericwyuan
bec45414a7 feat(garmin): 增加「退出 Garmin 账号」功能，删除已保存令牌以便重新登录 
backend: services/garmin.py 新增 delete_token()，删除 garmin_tokens 行并 forget_client 丢弃缓存会话；routes/garmin.py 新增 POST /api/garmin/disconnect（require_auth），返回 ok + 提示文案。
frontend: api.ts 增加 disconnectGarmin()；SyncPage 增加「退出 Garmin 账号」按钮（带二次确认弹窗）；DataSync.css 增加危险色样式。
设计：仅删除 OAuth 令牌，保留 users.garmin_email，下次重登只需密码；已同步的健康数据不受影响。
 2026-08-28 15:13:32 +08:00
ericwyuan
d2d6143ed6 fix(ui): 切换日期后数字不更新，卡片显示的是前一天的数据 
useCountUp 只靠 requestAnimationFrame 推进，没有兜底。帧不来的时候
（后台标签页、被节流的 webview）setDisplay 一次都不会调用，组件继续
渲染上一个值——往前翻一天，标题的日期变了，但每一个数字还停在前一天。
不是动画没播，是把另一天的数据当成这一天理直气壮地显示出来。

实测（造的数据）：08-24 → 08-23 → 08-22 三天，三张卡片全都显示 8,826，
而真实值是 8,826 / 10,232 / 10,715。

- 动画结束时间点加一个 setTimeout 兜底，保证最终值一定落地
- document.hidden 时直接跳过动画
- from 引用在收敛时同步更新，避免动画被打断后从错误的起点继续

动画是装饰，数字不是。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 09:33:22 +08:00
ericwyuan
564aaef6c1 fix(auth): 登录页不停刷新、无法输入 
未登录时五个 Tab 视图会同时挂载各自的 Screen，每个都判定「没登录」，
于是每个都对**当前**视图发一次 navigate('/login/', {reloadAll: true})。
每次 reloadAll 又让其他几个重新挂载，再各发一次——登录表单被持续拆掉重建，
根本打不出字。关掉页面过渡动画后这个循环变紧，症状才明显起来。

判断登录与否是外壳的职责，不是每个页面各自抢着跳转：
- App 持有会话状态：没有会话就只渲染一个 /login/ 视图，连 Tab 栏都不出；
  有会话才渲染五个 Tab。
- Screen 不再做任何跳转。
- setSession / clearSession 派发 ghl:auth 事件。storage 事件只在**其他**
  标签页触发，同标签页的登录登出需要自己的信号。
- 登录成功后不再手动 navigate：外壳会换掉整个视图，从一个正要被卸载的
  视图里发起路由是在和它抢。

实测：登出后登录页只有 1 个视图、无 Tab 栏，输入的内容 2.5 秒后仍在，
且输入框还是同一个 DOM 节点（没有重挂）；恢复会话后自动切回 5 个 Tab。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 09:08:02 +08:00
ericwyuan
6ad87115ab fix: 返回键失效的根因 + 同步页重做 + 连接池会永久阻塞线程 
返回键
- 根因是 Framework7 的页面过渡由动画事件驱动：push 时把 allowPageChange
  置 false，等动画报告结束再恢复。这个报告不来，路由就永久卡住，之后每次
  导航都被静默丢弃，back() 还会把上一页重建一份而不是弹出。
  实测对照：navigate({animate:false}) 前后状态完全正确，带动画则必卡。
  因此关掉页面过渡动画——导航同步完成，处处正确。动效改由内容承担
  （卡片入场、hero 揭示、顶部进度条），这个取舍里正确性优先。
- Screen 的返回改为显式 handler，先清掉残留过渡状态再 back()，
  不依赖路由自己的闸门。注意只清视图上的 router-transition 类：
  页面自身的 page-previous 是 F7 判断「回到哪一页」的依据，
  一并清掉会导致重建出一个重复的页面（中途踩过这个坑）。

同步页
- .btn 系列样式原本只定义在 pages/Pages.css，而那个文件只被一个没有路由的
  遗留页面引用，所以真实页面上按钮全都退化成 Framework7 的默认样式——
  就是你看到的三条链接。样式移进每个界面都会加载的 Screen.css。
- 主次分明：一个填充主按钮 + 两个带副标题的次按钮；补上「同步会取哪些数据」
  说明，页面不再是一大片空白。
- 进度条显示当前阶段（每日数据 2026-08-01 / 运动详情 12/174 / 身体成分…），
  原来只有「0 / 730 天」，几分钟里完全看不出在做什么。

后端
- MariaDB 连接池：_mariadb_release 用的是阻塞 put()，而队列 maxsize=10，
  _mariadb_acquire 在池空时又会新建连接。并发超过 10 之后，归还的线程会
  永久停在 put() 上，请求就此挂死。改为 put_nowait，多出来的连接直接关闭。
- 进程重启会带走同步线程却留下 status=syncing 的行，界面上是一个永远不动
  的进度条，还拒绝开始新同步。启动时清理。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 08:41:48 +08:00
ericwyuan
67a7c4b87e fix(ui): 自动同步开关不可点、返回键热区过小、路由卡死 
开关
- 我的 .toggle 类名和 Framework7 自带的 .toggle 组件撞了，元素被压成 0×0；
  另外 F7 全局给 input[type=checkbox] 加了 display:none，胜过我的 opacity:0，
  所以那个开关根本点不到。改名 set-switch 并显式恢复 input 的 display。
- 设置项改为乐观更新：先动控件，再发请求，失败回滚并报错。
  经隧道一个来回约半秒，开关在那半秒里纹丝不动会被当成坏了，
  用户再按一次，两个写入就打架了。

返回键
- 去掉导航栏毛玻璃背景时也把尺寸一起去掉了，链接缩成 44×16，
  手机上很难点中，按下也没有反馈。恢复 44px 高的热区并加按下态。

路由卡死
- F7 启动时给根节点加 framework7-initializing 来抑制动画，靠下一帧移除。
  这一帧在后台标签页或被节流的 webview 里不会到来，于是该类一直挂着，
  它的 transition-duration: 0ms !important 让过渡永远不发 transitionend，
  路由等的就是这个事件——allowPageChange 置 false 后再也没恢复，
  之后每一次导航（包括每一次返回）都被静默丢弃，只能刷新页面。
- 启动后主动清掉该类，并加一个看门狗：过渡类存活超过 1.6 秒即视为卡住，
  清理残留状态并放行路由。

进度条改用 portal 挂到 document.body。它原本是 F7 根节点的第一个子元素，
就这一个多余的节点会干扰 F7 的初始化。

部署脚本改为原子替换 static：原先 rm -rf 后再解包，中间有一段时间
文件是缺的，正好撞上就是 502。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 07:32:35 +08:00
ericwyuan
32588085a1 perf: 今日页首屏 394KB/2.0s → 51.5KB/0.82s 
逐个接口计时后的两处改动：

- 健康摘要不再下发空值。一天 40 项指标里大部分是这块表没有的传感器，
  全按 null 发出去占了约两成体积。客户端本来就把「键不存在」和 null
  当同一回事。
- 今日页首屏由 365 天改为 60 天，往前翻越界时再加载 180 天。
  一次取一年是为了让翻页不发请求，代价是首屏 394 KB，手机上不划算。
  日历选到窗口外的日期同样会自动加载。

顺带把加载逻辑收成一个 loadFrom：原来初始 effect 的依赖是空数组，
日历里改 from 不会触发重新拉取，是个还没被触发的 bug。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 04:34:32 +08:00
ericwyuan
f1319a6171 feat: 补齐 Garmin 未同步的数据，并各自配上界面 
审计 57 个接口后，把账号里真有数据却从未入库的部分补上。全部走同步模块，
界面只读本地库。

新增数据
- 体重与身体成分（体脂率/肌肉量/体水分/骨量/内脏脂肪/代谢年龄）
- 血压（接口通，账号暂无记录）
- 跑步成绩预测（5 公里 / 10 公里 / 半马 / 全马）
- 爬坡分、饮水量、出汗量 → health_data 新增七列
- 全天曲线：心率 / 压力 / 身体电量 / 呼吸 / 血氧
- 挑战赛（徽章挑战与好友挑战，与一次性的徽章不同，有周期和进度）
- 已配对设备

新增界面
- /body/ 身体成分：体重大数字 + BMI 分级 + 体脂肌肉曲线 + 血压表格
- /race/ 成绩预测：四个距离的预测成绩与配速，以及预测随时间的变化
- /challenges/ 挑战赛：按类型筛选，有目标的显示进度条
- /devices/ 已配对设备
- 每日页新增「全天曲线」，这是存日内采样的主要目的
- 健康页新增「身体成分」分组与「更多」入口，运动页加挑战赛与成绩预测入口

同步开销
- 日内曲线每天五个请求，14 天以内的同步顺带拉，更长的历史交给后台
  「补齐详细数据」，否则一年的同步会多出约 1800 个请求
- 原来的「补齐运动详情」扩展为统一的补齐任务，分阶段上报进度

日内采样抽稀到每天 240 点：手机图表分辨不出更多，只会把行撑大。

全量 446 项测试通过。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 04:16:33 +08:00
ericwyuan
34940cc387 feat(sync): 运动详情改为同步入库，详情页只读本地 
按需回源是错的：点一次运动要等七个 Garmin 接口，网络好的时候慢，
网络差的时候直接超时（实测公网下 Network Error）。

- sync_data 顺带补齐缺详情的运动
- POST /api/garmin/sync-details 后台补齐存量，GET 查进度
- 详情页只读本地库；没有就提示去同步，不再回源
- 同步页新增「补齐运动详情」按钮，带进度

身体年龄：加入公开的阻尼系数
- 34 岁 VO₂max 46 原本算出 21 岁。不是算错，是方法本身会饱和：
  人与人之间的 VO₂max 标准差约 7，而年龄每年只带来约 0.35 的衰减，
  于是稍微能练的人都会撞到参考表最年轻一档。
- 按 50% 向实际年龄收拢，收敛范围 ±20 → ±12 岁，同一算例现在给 27 岁。
- 去掉「高于最年轻一档按 20 岁计」的硬地板，那是一道正好落在用户身上的悬崖。
- 界面同时显示未收拢的原始值，阻尼系数写进评分依据。

路由：为每个路径补无斜杠别名
- F7 写地址栏时去掉尾斜杠，于是 /daily/ 在地址栏是 /daily，
  而那个地址匹配不到任何路由，刷新或分享就落到「找不到页面」。

布局：让页面结构上无法被撑宽
- 网格改用 minmax(min(210px,100%),1fr)：裸的 minmax(210px,1fr) 允许
  两列加起来超过窄屏宽度，第二张卡就被切掉在屏幕外。
- .ring-row 用 minmax(0,1fr)，1fr 会以 min-content 兜底，一句长说明就能
  把整行顶宽。
- .page-inner 加 overflow-x: clip。
- html/body 用 100dvh：手机浏览器把自己的地址栏盖在布局视口上，
  100% 高的应用会把底部 Tab 栏顶到它们下面——对用户来说就是没有 Tab 栏。

测试：新增 122 项（设置 44、身体年龄 44、运动详情 42），全量 446 项通过。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 04:03:49 +08:00
ericwyuan
fa865ca8a6 fix: 实机验证发现的七个缺陷 
部署与时区
- client/.env.production 写死 REACT_APP_API_URL=/api。之前没有这个文件，
  构建靠命令行临时传参，一旦忘了就把开发默认值 localhost:5000 打进包里，
  部署后整站 Network Error。
- 新增 lib/day.ts，所有日期改用本地日历日。原先用 toISOString() 取的是 UTC 日期，
  在 UTC+8 每天前 8 小时都会少查一天——当天的数据佳明已经有了，应用却够不到。

界面
- 覆盖 Framework7 9 给 .navbar .left/.right 加的 frosted pill，
  就是各页右上角和返回键旁边那个半透明椭圆。
- .metric-tab 显式 width:auto。F7 把每个 button 渲染成整宽块元素，
  运动详情的四个 Tab 因此竖着堆成四行。
- 主要收益为 UNKNOWN 时不显示该区块，那是「没有结论」的哨兵值。

正确性
- 心率区间百分比改用整次运动时长作分母。原先除以「落在区间内的总时长」，
  把低于区间 1 的时间挤掉了：44:06 的登山里区间 1 占 23:03，
  手表显示 52%，我算成了 90%。现在对上了。

性能
- 按进程缓存已认证的 Garmin 会话（15 分钟 TTL）。实测 _connect 单次 11 秒，
  而七个数据接口加起来才 4 秒——瓶颈全在每次重新认证。
  冷启 16s → 热 7s → 命中缓存 0.8s，不再撞客户端超时。
- get_activity_details 的 maxchart 由 2000 降到 500，反正写入时抽稀到 300。
- 重新绑定账号时丢弃缓存会话。

删除前端重做前遗留的 5 个无引用页面文件。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 01:16:44 +08:00
ericwyuan
8430ff335e feat(ui): 今日页日期切换 + 卡片可点 + 路由切换进度条 
需求 3.7 / 4.5 / 4.6 / 4.7

今日页
- 左右箭头切换日期，中间点开日历选任意一天，范围限定在已有数据内
- 没有记录的日期直接跳过，不会停在一个空白页上
- 一次读一年：往回翻一天不该产生一次请求，卡片的迷你曲线本来也需要前后几天
- 曲线窗口跟着所看的那天结束，卡片上的走势总是通向它上面那个数字
- 卡片改为从 lib/metrics.ts 渲染，点击进入指标详情

路由切换进度条
- 切换本身是瞬时的，用户等的是新页面的第一次请求，没有指示就像点了没反应
- 跑到 90% 停住等页面就位，不谎报完成
- 有最短显示时长，快速跳转时不会闪一下

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 00:49:38 +08:00
ericwyuan
0c7fecc124 feat(ui): 设置页重做 + 同步页简化 + 评分依据页 
需求 2.5 / 2.6 / 2.7 / 2.8 / 5.1 / 5.2 / 5.3

设置页
- 个人资料：身高/体重/出生日期/性别，另显示算出的 BMI 与年龄
- 单位：公制 / 英制
- 同步：自动同步开关、频率、历史范围
- 改动即存，不放「保存」按钮——每项都是单值且效果直观，
  而能保持脏状态的表单就是会悄悄丢编辑的表单
- 开关用原生 checkbox 只换绘制，键盘与读屏行为保持不变

/rating-basis/ 评分依据
- 11 项参考区间逐条列出边界与出处，包括「一般性参考，无权威标准」这种
  诚实的答案。判断从哪来必须能查到。

同步页
- 首要按钮「同步最新数据」，等几秒直接返回结果
- 次要按钮「同步历史」，按设置里的历史范围后台跑
- 状态压缩成三格：上次同步 / 自动同步 / 已同步天数
- 删掉原来四段说明文字，它们把两个动作埋在了下面

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 00:44:07 +08:00
ericwyuan
b0e0799a97 feat(ui): 卡片可点进详情 + 身体年龄 + 运动详情 + 指标选择弹窗 
需求 3.5 / 3.6 / 4.4 / 4.5 / 4.8 / 4.9

- 删掉导航栏右上角那两个 Link，就是它们渲染成半透明椭圆的。
  睡眠入口改为点健康页的睡眠卡片，每日入口移进趋势页内容里。
- 新增 lib/metrics.ts 作为唯一的指标注册表。label/unit/取值函数原本在
  今日、健康、趋势各写一份，改一处要改三处，也就有三次写不一致的机会。
- /metric/:id/ 指标详情：大数值 + 参考区间 + 7/30/90/365 趋势图 +
  平均最高最低达标天数 + 这个指标是什么 + 评分依据（取自后端，不在前端另写一份）
- /activity/:id/ 运动详情：概览/数据/分段/图表，数据分组照搬手表的排法，
  心率区间用单色顺序色阶（区间是有序刻度，不是分类，不能用分类色）
- /body-age/ 身体年龄：逐步展示 VO₂max 基准与各项修正，以及每步的出处
- 趋势页 15 个 chip 占满一屏且像张表单，改成弹窗选择，页面上只留一行摘要

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 00:39:33 +08:00
ericwyuan
85c00759f8 fix(ui): 三处实机问题 + hero 改为三圆环 
fix: 标题在窄栏里一行一个字
- Framework7 对裸 <button> 有全局样式，把「看数据」按钮拉成整行宽，
  标题/副标题容器被挤成 0 宽，文字只能竖排。给按钮显式 width:auto

fix: 标题旁边有个灰色方块
- 今日页没有右侧动作，但 NavRight 容器仍然渲染并带半透明白底。
  改为有内容才渲染

hero 改为三圆环（步数 / 睡眠 / HRV）:
- 每个环以「进入自己的参考区间」为满环，所以三个环的满度含义一致，
  尽管单位不可比
- 并列而非同心：Apple 的同心环成立是因为三环共享一个概念
  （动/练/站），而这三项是互不相关的度量，分开更好读

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-24 00:01:27 +08:00
ericwyuan
fd9b610810 [阶段10.1] Tab 改为 今日/健康/趋势/运动/设置 
按指定结构调整导航：每日归入趋势、睡眠归入健康、同步归入设置，
它们是各自 Tab 的详情视图而非独立目的地。新增「运动」Tab。

运动页（新）:
- 近 30 天运动时长/距离/消耗，以及今日强度分钟
- 项目分布：按累计时长排序，横条表示占比。只用一个色相 —— 每个项目
  一种颜色会让人以为分类另有含义
- 强度分钟趋势图，附 WHO 每周 150 分钟的参考
- 记录 / 个人纪录 / 奖励三个分页，运动记录 174 条

fix(nav): 五个 Tab 全部加载了同一个页面
- browserHistory 开在每个 View 上，导致它们都去读浏览器地址栏（当时是
  "/"）而不是各自的 url，五个 Tab 渲染出五份「今日」
- 浏览器历史只绑定主 View，其余 Tab 用自己的 url 独立加载

fix(nav): 导航栏右侧对所有页面塞同一组图标
- 睡眠/同步/设置三个图标出现在每个页面上，其中两个在多数页面无意义。
  改为按页面声明：趋势 → 每日，健康 → 睡眠，设置 → 同步

fix(viz): 图表标题在窄栏里竖排
- 标题与「看数据」按钮争抢宽度，短标题被压成竖排字符。
  标题允许收缩省略，按钮不收缩

fix: 未映射的运动类型直接暴露 snake_case
- 补充登山/划船/椭圆机等映射；仍未覆盖的转为空格分词并首字母大写，
  而不是把 Garmin 的原始 key 摆给用户看

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 23:52:18 +08:00
ericwyuan
7ab150537d [阶段10] 前端以 Framework7 重建，采用 iOS 原生形态 
按要求废弃手写外壳，改用 Framework7 React（theme=ios）。参照 PeakWatch
的信息架构与卡片语言。

保留（这些是资产，不该重来）:
- 数据层 services/api.ts、聚合 lib/aggregate.ts、参考区间 lib/ranges.ts
- 图表组件 Chart / Ring / Sparkline / BandBar / MetricCard / MetricStrip
- 经校验的配色令牌（色盲安全 + 对比度，浅深两档）

替换:
- 路由与外壳交给 F7：五个 Tab 各自独立导航栈，推入详情页不影响其他 Tab
- 页面转场、橡皮筋滚动、大标题折叠、半透明栏 —— 这些正是换框架的理由，
  手写做不像
- 底部标签栏改用 F7 Toolbar，触控目标与安全区由框架处理

配色接入:
- 新增 f7theme.css 把我们的令牌映射到 F7 的 CSS 变量，让它的导航栏/
  列表/面板与我们的图表同属一套设计，而不是两种视觉打架
- F7 的深色靠 .dark 类，我们的靠 data-theme，两者在 App 里同步切换

fix: 图标显示为原始名称（squ/hea/cale…）
- iconIos/iconMd 引用的是 framework7-icons 字体，没装就只会渲染出名字

其他:
- tsconfig moduleResolution 改为 bundler —— F7 用 exports 映射，
  node 解析方式找不到它的类型
- 登录页不套 Tab 外壳，未登录时不该出现导航

桌面与手机都要好看：内容在宽屏收进 1100px 居中列并加密卡片列数，
窄屏走底部标签栏；两档都已实机核对。

bundle 190KB -> 399KB，是换取原生手感的代价。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 23:38:21 +08:00
ericwyuan
757afdc941 [阶段9] 界面打磨：hero 圆环、sparkline、骨架屏、动效 
参考了 itsdrchen/Garmin-AI-Coach 与主流健康 App（Apple 活动圆环、
Oura/Whoop 的评分环、Garmin Connect 的卡内趋势）的做法。

hero 区（每个视图只有一个 hero 数字）:
- 步数目标圆环，超额时转为 status-good 色并保持满环 + 端点标记，
  而不是绕第二圈 —— 绕圈会让 101% 看起来比 100% 还少
- 圆环轨道用填充色同色系的浅阶而非中性灰，两者才读作同一个量器

sparkline（12 点，卡片内嵌）:
- 线用去强调色，只有最新一点用强调色，让它成为数字的背景而非对手
- null 处断开而不插值 —— 设备没记录的那天连一条平线过去等于编数据

骨架屏取代转圈:
- 形状与将要出现的内容一致，数据到位时布局不跳
- 用扫光而非闪烁，读起来像进度而不是元素在求关注

动效:
- 卡片/图表依次入场（45ms 递增），引导视线扫过而不是整屏同时砸下来
- 数字滚动到位、圆环扫过、sparkline 描线、悬停抬升、按下微缩
- 全部尊重 prefers-reduced-motion：直接跳过而非缩短时长 ——
  引起不适的是位移本身，不是它持续多久

深色改为冷调（借鉴参考项目）:
- 表面从暖近黑 #1a1a19 改为冷近黑 #181b21，更像运动 App
- 换表面意味着原有校验作废，已用校验器对新表面重跑：四个系列色
  全部通过含 3:1 对比度；文字亦逐个复核（正文 14.56:1、
  次要 7.98、弱化 4.38、按钮白字 6.63）

fix(a11y): 大号独立数字不应使用 tabular-nums
- 等宽数字让每个字形都占 0 的宽度，大字号下显得松散；
  等宽只保留给需要纵向对齐的表格列与坐标轴刻度

fix: 数字滚动动画吞掉了小数位
- StatTile 内部按 decimals 格式化，而调用方已经先 round 过一次，
  距离显示成 "9 km"、久坐成 "11 小时"。改为传原值 + decimals

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 22:48:09 +08:00
ericwyuan
bfda1cd017 [阶段8] 新增每日数据模块；趋势改为全指标并列 + 周期聚合 
每日数据（新页面 /daily）:
- 按活动/能量/心率/压力/睡眠/血氧呼吸/训练七组，列出全部 40 项指标
- 日期选择器 + 前后一天翻页；"只显示有数据的指标"开关
- 附当天的运动记录明细
- 标题处显示当天记录到多少项，缺数据一目了然

趋势（重写）:
- 15 组指标全部并列展示，不再一次只能看一个
- 标签可逐个隐藏/显示，选择存入 localStorage（每次刷新都重置的
  选择算不上偏好）；提供全选/全不选
- 两级筛选：范围（一月/一季/半年/一年/两年）× 周期（每天/每 7 天/
  每月/每季度）。周期选项按范围过滤，避免出现"近一月按季度聚合"
- 所有图表共用同一份聚合结果，一行筛选器统摄全部图表

聚合口径（lib/aggregate.ts）:
- 无论累计型还是速率型指标，一律折算为"周期内日均"，这样 30 天的
  月份和 31 天的月份不会仅因日历差 3%
- 周按最新一天往回切，而不是按自然周一 —— 否则开头会出现一个半空
  的桶，看起来像低谷，其实只是窗口起点
- 累计型指标的统计标签写作"日均"而非"平均"，读者不必猜口径

fix(viz): 聚合后柱形/面积图掩盖了变化
- 柱形与面积都以延展量编码大小，必须从 0 起；而一年的月均步数都在
  9,590~12,701 之间，画出来几乎一样高，恰恰看不见要看的变化
- 聚合视图改用折线：折线编码位置而非延展量，非零轴是正当的。
  改后 y 轴自动落在 9350~12750，走势清晰可读

fix(health): 运动记录按日期筛选时 500
- get_activities 复用了按 date 列过滤的子句，但 activities 表只有
  start_time，报 "Unknown column 'date'"。此前唯一的调用方不传
  日期，所以一直没暴露，每日数据页一传就炸
- 上界改用次日零点的开区间：SQLite 按字符串比较，而存储的分隔符
  可能是 'T'(0x54) 也可能是空格(0x20)，写成 "end 23:59:59" 会让
  当天 18:30 的记录排在上界之后而被排除在自己那天之外

tests (+6, 共 305): 运动记录的单日范围、上下界闭合、仅起点/仅终点、
不传范围返回全部、端点级验证

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 22:33:59 +08:00
ericwyuan
9e5e77755e [阶段7.2] 隐藏 AI 模块；剩余页面迁移到设计令牌 
AI 模块暂时下线（待重新设计），加 FEATURES 开关集中控制：
- 导航不显示"建议"，路由也不注册 —— 只隐藏入口而保留可访问的
  URL 等于没隐藏
- 设置页的模型清单区块一并隐藏，且不再请求 /analysis/models
- 页面与后端端点都保留，重新打开是一行改动

登录/同步/建议/设置四个页面此前仍在用旧样式（共 101 处硬编码颜色），
深色模式下全部失效。已改写为设计令牌。

fix(a11y): 主按钮白字对比度不足
- 白字在 --accent 上实测 4.42:1（浅）/ 3.64:1（深），均低于正文
  所需的 4.5:1
- 新增 --accent-solid 专用于填充面（按钮、选中标签），取同一蓝色阶
  更深的一步：5.39:1 / 6.63:1；--accent 继续用于文字、边框和标记

fix(viz): 一年档柱形图不可读
- 365 根柱子在 607px 宽度下每根仅 1.66px，既看不清也远低于
  ~24px 的悬停命中下限
- 超过 90 个点时柱形自动改为面积图，并在副标题里说明原因。
  折线/面积的十字准星吸附最近点，本就不依赖逐标记命中区

其他:
- 统计数值精度按量级取（11,013.99 既是虚假精度，又长到把单位挤到
  第二行）
- 设置页隐私说明更正：改用 OAuth 令牌后同步已不需要每次输密码

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 22:05:28 +08:00
ericwyuan
a17d6dde9b 睡眠页默认窗口改为 14 天 
30 根堆叠柱在常规宽度下每根约 10px，扣掉段间 2px 间隙后深睡那层
细到难以辨认，悬停命中区也逼近 24px 下限。默认收到 14 天让柱宽
翻倍，更长的窗口仍可手动选择。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 21:36:28 +08:00
ericwyuan
6a5cfa7806 [阶段7.1] 同步改为后台任务 + 进度上报，支持回补历史 
趋势页提供了"一年"档，但库里只有 7 天数据，那一档形同虚设。
实测每天约 2.84 秒（一天要打 5 个端点），回补一年需要约 28 分钟，
远超任何 HTTP 超时能等的时间。

- sync_status 新增 progress_current / progress_total / started_at
- start_sync() 起后台线程并立即返回，sync_data 每 5 天写一次进度
  （写库便宜但不免费，而前端本来就是 2 秒一轮询）
- POST /api/garmin/sync 改为 202 立即返回，接受 days 参数并
  夹在 1..730；进度经 GET /status 轮询
- 一次新同步会清掉上一次的错误，避免旧错误一直挂在界面上

前端:
- 同步页给出 7 / 30 / 90 / 365 天四个选项，日常与首次回补分开
- 进度条显示"第 N / 共 M 天"与预计耗时，并说明可以离开本页
- 页面挂载时若发现正在同步会接着轮询 —— 回补比页面存活时间长，
  刷新后必须能接上进度

tests (+7, 共 299):
- start_sync 在工作完成前就返回，且返回前已把 total 写好
- 进度随同步推进，结束时等于总天数
- days 超范围被夹到 730
- 新同步清除上一次的错误

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 21:31:50 +08:00
ericwyuan
ad88ec7e41 [阶段7] 前端重做：31 项指标全部露出，配色经色盲校验 
原来仪表板只有 4 张卡片和 4 张图，31 项指标里绝大多数没有出口。

信息架构重组为 7 个页面（原 5 个）:
- 今日   按活动 / 心率压力 / 睡眠呼吸三组展示 16 项指标
- 趋势   15 组指标可切换，5 档时间窗口（最长一年）
- 睡眠   新增。分期堆叠图 + 夜间血氧/呼吸/压力
- 成就   新增。奖励徽章按年份分组、个人纪录、运动记录
- 建议 / 同步 / 设置 保持

配色（依据 dataviz 规范，用校验器实测而非目测）:
- 采用验证过的分类色板并按既定 slot 顺序取色 —— 顺序本身就是
  色盲安全机制，不是审美选择，因此只取不循环
- 浅色 worst adjacent CVD ΔE 9.1 / 常视觉 22.9
  深色 worst adjacent CVD ΔE 8.4 / 常视觉 19.8，两档全部通过
- 浅色表面下 aqua 2.74:1、yellow 2.11:1 低于 3:1，按规范提供
  "relief"：每张图都带表格视图，且图例始终与文字标签同现
- 深色不是自动反色，是同色相针对深色表面重新取阶并单独校验
- 状态色（good/warning/serious/critical）保留专用，绝不当作
  第 N 个系列色；且始终图标 + 文字同现，不靠颜色单独表意

图表规范:
- 单一 y 轴，绝不双轴；量纲不同的指标拆成不同图
- 2px 线宽、4px 圆角柱端锚定基线、堆叠段间 2px 表面色间隙、
  悬停标记 2px 表面色描边
- 两系列以上必有图例，单系列不加（标题已经点明）
- 折线 connectNulls，设备漏记的日子不把线打断
- 数值文字一律用文字色令牌，不染系列色

其他:
- 主题切换（自动/浅色/深色），选择写入 localStorage 并标在 <html>
- 导航改为顶部横向，移动端可横滑
- 表格、徽章、空状态等组件统一到设计令牌

验证方式: DOM 审计确认 2px 线宽、圆角为 A 4,4 弧、堆叠段
2px 间隙、图例数量与系列数匹配、两档主题令牌各自解析到校验过的色值。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 21:17:08 +08:00
ericwyuan
cbbff61082 [阶段6] 同步 Garmin 全量数据：31 项日指标 + 奖励 + 个人纪录 
原来每天只存 7 个指标，而 get_user_summary 一次就返回 60+ 字段，
另有睡眠分期、训练准备度、耐力分等独立端点从未被调用。

db.py:
- health_data 新增 31 列（距离/活动卡路里/基础代谢/爬楼/强度分钟/
  久坐时长/最高最低心率/最大压力/身体电量四项/血氧/呼吸/
  睡眠深浅REM清醒分期/睡眠血氧/睡眠呼吸/睡眠压力/训练准备度/
  VO2max/耐力分）
- 新增 badges 与 personal_records 两张表，均以 (user_id, garmin_id)
  为主键，重复同步更新而非累积
- 新增增量迁移: CREATE TABLE IF NOT EXISTS 对已存在的表不生效，
  新列必须显式 ALTER，否则生产库上永远不会出现。按列名比对后
  逐个补齐，SQLite 与 MariaDB 都幂等

services/garmin.py:
- _extract_daily 改为汇总 user_summary + sleep + hrv +
  training_readiness + training_status + endurance_score 五个端点
- 每个可选端点用 _safe 包裹：某项设备不记录时留 NULL，不影响当天其余数据
- 新增 sync_badges / sync_personal_records（账号级，每次同步取一次）

fix(garmin): 个人纪录整批写入失败
- Garmin 在同一份数据里混用 ISO 字符串和 Unix 毫秒时间戳，
  prStartTimeGmt 是 1570961412000，写进 DATETIME 列被 MariaDB
  以 1292 拒绝，导致 11 项个人纪录一条都没存进去
- 新增 _to_datetime 统一处理 ISO / 毫秒 / 秒三种形状，并优先取
  Garmin 自己提供的 *Formatted 字段

services/ai.py:
- 送给模型的 CSV 从 7 列扩到 23 列，纳入身体电量、血氧、呼吸、
  训练准备度、耐力分和睡眠分期

接口: GET /api/health/badges、/api/health/personal-records

tests (+13, 共 292):
- 徽章/纪录的往返、重复同步不累积、按用户隔离
- 两个用户可持有同一个 Garmin 徽章 id 而不冲突
- 时间戳三种形状的归一化及无效值不抛异常

NAS 实测: 7 天数据每天 31 项指标、65 个奖励、11 项个人纪录

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 20:48:49 +08:00
ericwyuan
bb774c332b [阶段5.2] 两步验证改到网页端完成，手机上即可绑定 Garmin 
背景：命令行方案要求用户在电脑前开交互式终端，实际不可行。
改为在网页里完成 MFA，手机也能操作。

难点：garth 索取验证码走的是 *阻塞回调*，0.4.46 没有
"发起登录 -> 返回句柄 -> 稍后续接" 的接口，登录必须一直挂着。
而 gunicorn 跑多个 worker，验证码请求不一定落到挂着登录的那个 worker。

方案：登录跑在后台线程里，停在 prompt_mfa 内轮询数据库；
浏览器用另一个请求把验证码写进同一行。**汇合点是数据库而非进程内存**，
所以哪个 worker 收到验证码都能送达。

- 新增 garmin_mfa_sessions 表（不存密码，密码只活在等待线程的内存里）
- services/garmin_auth.py：start_login / submit_code / cancel
  状态机 starting -> awaiting_code -> finishing -> done|failed
- 超时 5 分钟自动放弃，会话 1 小时后清理
- 会话按 user_id 校验，他人拿到 session id 也读不到、提交不了

接口:
- POST   /api/garmin/login        发起登录，202 返回 session
- GET    /api/garmin/login-status 轮询状态
- POST   /api/garmin/mfa          提交验证码
- DELETE /api/garmin/login        取消

前端 DataSync 改为三步：
- 未绑定 -> 输密码「绑定 Garmin 账号」
- 需要验证码 -> 弹出 6 位验证码输入框（inputMode=numeric、
  autoComplete=one-time-code，手机可直接从短信自动填充）
- 已绑定 -> 只剩「立即同步」，不再要密码

tests/test_garmin_mfa.py (20 通过):
- stub 的 prompt_mfa 按 garth 的真实方式同步阻塞调用
- 关键用例：验证码直接写进数据库行也能被挂起的线程取到
  （模拟验证码落到另一个 worker）
- 无 MFA 的账号不经验证码直接完成
- 验证码错误 / 密码错误 / 等待超时 各自失败并给出原因
- 取消后挂起线程立即释放，不空转到超时
- 密码不出现在会话行里
- 跨用户读取和提交均被拒

全量: 271 passed

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 20:11:45 +08:00
ericwyuan
af0604bce4 fix(garmin): 两步验证账号同步报 EOFError，改用令牌登录 
现象：网页触发同步报 "EOF when reading a line"。

原因：garth 的默认 MFA 提示是 input()，向 stdin 索取验证码。
gunicorn worker 没有 stdin，于是抛出 EOFError——错误信息本身
完全没提到 MFA，看不出该做什么。

方案：把"输验证码"和"日常同步"拆开。
- 新增 garmin_tokens 表存 garth 令牌（Client.dumps/loads 序列化）
- garmin_login.py：在终端里跑一次，可正常输入验证码，
  成功后令牌存库
- _connect() 优先加载令牌并 refresh_oauth2()，命中则完全跳过登录，
  既不需要密码也不需要验证码（令牌有效期约一年）
- 无令牌且密码登录撞上 MFA 时，抛 MFARequired 并给出具体该执行
  哪条命令，而不是把 EOFError 原样抛给用户

接口:
- GET /api/garmin/auth-status 返回是否已有令牌
- /api/garmin/sync 在已有令牌时不再强制要求密码

前端:
- 有令牌时隐藏密码输入框，提示无需密码
- 同步返回 mfaRequired 时，展示需要在 NAS 上执行的具体命令
- 同步请求超时放宽到 180s（一周的天数 + 运动是多次上游调用）
- 成功消息补上运动记录条数

tests (test_garmin_sync.py 新增 12 条，共 35):
- 令牌存取、覆盖不累积、按用户隔离
- 有令牌时绝不调用 login()
- MFA 的 EOFError 转成带操作指引的 MFARequired
- 普通 401 不会被误标成 mfaRequired
- 无令牌且无密码时给出明确拒绝

NAS 真机: 252 passed

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 19:57:40 +08:00
ericwyuan
5f07dad019 [阶段5] 部署到 NAS + frp 公网映射，并加注册锁 
部署 (NAS 192.168.50.64):
- MariaDB 建库 garmin_health_lab，5 张表由 init_db 建好
- Python 3.8.15 venv；NAS 无 gcc，依赖全部走纯 Python 轮子
- gunicorn 2 worker × 4 线程，--timeout 300（AI 生成耗时可达数分钟）
- start.sh / stop.sh，可重复执行；日志落 logs/
- 在 NAS 真机 + 真实 MariaDB 上跑通全部测试：205 passed

app.py / config.py:
- STATIC_DIR 存在时由同一个 Flask 进程托管 React 构建产物，
  部署即单端口单进程，不需要额外反代
- 404 处理区分 /api 前缀：API 仍返回 JSON，其余回退到 index.html，
  这样 /settings 这类前端路由刷新后不会 404

安全 - 注册锁 (ALLOW_REGISTRATION):
- 服务要挂到公网，而原本 /register 完全开放，任何人都能注册进来
  读取健康数据
- 默认策略 auto：仅在尚无任何账号时开放，注册完第一个即自动关闭
- 另支持 true / false 显式覆盖；按请求读取，改配置无需重启
- 新增 GET /auth/registration-status，前端据此隐藏注册标签页

frp 公网映射:
- 复用 NAS 上已有的 frpc (/etc/frp/frpc.toml)，追加 garmin 隧道
  NAS:8123 -> 甲骨文:8123（改前已按既有惯例备份 .bak.<时间戳>）
- 经 S99frpc.sh restart 生效，原有 4 条隧道均正常恢复

tests/test_registration_policy.py (13 通过):
- auto 策略下第一个账号放行、第二个 403 且不落库
- true/false 显式覆盖，大小写不敏感
- 策略按请求读取而非 import 时冻结
- 关闭注册不影响登录；status 端点无需鉴权

公网实测: 页面、SPA 路由、鉴权 401、注册锁 403 均符合预期。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 18:49:05 +08:00
ericwyuan
acc6a2474b [阶段4.4] AI 建议结果缓存 - 页面不再阻塞等待 160 秒 
网关首选的推理模型一次生成约 160 秒，每次打开建议页都重跑不可用。
结果落库缓存，页面读缓存，用户想要新的再手动触发。

db.py:
- 新增 ai_recommendations 表，每用户一行（重新生成是替换不是累积）
- fingerprint 列记录这条建议是基于哪份数据算出来的

services/analysis.py:
- _fingerprint() 对全部每日指标 + 运动条数取 sha256，任何一次同步
  新增或修正了数值都会让摘要变化，从而使缓存失效
- TTL 默认 24 小时（AI_CACHE_TTL_HOURS 可调）
- 指定 model 参数时绕过缓存：点名某个模型意味着想要那个模型的答案
- 降级到规则引擎的结果不写缓存，避免把兜底答案当成 AI 结果存下来
- 缓存写入失败只打日志，不影响本次请求返回

routes: ?refresh=1 强制重新生成

前端:
- "重新生成" 按钮走 refresh，并提示需要 1-3 分钟、可以离开本页
- meta 栏显示是否为缓存结果及生成时间，以及网关的上游厂商
- axios 该请求超时放宽到 240s（冷生成远超默认超时）

tests/test_ai_cache.py (20 通过):
- 第二次调用不再打模型
- 新增一天数据 / 修正某天数值 / 新增一条运动记录，三种情况都失效
- TTL 边界两侧各一条（刚过期重算、未过期沿用）
- 缓存按用户隔离，A 的结果不会答给 B
- payload 损坏时重新生成而不是抛异常
- 规则兜底结果和无数据用户都不落缓存

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 17:55:12 +08:00
ericwyuan
8616a13525 [阶段4.2] 前端对接 Flask API + 建议/分析/设置页面，移除废弃的 Node 后端 
选型确认为 Python Flask 后，删除 server/ 整套 Node 实现，
根 package.json 改为只管理 client workspace，
npm run dev 同时拉起 Flask 与 React。

fix: 前端读取响应的方式与后端不符
- Flask 返回裸数组/对象，而前端读的是 response.data.data
  （Node 那套 {success,data} 包装），登录后拿到 undefined 直接崩
- api.ts 重写为返回 response.data，并补齐全部端点的 TypeScript 类型
- 401 拦截器改为清除会话并跳转 /login，而不是留在空白页

fix: 同步页缺少 Garmin 密码输入
- 后端只存密码哈希、无法还原，/garmin/sync 要求请求体带明文密码，
  原页面没有该输入框，点同步必然 400
- DataSync 增加密码字段，请求结束后立即清空，并说明为何每次都要输入

新增页面:
- Recommendations: 模型下拉切换（未配置密钥的模型置灰），
  展示本次由哪个模型作答、是否发生了降级、分析了多少天数据；
  按优先级配色，底部附免责声明
- Analysis: 6 个指标 × 4 个时间窗口，展示均值/中位数/极值/
  前后半段差值，并绘制趋势图
- Settings: 模型清单与配置状态、数据隐私说明、退出登录

Dashboard:
- 修正响应结构，数据扁平化后再传给图表
  （原先给 dataKey 传了函数，与 Chart 的 string 类型不符）
- 无数据时引导用户去同步，而不是显示一堆空图表

Chart:
- 按指标而非按行判断是否为空，某天缺某项指标不再让整张图判空
- 折线图 connectNulls，避免设备漏记的日子把线断成碎片

验证: 前端 tsc --noEmit 通过；后端 161 passed / 1 skipped；
实机启动 Flask 后 register/login/models/ai-recommendations 均正常，
未配置密钥时正确降级到规则引擎。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 12:43:52 +08:00
ericwyuan
0177758e1f [阶段2.3-2.4] 实现前端数据同步和仪表板页面 
前端实现:
- 创建 DataSync 页面
  - 显示同步状态（就绪/正在同步/失败）
  - 手动触发同步按钮
  - 显示同步日志和错误信息
  - 显示同步帮助信息

- 创建 Dashboard 页面
  - 今日概览（步数、心率、睡眠、卡路里）
  - 30 日统计（平均值、总计）
  - 交互式图表展示（步数、心率、睡眠、卡路里）

- 创建 Chart 组件
  - 支持折线图和柱状图
  - 使用 Recharts 库
  - 响应式布局

前端样式:
- DataSync.css
- Dashboard.css
- 完整的响应式设计

验收标准已满足:
- 数据同步页面功能完整
- 仪表板显示健康数据
- 图表正确展示数据趋势
- 移动端响应式

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 12:27:43 +08:00
ericwyuan
3b2d0697f0 [阶段1.1-1.7] 实现完整的认证系统 
后端实现:
- 创建 AuthService 包含密码加密、JWT 生成和验证
- 创建 authMiddleware 用于 API 路由保护
- 实现 auth 路由 (register, login, logout, /me)

前端实现:
- 创建 Login 页面 (登录/注册标签页)
- 创建 ProtectedRoute 组件用于路由保护
- 更新 App.tsx 集成路由保护
- 前端 API 客户端已包含认证方法和拦截器

验收标准已满足:
- 用户可以注册和登录
- JWT Token 正确生成和验证
- 受保护的路由需要有效 Token
- 未认证用户重定向到登录页面

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 12:25:33 +08:00
ericwyuan
d73405decb Initial commit: Set up Garmin Health Lab project structure 
- Initialize monorepo with root workspace configuration
- Set up Express.js backend with TypeScript
- Set up React 18 frontend with TypeScript
- Create database schema with SQLite
- Implement project architecture and documentation
- Add development and deployment guidelines

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-08-23 11:11:29 +08:00