用途与实际影响
这项功能怎样使用
为什么需要它
设备 API 需要长期凭据；如果每次刷新都重新授权、把 token 写盘，或让脚本在后台反复重试，既增加打扰，也扩大凭据与误操作风险。
举个实际例子
我明确说“现在更新一次Fitbit Air”。系统先处理已经取回但尚未整理的结果；确需联网时才由固定凭据入口开始更新。若只是本段请求预算用完、同一清单确有进展，就继续下一段；账号需重新绑定、权限或因子失败、无进展或请求超时则停止并说明，不换账号、不转后台重试。
最后我会得到什么
得到一次由本人明确发起的前台更新结果：取回了什么、哪些日期还缺、下一步能否离线核对。账号或权限出了问题就说明并停止，不换账号或在后台反复尝试；长期凭据仍留在受保护入口。
可用于当前判断
本次设备记录取回并核对完整后，再转入本机离线验真；一次请求返回不等于全部完成。
需要复核
若上一批已经成功取回但尚未整理，先在本机完成它，不重复访问账号。
本轮不可用
账号需重新绑定、回执异常或本次运行超时就停止，保留已有材料并说明接续条件。
从哪里开始
明确说“更新这次 Fitbit Air 记录”，由现有前台入口执行。
需要准备什么
- 本人明确的这次设备刷新请求
- 想看的日期范围（如不同于默认）
从开始到拿到结果
- 1
系统核对并处理
只在本次前台通过受保护凭据入口取回 Google Health 数据，凭据不落在普通文件或命令行。
- 2
交付与接续
交回本次导出、缺页和后续离线验真状态；连接或授权失败就停，不暗中设后台同步。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
OAuth（账号授权协议）、PKCE、Secret Broker（本机受保护凭据中介）存储/备份/回读、受限预算继续与进程终止均有源码和合成测试；当前账号未验证关键规则与设计选择
首次桌面 OAuth（账号授权协议） 使用回环 callback 和 PKCE。
只接受完整只读 scope 与可长期使用的 refresh credential。
client secret 和 refresh token（刷新令牌） 通过 stdin 送入 Secret Broker（本机受保护凭据中介）。
保存事务、恢复副本和 lookup read-back（正式回读） 全部闭合才称已存储。
每段执行都使用同一个固定Secret Broker（本机受保护凭据中介）；仅request_budget_exceeded、同一exact manifest（清单）和累计请求数进展共同成立才继续，rebind、因子或权限失败不重试换路。
本模块用到的名词
- OAuth（账号授权协议）
- 用户明确允许应用以只读 scope 访问设备数据的标准流程。
- PKCE（授权码防截获校验）
- 用一次性 verifier/challenge 绑定授权码交换，降低授权码被截获后复用的风险。
- Secret Broker（本机受保护凭据中介）
- 唯一允许 importer 使用长期凭据的受保护入口；网页不读取任何明文。
- Foreground refresh（前台刷新）
- 本人明确发起并在当前任务内完成，不由计划任务或 watcher 触发。
专业定义
更新在当前任务里完成；凭据留在受保护位置，不写进普通文件，也不建立定时同步或后台监测。
解决什么
解决 token 文件散落、凭据出现在 argv/stdout、后台同步扩权、重复授权和 Secret Broker（本机受保护凭据中介） 失败后盲重试。
当前怎样实现
- google_health_enroll.py 验证 desktop loopback client、provider endpoint、redirect 和只读 scope。
- OAuth（账号授权协议） 使用 state 与 S256 PKCE，回调只监听 127.0.0.1 随机端口。
- 凭据 bundle 只通过 stdin 交给 Secret Broker（本机受保护凭据中介），不进入 argv。
- Secret Broker（本机受保护凭据中介） receipt（执行回执） 必须证明 local transaction（事务）、recovery set、runtime（运行环境） identity 和 plaintext_returned=false。
- google_health_refresh.py以64KiB合并输出上限和项目自有watchdog约束每次固定Secret Broker（本机受保护凭据中介）调用；_budget_resume_checkpoint与_has_budget_resume_progress只允许有进展的同清单预算继续。
- 超时或中断用 taskkill /T /F 终止整棵登记目标进程树。
执行流程
- 1
首次明确授权时读取 desktop client JSON。
- 2
在本机回环完成 OAuth（账号授权协议） + PKCE 并交换长期凭据。
- 3
通过 stdin 存入受保护凭据中心并完成 backup/lookup 回读。
- 4
以后本人明确运行前台 refresh。
- 5
若没有待处理成功交接，调用固定Secret Broker（本机受保护凭据中介）；同一清单因预算停止且累计请求数增加时继续下一段。
- 6
最终合法pass回执后进入离线capture；除已证明进展的预算停止外，其他结果按具体错误停止。
边界
- 网页不运行 enrollment、Secret Broker（本机受保护凭据中介）、importer 或真实 provider。
- 任何 OAuth（账号授权协议） JSON、token、client secret、cookie 或 SecretRef 结果不得公开。
- 当前测试使用合成 runner 和模拟网络，不能证明当前账号仍连接。
- 刷新失败不切换浏览器、账号、provider 或备用凭据路线。
失败与恢复
- OAuth（账号授权协议） scope 不完整或 refresh token（刷新令牌） 有明确期限
- 拒绝登记，不把短期访问冒充为长期刷新能力。
- Secret Broker（本机受保护凭据中介） 返回 rebind_required
- 精确返回 runtime_rebind_required；本轮停止且不重试。
- Secret Broker（本机受保护凭据中介） 输出过大、stderr 非空或回执字段不闭合
- 按稳定无秘密错误码失败，不调用 capture。
- watchdog 超时或用户中断
- 终止整棵进程树，关闭 pipe，不留下后台子进程。
真实入口
google_health_enroll.py桌面 OAuth（账号授权协议）、PKCE、stdin secret、recovery 和 lookup 回读
google_health_refresh.py固定前台入口、同清单预算继续、输出与超时边界
tests/test_google_health_enroll.py授权、只读 scope、凭据传输和存储收敛回归
tests/test_google_health_refresh.py固定入口、预算继续例外、离线优先、rebind、输出、超时和进程树回归
如何验证
- 10 项 enrollment 测试覆盖 desktop client、PKCE、scope、stdin、backup 与 read-back（正式回读）
- 本轮140项全套中的refresh回归覆盖固定入口、同清单有进展的预算继续、离线优先、rebind、输出上限、超时与中断；不把重叠用例另外相加
- 本轮没有触发真实 OAuth（账号授权协议）、Secret Broker（本机受保护凭据中介） 或 provider，因此当前现场状态保持 Unknown（未验证）
与其他模块的关系
它是唯一凭据/网络前台入口；成功后把精确 manifest（清单） 交给原始保全和离线判断模块，自己不解释健康。