wx_pbzc/.workbuddy/memory/MEMORY.md

项目长期记忆（wx_pbzc 平板支撑训练小程序）

关键技术陷阱（最高优先级，改样式/加组件前必读）

• 组件 style isolation = isolated：页面 wxss 改不了组件内部类；唯一能跨边界的是 CSS 变量（沿 DOM 继承进 slot）。渐变/主色容器内反白文字必须用 var(--text)，绝不用 var(--primary)（橙字画橙底=隐形）。进度条填充用 var(--on-primary,...) 让容器可覆盖为白。
• 图标色烤死在 SVG data URI（utils/icons.js：*Fill=主题色、*(无Fill)=灰 #999），CSS 改不了 <image>。主色/渐变底（hero 卡、primary 按钮）须用 *White 变体（如 playWhite），浅底用 *Fill。随状态换色的小装饰用纯 CSS 画（如 .circuit-phase-dot），别用 icon。
• 图标图形在 viewBox 内未必垂直居中：外部库（Phosphor 等）的 path 直接塞进 24 viewBox，图形重心可能偏上/偏下 ±1rpx（medalMilitary 偏下 1.13、crownPh 偏上 1.13），导致「同排 icon 与文字对齐」各图标错位不一，CSS 微调永远修不齐。治本：用 svgpath 库（npm 装 managed workspace）abs→unarc→unshort→iterate 算包围盒，scale+translate 把图形等比缩放到 24×0.92 并平移到 (12,12) 居中。自写 path 解析器易错（V/H 单参数命令打乱配对、a 圆弧终点），别手写。7 枚勋章已按此法居中（2026-08-04）。
• 圆形头像裁剪：必须「外层 overflow:hidden + <image> 自身 border-radius:50%」双保险，否则远程照片（cloud://）裁不掉。
• 系统字体缩放致文字溢出固定盒（真机重现、模拟器不重现）：getAppBaseInfo().host.env==='devtools' 时跳过补偿，真机/PC 才把字号 ÷factor 并 clamp。凡文字进固定圆/方盒且靠 overflow:hidden 裁切，都要考虑。
• 云函数写库必须 { data: {...} } 包裹（wx-server-sdk 2.6.3）：set/update/add 漏包裹报 parameter.data should be object。读操作 get() 无此限制。
• 自定义组件宿主默认 inline：页面给 <ui-card> 等标签加 border/transform/box-shadow 会碎裂或静默失效（仅 ui-card 已修 :host{display:block}）。描边优先用 box-shadow:0 0 0 Nrpx 并补 border-radius，别用 border。跨组件边界的 nth-child 选择器一律失效，交错延迟由页面传 index 驱动。
• @font-face 本地路径不可靠：微信小程序 @font-face 的 src:url('./local.woff2') 本地相对路径在真机上不生效（devtools 可能假性生效），字体静默回退系统字体。唯一可靠方案：把 woff2 转 base64 data URI 内联到 src:url('data:font/woff2;charset=utf-8;base64,...')，不依赖外部文件/网络。wx.loadFontFace 需配 downloadFile 域名白名单且网络不稳，同样不推荐。
• 隐私协议在 MP 后台配置，不在 app.json：chooseAvatar 属隐私接口，需在小程序管理后台「设置→服务内容声明→用户隐私保护指引」声明「用户信息(头像/昵称)」。代码里（app.json）看不到隐私配置是正常的；判断隐私合规先确认后台指引状态，别只看代码就下"审核风险"结论。已上架运行 = 后台已配好。__usePrivacyCheck__:true 仅本地调试用，正式版非必须。
• App.onLaunch 的 async/await 不阻塞首屏：微信框架是「非阻塞生命周期调度」——onLaunch 被调用但页面 onLoad/onShow 并行推进，不等 onLaunch 内 Promise resolve。所以 app.js 里 await cloud.pullAll() 不会卡首屏，只是 await 之后的同步逻辑延迟执行。判断启动性能别把 onLaunch 的 await 当阻塞。
• 代码审查避免过度判断：给本项目做问题分析时，勿把"合理设计选择/优化建议"拔高成"问题/风险"。已被纠错的判断：①隐私协议缺失（实为后台配置，代码看不到）②onLaunch await 阻塞启动（机制理解错）③组件默认 isolated 不一致（实为合理分层）。下结论前先核实机制事实，区分"真 bug / 可优化 / 合理设计"。

排行榜架构（2026-07-28+，云函数 cloudfunctions/leaderboard）

• 预计算快照：定时触发器（每 4min）_rebuildSnapshots() 扫 plank_data 算 day/month/year/endurance 四榜写 leaderboard_snapshot；客户端 99% 走 _serveFromSnapshot()（≈50ms），仅训练后 force=true 那次实时重算+回写。改后须重新部署云函数（定时器随部署注册）。
• 耐力榜(endurance)：全局单次最久，取 max(duration) 并记 bestDate；本人未进 top10 由 my-bar 在底部显示（依赖快照存 top500）。
• 头像延迟已通过云函数 getTempFileURL 预解析解决；plank_data.updatedAt 需建单字段索引。

语音 / 常亮 / 循环训练

• TTS 词条两份白名单（utils/voice.js 与 cloudfunctions/tts/index.js）须同步；加词条后必须重新部署 tts 云函数。词条避免含数字/变量（如"第3组"），用通用句。
• voice.play 截断前一条（_playSeq）：circuit halfway 与 rest 切换同刻须用 _voiceBusyUntil 让位；每组<10s 不播过场。
• wx.setKeepScreenOn 是小程序级、切后台失效：onUnload 须显式关，onShow 若 isRunning 须重新武装（否则后半程息屏丢语音/震动）。
• 循环训练 circuit（2026-08-03）：自由训练的循环形态，不碰 plan.js。入口首页 ghost 按钮→配置弹窗→timer?circuit=1&...。duration=组数×每组秒（不含休息）；记录 mode:'circuit'、planId:'circuit'（计入连胜不计入计划进度）。状态机 utils/circuitTimer.js。

约定

• 页面叫法：index=训练首页，timer=训练页，leaderboard=排行榜，records=记录，settings=设置。
• 美化按"见效快优先"分批，每轮 node --check + grep 残留再交付。
• git push 须 dangerouslyDisableSandbox:true（沙箱隔离致 github SSL 超时）；无 SSH，仅 HTTPS remote。
• GitHub 链路不稳：国内环境到 github.com:443 常 SSL 重置/HTTP2 framing 失败（非代码问题），git.soao.net(soao) 国内远程稳定。策略：soao 为主远程、实时同步；origin(GitHub) 失败则延后推或本地代理(127.0.0.1:7890 等)临时 git -C <repo> config http.proxy 推完 config --unset 撤销。代码已 commit 则零丢失风险。