lc
ca1793b4c0
- 趋势组件 trend-chart 新增 chartType(line/bar),line 模式用内联 SVG 渲染折线+渐变面积(无 canvas) - 记录页个人最佳趋势改用折线图,峰值信息移到图表下方对称高亮块显示最佳趋势产生日期 - 修复1: linePoints 漏存绝对坐标 y 导致运行时 toFixed 崩溃 - 修复2: 折线模式漏渲染数据点数值(valueText),现圆点上方显示且 0 值不显示
31 lines
5.9 KiB
Markdown
31 lines
5.9 KiB
Markdown
# 项目长期记忆（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` 驱动。
|
||
- **隐私协议在 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 则零丢失风险。
|