wx_pbzc/.workbuddy/memory/MEMORY.md

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

关键技术陷阱

• 小程序组件 style isolation：自定义组件默认 isolated。组件内 variant 拼出的类（gradient/in 等）在组件作用域，页面里写的 .组件类 <slot后代> 跨作用域选择器全部失效（如 .ui-card.gradient .streak-num）。唯一能跨边界传递的是 CSS 自定义属性（会沿 DOM 继承进 slot）。
  • 推论：渐变/主色容器内要反白的文字，必须用 var(--text)/var(--text-secondary)（容器在 .gradient 里重定义过即会变白），绝不能用 var(--primary)——否则橙色字画在橙色底上=看不见。
  • 进度条填充同理：用 var(--on-primary, <原渐变>) 让容器可覆盖为白，而非依赖失效的后代选择器。
• 图标 SVG 颜色是烤死在 data URI 里的（utils/icons.js 的 build()：*Fill 用 primary 主题色、*（无 Fill）用灰 #999）。CSS 的 color/currentColor/变量都改不了 <image src> 这种图标。所以：
  • 放在主色/渐变底（gradient hero 卡、primary 实心按钮）上的图标必须用白色变体（hotWhite/formWhite/playWhite/trophyWhite 等），否则同色隐形。
  • 加新图标或新彩色容器时，先想清楚底色：浅色底用 *Fill（主题色），彩色/主色底用 *White 变体。
  • 主按钮 ui-btn--primary 背景是橙渐变，playFill(橙) 放上去即隐形——须用 playWhite。ghost/outline 按钮底色浅或灰，用 *Fill/灰色变体即可。
  • components/ui-btn 图标尺寸 1.3em（随按钮字号自适应），不要回到 1em 以免显得过小。
  • 需要「随状态换色」的小装饰件，一律用纯 CSS 画，别用 icon：图标色改不动，而状态灯/圆点要在 白/绿/灰 间切换。timer 页循环训练徽章的 .circuit-phase-dot 即是此解（14rpx CSS 圆点 + BEM 状态类控制 background）。
• timer 页新增顶部元素必须 position:relative; z-index:1：.breathe-ring（呼吸光晕，z-index:0）在 DOM 里排在页面上方元素之后，同 stacking 上下文下会反盖上去，把主色光晕晕染到白卡片上。循环训练进度面板 .circuit-bar 踩过。
• 深色模式有两套事实源，改配色前先统一：theme.json 的 dark 与 app.wxss/utils/theme.js 要一致（已统一到 #131316 系）。
• 微信圆形头像/图片裁剪陷阱（用户基础库实测）：本项目的圆形头像在用户机器上表现如下——
  • 单独给 <image> 加 border-radius:50%（无 overflow 父层）→ 圆框里露方图，失效。
  • 外层 <view> 加 overflow:hidden+border-radius:50% 包裹 → 能裁切 SVG 占位图，但裁不掉远程照片（cloud:// 真实头像），照片仍方。所以日榜（多为占位图）正常、月榜/年榜（真实照片）却方。
  • 唯一可靠写法：外层 overflow:hidden 父层 且 <image> 自身也加 border-radius:50%（双保险）。设置页 .avatar-btn(button,overflow:hidden)+.avatar-img(image,border-radius:50%) 即是此写法且实测正常。排行榜 .avatar/.avatar__img 已对齐这一写法。
  • 推论：以后做圆形头像，必须 image 自身 border-radius:50%，不能只靠父层 overflow。
• 微信系统字体缩放导致文字溢出固定盒子（模拟器不重现、真机重现）：微信会按用户「设置→通用→字体大小」自动放大所有文字（含 rpx 字号），但不放大 rpx 盒子尺寸（width/height/padding）。症状：固定尺寸的圆形/方形容器里的文字在真机被放大、超出后被 overflow:hidden 裁掉，模拟器（标准档倍率 1.0）正常。
  • 获取缩放：wx.getAppBaseInfo().fontSizeScaleFactor（当前字号÷标准 17px）；旧接口 getSystemInfoSync().fontSizeSetting（px，标准 17）。
  • 真机/模拟器不对称（关键坑）：getAppBaseInfo().host.env 在模拟器是 'devtools'、真机是 'wechat'。模拟器会原样返回你手机的真实缩放倍率，但渲染时并不会把文字放大；真机才会真的放大。所以若不做区分，补偿把字号缩成 design/factor 后：真机放大回 design（正常），模拟器按缩小值渲染（数字变小=「不正常」）。→ 必须在 host.env === 'devtools' 时跳过补偿、直接用设计字号；仅在真机/PC 微信才补偿。首页 _readFontScale() 已加此判断。
  • 补偿法：把容器内的关键文字字号反向除以该倍率（designRpx / factor），并在 JS 里 clamp 到安全区间（如 48–96），使真机渲染成和模拟器一致的视觉大小、永不溢出。首页 .target-time 已用此法（index.js _readFontScale()）。
  • 配套 CSS：white-space:nowrap 防换行顶出圆圈。
  • 推论：以后凡把文字放进固定尺寸的圆形/方形容器且依赖 overflow:hidden 裁切，都必须考虑字体缩放补偿，否则真机大字体档必溢出。
• 排行榜头像 1–2s 延迟根因（设计使然，非 bug）：profile.avatarUrl 存的是 cloud:// 云存储 fileID（settings._uploadAvatar 用 wx.cloud.uploadFile 返回 fileID）；云函数 leaderboard 直接透传，前端 <image src="cloud://..."> 在 setData 渲染时才把 fileID 解析成临时 https URL（等效一次 getTempFileURL 网络往返）再下载。文字（昵称/时长/排名）是本地字符串瞬时渲染 → 故"文字先出、头像后出"，延迟正是头像专属的「云存储解析 + 原图下载」段，叠加云函数冷启动。
  • 占位图 peopleFill 是本地 SVG data URI 瞬时，所以日榜（多为占位）无感、月/年榜（真实照片）延迟明显。
  • 优化方向：①云函数返回前对 cloud:// 的 avatarUrl 批量 cloud.getTempFileURL 预解析成 https；②_uploadAvatar 上传前把 chooseAvatar 原图压缩/裁剪到最长边 ~200px、转 jpg/webp，体积降一个数量级；③云函数保活降冷启动。
• 云函数数据库写操作必须 { data: {...} } 包裹（wx-server-sdk 关键坑）：wx-server-sdk(本项目 2.6.3) 的 db.collection().doc(id).set(x) / .update(x) / .add(x) 写操作，参数必须是 { data: realObj } 包裹形式——SDK 内部读 parameter.data 当作要写入的文档。直接传裸对象 set(realObj) 会让 SDK 读 realObj.data === undefined，报 parameter.data should be object instead of undefined（读操作 get() 不受影响，裸对象/无参都行）。leaderboard 云函数 _persistSnapshot 踩过此坑：写快照全失败、集合一直空。
  • 修复：docRef.set({ data: { period, ranked, myOpenid, updatedAt } })。写入后文档内容即 realObj（data 外套被 SDK 解开），读取 doc.data 仍是 realObj，读逻辑无需改。
  • 推论：以后任何云函数写库代码，先写 { data: ... }，别沿用客户端 SDK 的裸对象习惯；出错时先怀疑是不是漏了 data 包裹，而不是怀疑部署。

排行榜架构（2026-07-28 落地 P0/P1/P2 后）

• 预计算快照：cloudfunctions/leaderboard 的 exports.main 现在区分两种调用——

  • 定时触发器（config.json 的 triggers：snapshotTimer / 0 */4 * * * * *，每 4 分钟）进入 _rebuildSnapshots()：扫描一次 plank_data（_fetchLatestByOpenid，走 updatedAt 索引+投影），复用 _buildFromScan() 算 day/month/year/endurance 四榜，各自写进 leaderboard_snapshot 集合（doc._id=周期，字段 period/ranked/myOpenid/updatedAt；首次写自动建集合）。
  • 客户端请求：默认走 _serveFromSnapshot()（1 次 get ≈ 50ms），快照缺失/过期(>6min)才 _computeBoard() 实时重算并回写。首开/冷启动已从 2-3s 降到 ≈50ms。

• force 语义：仅训练后那一次（客户端 onShow 读 _lb_force_refresh 置 force=true）走 _computeBoard(force:true,persist:true) 实时重算+回写快照；其他 99% 请求读快照，已满足"force 不再绕过云缓存"诉求。

• P1 启动预热：app.js onLaunch 在 cloud.init() 后 fire-and-forget 调一次 leaderboard(day)，提前暖云实例/快照。

• 头像延迟：云函数内 getTempFileURL 预解析已落地（在 _buildFromScan 里），前端不再懒加载，故"文字先出头像后出"的 1-2s 延迟已大幅消除；快照每 4min 重写，临时 URL 始终新鲜。

• 改动注意：要生效必须重新部署 leaderboard 云函数（定时器随部署注册）。plank_data.updatedAt 单字段索引需在控制台已建（用户已建）。响应结构 {period,ranked,myOpenid,myEntry,updatedAt} 不变，客户端 leaderboard.js 无需改逻辑（仅注释更新）。

• 耐力榜（第 4 个 tab，2026-07-31 新增）：全局单次最久。_buildFromScan 的 endurance 分支遍历每人全部 records 取 max(duration) 并记下该条 r.date 作"产生时间"→ bestDate 字段靠 publicEntry 的 ...publicData 展开透传进快照/响应（无需改 data.js）。客户端 periods 加 {key:'endurance',label:'耐力',maxRank:10}；行/领奖台/my-bar 的副标签统一改用 subText（耐力=格式化日期 YYYY-MM-DD HH:MM，其余=N次）。本人未进 top10 时由既有 my-bar（myEntry.rank > rankedList.length）在底部显示其最佳成绩+日期——依赖快照存 top500、findMyEntry 在完整 500 条里定位本人，故即便排 200 也能被找到。改云函数后须重新部署（定时器随部署注册 endurance）。

• TTS 语音词条是「两份白名单」，必须同步：utils/voice.js 的 PROMPTS 与 cloudfunctions/tts/index.js 的 PROMPTS 各存一份。客户端有、云端没有 → 云函数返回 Unknown prompt key，_fetchUrl 得 success:false 后返回 null，play() 静默 return（不报错、不弹 toast，只是不出声，极难察觉）。加词条后必须重新部署 tts 云函数。词条设计上要避免包含数字/变量（如"第3组"），否则得按 N 合成 N 份音频；用"下一组，准备开始"这类通用句即可覆盖任意组数。

• voice.play 会截断前一条语音（_playSeq 机制：新 play 令旧的作废）。凡是可能同一 tick 触发两条语音的地方，必须定优先级。已知必撞场景：circuit 的 halfway 触发点 = sets×hold/2，偶数组时必然落在第 sets/2 组最后一秒，与 rest 阶段切换同刻 → 用 _playProgressVoice 设 _voiceBusyUntil = now+2600，让阶段语音在窗口内让位。类似地，每组 <10 秒时不播过场语音（一句话约 2 秒，否则连珠炮）。

• circuit 的进度播报基准必须是整场（sets × holdPerSet），不能是每组：否则 4 组会播 4 次"已完成一半啦"。判据用 <= 而非 ===，容忍小程序后台回前台的跳秒补偿。只在 phase==='working' 求值——休息时 workTotal 冻结，天然不会重复触发。

• wx.setKeepScreenOn 是「小程序级」不是「页面级」，且切后台会失效（训练页已用，pages/timer/timer.js 的 _keepScreenOn）：

  • 开了不关 → 用户离开训练页后，首页/记录/榜单全程常亮耗电，只有退出小程序才自动失效。故 onUnload 必须显式 keepScreenOn:false。
  • 反过来，切后台再回前台会被系统清掉，所以 onShow 里要 if (this.data.isRunning) 重新武装，否则后半程又开始息屏丢语音/震动。
  • fail 必须静默（部分 Android ROM 省电模式拒绝该调用），低基础库用 typeof wx.setKeepScreenOn !== 'function' 降级。
  • 背景：息屏/后台后 JS 定时器被节流，Timer/CircuitTimer 靠 Date.now 补偿秒数不会错，但实时提示（语音/震动）错过就没了——平板支撑用户手撑地不碰屏，60 秒必息屏，所以常亮实际是在修 bug 而非锦上添花。

• 自定义组件宿主节点默认是 inline —— 页面侧给组件标签加 border/box-shadow/transform 会碎裂或静默失效：本项目 components/ 下 7 个组件没有任何一个写了 :host { display: block }（全局 grep :host/display:block 零匹配），组件 wxss 只给内部那个 view（如 .ui-card）写样式。宿主节点（页面 wxml 里的 <ui-card> 标签）因此是 inline 盒。

  • 页面 wxss 可以命中宿主节点上的 class（style isolation 只隔离组件内部），所以样式确实生效了——但按 inline 盒规则渲染：
    • border → inline 盒被内部 block 打断成前/后两个零宽行盒，只在碎片上画左右边框（各 4rpx 贴合成一根竖线）→ 视觉是 block 左上角、左下角各一条竖条，而不是包一圈。首页 .just-completed（训练完成 3 秒高亮）就是这个症状。
    • transform: scale() → 完全无效（不适用于非替换 inline 元素），脉冲/缩放动画静默不生效。
    • box-shadow → 同样只画在零宽碎片上，等于看不见。
  • 诊断特征：只要是"某个自定义组件标签上加了装饰样式，结果出现零散短线/动画不动"，先怀疑宿主 inline，而不是怀疑选择器没命中。
  • 修法：组件 wxss 加 :host { display: block; }（小程序支持 :host）。改前需回归各页面该组件的间距布局（inline→block 会吃掉行内空白、宽度变 100%）；ui-btn 这类可能被当行内用的组件要单独评估。
  • 同源坑：ui-card.wxss 的 .ui-card.in:nth-child(1..4) 交错入场延迟也是失效的——.ui-card 在组件内部永远是根下第 1 个子元素，恒匹配 nth-child(1)。跨组件边界做"第 N 个"选择器一律不可靠，要交错必须由页面传 index 或内联 animation-delay。
  • 已修（2026-08-03，仅 ui-card）：加了 :host { display:block; margin-bottom:24rpx; box-sizing:border-box }，并把 margin-bottom 从内部 .ui-card 上提到宿主——否则页面侧加的边框会把 24rpx 外边距一起圈进框里，框比卡片高一截。交错延迟改为 index 属性驱动的内联 animation-delay（50 + min(index,3)*100 ms），14 处调用点全部显式传 index；index 默认 0，漏传也只是退回旧行为，零回归。
  • 其余 6 个组件宿主仍是 inline，不要盲目批量加 :host{display:block}：ui-btn 在 pages/timer/timer.wxml 里靠 custom-style="margin-right:28rpx" 并排布局，改 block 会直接撑成整行。要改必须逐个回归。
  • 页面侧给组件标签做描边，优先用 box-shadow: 0 0 0 Nrpx <color> 而不是 border：border 会改变宿主盒尺寸（撑大或在 border-box 下向内压窄内容），高亮出现/消失时布局跳动；box-shadow 不占布局空间。但宿主自身没有圆角，必须显式补上与内部卡片一致的 border-radius，否则描边是直角框套在圆角卡片外面。

约定

• UI 动词说法：index=首页/训练首页，timer=训练页，leaderboard=排行榜，records=记录，settings=设置。
• 美化按"见效快优先"分批做，每轮 node --check + grep 残留再交付。
• git 推送需走 sandbox 外：本机 Bash 工具默认 sandbox 隔离网络，git push 到 github.com 会 SSL connection timeout（约 5 分钟才报错）。必须用 dangerouslyDisableSandbox: true 在沙箱外执行推送（或 run_in_background + 沙箱外）才能连上。无 SSH key，remote 仅 HTTPS。

功能：循环训练 circuit（2026-08-03 落地，简化版 + 配置持久化）

• 定位：「自由训练」的循环形态，不是新计划体系。不碰现有 utils/plan.js 的 hold 模式与每日计划进度。
• 入口：首页「循环训练 · 分组练习」ghost 按钮 → 底部配置弹窗（stepper 调 每组时长/组数/休息/每周目标）→ saveCircuitConfig + 跳 timer?circuit=1&hold=&sets=&rest=&sessions=。
• 配置持久化：utils/storage.js 的 getCircuitConfig/saveCircuitConfig（本地 circuit_config 键，含默认值+范围校验，不进云同步）。下次打开弹窗预填上次值。
• 状态机：utils/circuitTimer.js（新）CircuitTimer 类，接口仿 Timer：start/stop/pause/resume + onTick/onPhaseChange/onComplete；stop() 返回 workTotal（有效撑总秒，不含休息）。
• 关键不变量 1：duration 始终 = 有效撑总秒（组数×每组秒，不含休息） → 排行榜/里程碑/统计零改动。
• 关键不变量 2：循环记录 planId 用 'circuit' → getPlanDay 不会把它算进每日计划进度；但 updateStreak 仍计入连胜（用户确实练了）。
• 记录落库字段：mode:'circuit' + sets/holdPerSet/restPerSet/sessionsPerWeek（records 页按 r.mode 显示「循环 N组×Ms」）。
• 阶段提示：TTS 只有 6 个固定 key 无"第N组/休息"词 → circuit 阶段切换用震动 + 屏上 phaseTip 文本，完成复用 complete 语音。
• 进度环：circuit 模式轨道恒中性灰（否则每阶段都按"累计≥阶段长"误判变绿）。
• 未做（可选后续）：周频次硬追踪（仅存 sessionsPerWeek 作显示）、逐周进阶、设置页统一管理。
• 验证：6 个 JS 全过 node --check；未动云函数/榜单/云同步。