# 踩坑速查与迁移经验

> 经 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

---

> 新增经验请按以上格式录入，包含：场景、问题、解决方案、影响页面、发现日期（可选）。