1
This commit is contained in:
66
_DEL/miniprogram-dev/05-lessons/convergence-patterns.md
Normal file
66
_DEL/miniprogram-dev/05-lessons/convergence-patterns.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# 收敛模式与不可消除差异
|
||||
|
||||
> 记录视觉还原过程中的收敛规律和不可消除差异白名单。
|
||||
> 基于 A-C 批次（53 单元）的实际数据总结。
|
||||
|
||||
---
|
||||
|
||||
## 不可消除差异白名单
|
||||
|
||||
以下差异在所有页面中均存在，不计入差异率，审计报告中标注「不可消除，已忽略」：
|
||||
|
||||
| 差异类型 | 根因 | 估计贡献 |
|
||||
|---|---|---|
|
||||
| 字体渲染（字形、次像素、间距） | Chromium（Noto Sans SC）vs 微信 WebView（系统字体） | ~2% |
|
||||
| 行内元素高度系统性偏小 ~7% | WebView 字体度量（ascent/descent/leading）差异 | ~1% |
|
||||
| rpx 取偶数四舍五入 | 每个 px 值换算后取偶数，累积微小偏差 | ~0.5% |
|
||||
| 抗锯齿差异 | 渲染引擎对边缘像素处理不同 | ~0.5% |
|
||||
| 环比箭头（SVG vs 文字 ↑↓） | 已确认可接受 | — |
|
||||
| CSS 渐变文字 → 纯色文字 | MP 不支持 `-webkit-text-fill-color` + clip | — |
|
||||
| Banner 纹理差异 | 7 层叠加渐变 + SVG 纹理无法完全复现 | ~3% |
|
||||
|
||||
背景噪音基线：~3.87%（Benchmark v3 实测）。<5% 通过目标在基线之上仅有 ~1% 修正空间。
|
||||
|
||||
---
|
||||
|
||||
## 典型收敛曲线
|
||||
|
||||
### 单屏页面（board-coach/customer 维度）
|
||||
- 初始差异率：4-11%
|
||||
- 白名单扣除后：<3%
|
||||
- 通常 0 轮修正直接通过
|
||||
|
||||
### 多屏长页面（board-finance）
|
||||
- step-0：6% → 0 轮通过
|
||||
- step-600~1200：9-11% → 含滚动偏移 + 字体渲染
|
||||
- step-2400~3600：15-18% → 累积高度偏移，跳过
|
||||
- step-4200+：3% → 页面底部，双端 clamp 到 maxScroll
|
||||
|
||||
### 任务详情系列（task-detail）
|
||||
- step-0：20-24% → mock 数据差异 ~15% + Banner 纹理 ~3% + 字体 ~3%
|
||||
- 全部跳过（白名单覆盖）
|
||||
|
||||
---
|
||||
|
||||
## 跳过原因分类
|
||||
|
||||
| 原因 | 出现频率 | 可修复性 |
|
||||
|------|---------|---------|
|
||||
| 累积高度偏移（rpx 取整导致 MP 页面更短） | 高 | 不可修复（系统性） |
|
||||
| mock 数据差异 | 中 | 可修复（对齐数据） |
|
||||
| Banner 纹理差异 | 中 | 部分可修复（简化纹理） |
|
||||
| 话术设计变体（H5 vs MP 实现差异） | 低 | 需重构 |
|
||||
|
||||
---
|
||||
|
||||
## 高度偏移规律
|
||||
|
||||
MP 页面总高度因 rpx 取整累积比 H5 略短。偏移量随页面长度增大：
|
||||
|
||||
| 页面 | H5 scrollHeight | MP scrollHeight | 偏移 |
|
||||
|------|----------------|----------------|------|
|
||||
| board-finance/default | 5600px | ~5030px | ~570px（10%） |
|
||||
| board-finance/compare | 5579px | ~5030px | ~549px |
|
||||
|
||||
偏移导致中间屏（step-2400~3600）的内容窗口错位严重，是跳过的主要原因。
|
||||
页面首尾屏不受影响（首屏 scrollTop=0，尾屏双端 clamp 到 maxScroll）。
|
||||
148
_DEL/miniprogram-dev/05-lessons/pitfalls.md
Normal file
148
_DEL/miniprogram-dev/05-lessons/pitfalls.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 踩坑速查与迁移经验
|
||||
|
||||
> 经 User 确认后录入的实践经验。AI 发现新踩坑点时先提出建议，User 确认后再录入。
|
||||
> 按类别组织，每条记录包含：场景、问题、解决方案、影响页面。
|
||||
|
||||
---
|
||||
|
||||
## WXML 模板
|
||||
|
||||
### 禁止在 `{{}}` 中调用 JS 方法
|
||||
- 场景：WXML 模板中使用 `.toFixed()`、`.map()` 等
|
||||
- 问题：小程序模板不支持 JS 方法调用
|
||||
- 方案：用 WXS 模块 `utils/format.wxs`
|
||||
- 影响：所有页面
|
||||
|
||||
### TabBar 页面跳转必须用 `wx.switchTab`
|
||||
- 场景：从非 tabBar 页面跳转到 task-list、board-finance、my-profile
|
||||
- 问题：`navigateTo` 会静默失败
|
||||
- 方案：tabBar 页面一律用 `wx.switchTab`
|
||||
- 影响：所有涉及 tabBar 跳转的页面
|
||||
|
||||
---
|
||||
|
||||
## 样式与布局
|
||||
|
||||
### 一屏页面用 `height: 100vh` 而非 `min-height`
|
||||
- 场景：login、reviewing、no-permission 等单屏页面
|
||||
- 问题：`min-height: 100vh` 在某些情况下不生效
|
||||
- 方案：`height: 100vh` + `box-sizing: border-box`
|
||||
- 影响：login, reviewing, no-permission
|
||||
|
||||
### 状态栏适配禁止用 `env(safe-area-inset-top)`
|
||||
- 场景：自定义 navBar 页面的顶部 padding
|
||||
- 问题：小程序不支持 `env()` CSS 函数
|
||||
- 方案：JS `wx.getSystemInfoSync().statusBarHeight` 动态设置
|
||||
- 影响：所有自定义 navBar 页面
|
||||
|
||||
### `padding-top + 100vh` 必须配合 `box-sizing: border-box`
|
||||
- 场景：有顶部 padding 的全屏页面
|
||||
- 问题：不加 box-sizing 会导致底部内容溢出
|
||||
- 方案：始终添加 `box-sizing: border-box`
|
||||
- 影响：所有全屏页面
|
||||
|
||||
---
|
||||
|
||||
## TDesign 组件
|
||||
|
||||
### `t-button icon` 只支持内置图标
|
||||
- 场景：按钮中使用品牌图标（微信 logo 等）
|
||||
- 问题：`icon` 属性只接受 TDesign 内置图标名
|
||||
- 方案：用 `<view>` + `<image>` 组合替代
|
||||
- 影响：login 页面微信登录按钮
|
||||
|
||||
### TDesign 默认样式优先级高
|
||||
- 场景：需要大幅覆盖 TDesign 组件样式
|
||||
- 问题：CSS 变量和外部样式类不够用时，`!important` 也可能不生效
|
||||
- 方案：直接用原生 `<view>` 实现，绕开样式干扰
|
||||
- 影响：视具体组件
|
||||
|
||||
---
|
||||
|
||||
## 资源引用
|
||||
|
||||
### 所有 H5 内联 SVG 必须导出为独立文件
|
||||
- 场景：H5 中直接写在 HTML 内的 `<svg>` 元素
|
||||
- 问题：小程序不支持内联 SVG
|
||||
- 方案：导出为 `.svg` 文件存放 `assets/icons/`，用 `<image>` 引用
|
||||
- 影响：所有含内联 SVG 的页面
|
||||
|
||||
### 引用不存在的图片会 500 错误
|
||||
- 场景：WXML 中 `<image src>` 指向不存在的文件
|
||||
- 问题：不是 404 而是 500 错误，难以排查
|
||||
- 方案：用 CSS 渐变、emoji、`<t-icon>` 替代；或确保文件存在
|
||||
- 影响：所有页面
|
||||
|
||||
---
|
||||
|
||||
## 截图与对比
|
||||
|
||||
### rpx 取整导致累积高度偏移
|
||||
- 场景：多屏长页面的中间屏截图对比
|
||||
- 问题：MP 页面总高度比 H5 短 ~10%，中间屏内容窗口错位
|
||||
- 方案：使用锚点对齐法（按元素位置对齐而非 scrollTop 数值）
|
||||
- 影响：board-finance, performance 等长页面
|
||||
- 发现日期：2026-03-10
|
||||
|
||||
### AI 浮动按钮动画造成随机差异
|
||||
- 场景：截图时 ai-float-button 的 gradientShift 动画处于不同帧
|
||||
- 问题：每次截图差异 ~1%
|
||||
- 方案：双端截图前隐藏（H5 用 JS，MP 用 `wx:if="{{false}}"`)
|
||||
- 影响：所有含 ai-float-button 的页面
|
||||
- 发现日期：2026-03-10
|
||||
|
||||
### 禁止跨维度套用布局假设，H5 原型是唯一视觉真相
|
||||
- 场景：board-customer "最专一"卡片的 `.loyal-table` 布局
|
||||
- 问题：其他维度（最应召回等）的 `card-mid-row` / `card-assistant-row` 有 `ml-11`（80rpx 对齐头像右侧），开发时"合理推断"表格也应该加 `margin-left: 80rpx`。但 H5 原型中表格容器没有 `ml-11`，是从卡片 padding 开始的（left=16px）。Playwright 实测才发现偏差
|
||||
- 方案：每个维度的每个组件都必须回到 H5 HTML 逐一确认 Tailwind 类，禁止从其他维度"类推"。不确定时用 Playwright `getBoundingClientRect()` 实测 H5 元素位置
|
||||
- 影响：所有多维度页面（board-customer 8 维度、board-coach 4 维度）
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
### H5 与 MP mock 数据不同，像素级 diff 需结合结构比对
|
||||
- 场景：用 PIL/numpy 或 image-compare 对比 H5 和 MP 截图
|
||||
- 问题：H5 原型使用硬编码 mock 数据（如孙先生/王先生/李女士），MP 使用后端返回的测试数据（王先生/李女士/张先生），文字内容不同导致像素 diff 高达 11%，18 个分段覆盖全页面，无法区分"数据差异"和"样式差异"
|
||||
- 方案：像素级 diff 仅用于发现大面积结构偏移（窗口错位、整块缺失）。样式还原度验证的主要方法是 Tailwind 类→rpx 值逐项比对表，逐一确认每个 CSS 属性的换算结果
|
||||
- 影响：所有页面的截图对比流程
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
### Tailwind→WXSS 映射必须逐项建表验证
|
||||
- 场景：将 H5 Tailwind 类翻译为小程序 WXSS
|
||||
- 问题：凭记忆或经验直接写 WXSS 值容易出错——`font-medium` 是 500 不是 600，`gap-1` 是 4px 不是 2px，`space-y-2` 是 8px 不是 4px。错误在视觉上不明显但会累积
|
||||
- 方案：对每个组件建立完整的对照表（H5 Tailwind 类 → 计算值 px → rpx 换算 → MP WXSS 值），逐行核对。参考速查表：`2→4, 4→8, 6→10, 8→14, 10→18, 12→22, 14→24, 16→28, 20→36, 24→42`
|
||||
- 影响：所有页面的 WXSS 编写
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
### 相邻元素间距叠加导致高度翻倍
|
||||
- 场景：经营一览的 `.overview-grid-2` 底部 padding 32rpx + `.ai-insight-section` margin-top 32rpx，间距翻倍为 64rpx
|
||||
- 问题：H5 中 grid 无 margin-bottom，间距完全由下方元素的 `mt-4`(16px) 提供。MP 中两端都加了间距，导致块间距翻倍、整体高度偏高
|
||||
- 方案：校对间距时必须确认「这段间距是谁提供的」——上方元素的 padding-bottom 还是下方元素的 margin-top。用 Playwright `getComputedStyle` 实测 H5 两个相邻元素的 margin/padding，确认间距归属后只在一端设置
|
||||
- 影响：所有包含多个子区块的板块（经营一览、预收资产等）
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
### 用 Playwright 实测 H5 比手动解析 Tailwind 更可靠
|
||||
- 场景：H5 原型文件是单行 minified HTML，手动读取 Tailwind 类名容易遗漏或误判
|
||||
- 问题：Tailwind 类名组合后的实际渲染值不直观（如 `p-4` 在嵌套容器中可能被覆盖，`space-y-2` 的实际 gap 取决于子元素数量），手动推算容易出错
|
||||
- 方案：通过 `browser_run_code` 创建 375×812 viewport + DPR 1.5 的 context，用 `getComputedStyle` + `getBoundingClientRect` 直接拿到渲染后的实际 px 值，再按换算规则转 rpx。这个方法应作为所有页面校对的标准流程
|
||||
- 影响：所有页面的 WXSS 校对流程
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
### Tailwind 字号类自带 line-height，WXSS 必须同步补齐
|
||||
- 场景：校对经营一览的现金流水概览 4 个块，H5 明显比 MP 高
|
||||
- 问题：Tailwind 的 `text-xs`/`text-sm`/`text-lg`/`text-xl` 等字号类捆绑了特定的 `line-height`（如 `text-lg` = `font-size: 18px; line-height: 28px`），但 WXSS 只写了 `font-size` 没写 `line-height`，小程序默认行高约 1.2，远小于 Tailwind 的行高，导致每行文字占据的垂直空间不足，块整体矮了一截
|
||||
- 方案：每个 Tailwind 字号类转 WXSS 时，必须同时写 `font-size` 和 `line-height`。完整对照表（87.5% 缩放）：
|
||||
|
||||
| Tailwind | font-size (px) | line-height (px) | WXSS font-size | WXSS line-height |
|
||||
|----------|---------------|------------------|----------------|-----------------|
|
||||
| `text-xs` | 12 | 16 | 22rpx | 28rpx |
|
||||
| `text-sm` | 14 | 20 | 24rpx | 34rpx |
|
||||
| `text-base` | 16 | 24 | 28rpx | 42rpx |
|
||||
| `text-lg` | 18 | 28 | 32rpx | 48rpx |
|
||||
| `text-xl` | 20 | 28 | 36rpx | 48rpx |
|
||||
| `text-2xl` | 24 | 32 | 42rpx | 56rpx |
|
||||
|
||||
- 影响：所有页面的所有文字元素
|
||||
- 发现日期：2026-03-12
|
||||
|
||||
---
|
||||
|
||||
> 新增经验请按以上格式录入，包含：场景、问题、解决方案、影响页面、发现日期（可选）。
|
||||
Reference in New Issue
Block a user