# 项目长期记忆（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。
- **圆形头像裁剪**：必须「外层 `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` 驱动。

## 排行榜架构（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。