1

.kiro/specs/h5-miniprogram-migration-subsequent/design.md

@@ -0,0 +1,498 @@
+# 技术设计文档：H5 → 微信小程序像素精调
+
+## 1. 概述
+
+本设计文档为 17 个页面（共 79 个对照处理单元）的 Step 6-7 像素精调提供技术方案。所有页面已完成 Step 0-5 结构迁移（TS 零诊断、路由注册、四态处理）。
+
+核心设计思路：以「对照处理单元」为最小粒度，通过两阶段收敛流程（结构级修正 → 像素级精调）系统性消除视觉差异。
+
+参考文档（不重复，仅索引）：
+- 迁移规则与转换公式：`docs/prd/MIGRATION-PLAYBOOK.md`
+- 样式标准值：`docs/h5_ui/design-tokens.json`（颜色灰阶、字号、圆角、阴影的标准 rpx 值）
+- 工具链源码：`scripts/ops/anchor_compare.py`
+
+## 2. 截图策略
+
+### 2.1 双端参数对齐
+
+| 参数 | H5 | MP | 对比基准 |
+|------|-----|-----|---------|
+| viewport | 430×752 | 430×752（windowHeight） | 统一 |
+| DPR | 1.5 | 1.5（MCP 有效 DPR） | 统一 |
+| 输出尺寸 | 645×1128 | 645×1128 | 统一，无需缩放 |
+
+> 验证数据（2026-03-10 board-finance 实测）：H5 Playwright DPR=1.5 输出 645×1128；MP MCP screenshot 输出 645×1128。两端尺寸完全一致，无需任何缩放处理。
+
+### 2.2 固定步长滚动方案
+
+采用固定 600px 步长滚动截图，替代锚点方案。两端使用完全相同的 scrollTop 序列（0, 600, 1200, ...），不依赖锚点位置，消除 H5/MP 元素位置差异导致的对齐问题。
+
+核心参数：
+- 步长：600px（逻辑像素）
+- scrollTop 序列：从 0 开始，每次 +600，最后一屏 clamp 到 `maxScroll = scrollHeight - viewportHeight`
+- 段数计算：`N = floor(maxScroll / 600) + 1`（首屏 step-0 + 每 600px 一步 + 最后一步 clamp 到 maxScroll）；`maxScroll ≤ 10` 的页面视为单屏（N=1）
+
+实测精度（board-finance，2026-03-10）：
+- H5 端：Playwright `window.scrollTo` 精确命中目标值（偏差 0px）
+- MP 端：`wx.pageScrollTo` 精确命中目标值
+
+### 2.3 底部浮动元素处理
+
+H5 端存在 `#bottomNav`（64px fixed 底部导航）和 `.ai-float-btn-container`（56px 浮动按钮），MP 端使用原生 tabBar（不在 webview 截图中）。
+
+处理方式：H5 截图前用 JS 隐藏所有底部浮动元素：
+```javascript
+document.getElementById('bottomNav').style.display = 'none';
+document.querySelectorAll('.ai-float-btn-container').forEach(el => el.style.display = 'none');
+```
+MP 端原生 tabBar 本来不在截图中，无需处理。MP 端如果存在 AI 浮动按钮，因 H5 端已隐藏，该区域的差异在对比时可忽略，不计入差异率。
+
+### 2.4 浮动元素专项检测（结构校验阶段）
+
+长页面滚动截图中，sticky/fixed 元素（如 sticky 导航栏、筛选栏）在每一屏的相同位置出现。通过滚屏上下页对比，可以精准识别这些浮动元素的差异并专项修复。
+
+检测方法：
+1. 对同一页面的相邻屏截图进行对比，在不同屏中持续出现在相同位置的差异区域即为 sticky/fixed 元素
+2. 对 H5 vs MP 的 sticky 区域做像素对比，差异即为浮动元素的样式偏差
+3. sticky 元素差异在每一屏都会重复出现，修复一次即可消除所有屏的该区域差异
+
+适用场景：
+- board-finance：`.safe-area-top`(45px) + `#filterBar`(71px) = 116px sticky
+- board-coach/board-customer：`.board-tabs`(42px) + `.filter-bar`(68px) = 110px sticky
+- 所有带 sticky 头部的长页面
+
+优化效果：修复 sticky 区域差异后，所有屏的差异率会同步下降（因为每屏都包含相同的 sticky 区域）。
+
+### 2.5 截图操作指南
+
+#### 2.5.1 H5 截图
+
+底层技术：Playwright + Chromium，viewport 430×752，DPR=1.5，headless=True。
+
+流程：
+1. 打开 Live Server 提供的 H5 页面（`http://localhost:5500/docs/h5_ui/<page>.html`）
+2. 等待 Tailwind CDN JIT 渲染（1500ms）
+3. 隐藏滚动条 + 底部浮动元素（`#bottomNav` + `.ai-float-btn-container`）
+4. 按 scrollTop 序列逐屏截图：先 `scrollTo(0,0)` 再 `scrollTo(0, target)`
+
+截图脚本：`scripts/ops/anchor_compare.py extract-h5 <page>`（固定 600px 步长模式）
+
+输出：`docs/h5_ui/compare/<page>/h5--step-<scrollTop>.png`（645×1128）
+
+#### 2.5.2 MP 截图
+
+前置条件：微信开发者工具已打开，MCP 已连接。
+
+流程：
+1. 导航到目标页面（tabBar 页面用 `switch_tab`，其他用 `navigate_to`）
+2. 等待页面加载（2000ms）
+3. 按相同 scrollTop 序列逐屏截图：
+   ```javascript
+   // 每屏：先回顶再滚到目标，确保精确
+   wx.pageScrollTo({ scrollTop: 0, duration: 0 })
+   // 等待 200ms
+   wx.pageScrollTo({ scrollTop: target, duration: 0 })
+   // 等待 500ms，读取实际 scrollTop，截图
+   ```
+
+输出：`docs/h5_ui/compare/<page>/mp--step-<scrollTop>.png`（645×1128）
+
+#### 2.5.3 多维度页面 MP 截图
+
+board-coach 和 board-customer 为多维度页面，每个维度的卡片模板不同，需逐维度截图。
+
+board-coach（4 种排序维度）：
+- 维度通过筛选栏下拉切换（`onSortChange`），对应 4 种卡片模板：`perf`（定档业绩）、`salary`（工资）、`sv`（客源储值）、`task`（任务完成）
+- MP 操作：获取页面快照 → 点击排序筛选下拉 → 选择目标维度 → 等待列表刷新 → 截图
+- H5 操作：通过 JS 调用 `selectType('perf_desc')` 等切换 dim-container 显隐 → 截图
+- 子目录：`board-coach/perf/`、`board-coach/salary/`、`board-coach/sv/`、`board-coach/task/`
+
+board-customer（8 种客户维度）：
+- 维度通过筛选栏下拉切换（`onDimensionChange`），对应 8 种卡片模板：`recall`（最应召回）、`potential`（消费潜力）、`balance`（最高余额）、`recharge`（最近充值）、`recent`（最近到店）、`spend60`（最高消费）、`freq60`（最频繁）、`loyal`（最专一）
+- MP 操作：获取页面快照 → 点击维度筛选下拉 → 选择目标维度 → 等待列表刷新 → 截图
+- H5 操作：通过 JS 调用 `selectType('recall')` 等切换 dim-container 显隐 → 截图
+- 子目录：`board-customer/recall/`、`board-customer/potential/` ... `board-customer/loyal/`
+
+> 交互文档参考：`docs/h5_ui/interactions/board-coach.md`、`docs/h5_ui/interactions/board-customer.md`
+
+#### 2.5.4 逐屏对比
+
+对同一 scrollTop 的 H5/MP 截图做像素对比：
+```
+mcp_image_compare_compare_images
+  image1_path: "docs/h5_ui/compare/<page>/h5--step-<N>.png"
+  image2_path: "docs/h5_ui/compare/<page>/mp--step-<N>.png"
+  diff_output_path: "docs/h5_ui/compare/<page>/diff--step-<N>.png"
+  threshold: 0.1
+```
+
+### 2.5.5 双端高度不一致处理
+
+MP 端页面高度可能与 H5 不一致（样式差异导致内容更短或更长）。如果直接按 H5 的 scrollTop 序列去滚 MP，可能滚过头（scrollTo 被 clamp）或漏截（页面更长）。
+
+处理流程：
+1. 先截双端 step-0（首屏），对比确认基线
+2. 再截 step-600（第二屏），读取 MP 端实际 scrollTop：
+   - 如果 MP 实际 scrollTop 远小于 600（被 clamp），说明 MP 页面比 H5 短，后续步骤需按 MP 实际 maxScroll 调整序列
+   - 如果 MP 实际 scrollTop ≈ 600，说明双端高度接近，继续按 H5 序列推进
+3. 之后逐屏推进，每屏截图前先读取 MP 端实际 scrollTop，确认到达预期位置
+4. 如果 MP 页面比 H5 长（MP 还能继续滚但 H5 序列已结束），追加额外步骤直到 MP 也到达 maxScroll
+
+> 此规则防止因双端高度差异导致后续屏截图错位或遗漏。
+
+### 2.6 长页面级联影响与修正规则
+
+修正某一屏的 WXSS 时，可能影响后续屏的布局。因此：
+
+1. 修正后必须重新截取所有屏的截图（因为固定步长方案下，布局变化会影响每屏内容）
+2. 优先修复 sticky 区域差异（一次修复，所有屏受益）
+3. 从 step-0 开始顺序审查差异，确保前序屏达标后再处理后续屏
+4. 如果修正引入回归，回退到受影响的最早屏重新验证
+
+### 2.7 结构级视觉元素识别清单（阶段一修正范围）
+
+以下元素类型在双端截图中容易产生大面积差异（>10%），属于阶段一优先识别和修正的对象。严重缺失时可能导致 >15% 触发重写。
+
+#### 2.7.1 大面积背景
+
+| 背景类型 | MP 支持 | 处理方式 |
+|----------|---------|---------|
+| 纯色 / `linear-gradient` / `radial-gradient` / `repeating-linear-gradient` | ✅ | 直接迁移，查 `docs/h5_ui/design-tokens.json` 取精确色值和方向 |
+| `backdrop-filter: blur()` | ❌ | 改用 `background: rgba(255,255,255,0.95)` 半透明纯色 |
+| `url("data:image/svg+xml,...")` | ❌ | 用 CSS 渐变模拟，或导出为 PNG/base64 引用 |
+
+精调要点：
+- 渐变方向和色值必须与 H5 完全一致，大面积色差肉眼极其明显
+- 半透明背景透明度差 0.1 在大面积上可见
+
+#### 2.7.2 复杂图标与 SVG
+
+Step 0-5 已完成所有 SVG 迁移决策（详见 `MIGRATION-PLAYBOOK.md` 3.5 节）。精调阶段关注：
+
+| 图标类型 | 精调关注点 | 已审计案例 |
+|----------|-----------|-----------|
+| TDesign `<t-icon>` | `size`（rpx）和 `color` 与 H5 原始 SVG 一致 | 目录按钮 `view-list`、筛选箭头 `caret-down-small` |
+| 导出 SVG + `<image>` | `width`/`height`（rpx）与 H5 显示尺寸一致 | AI 悬浮按钮、底部导航栏图标 |
+| 文字/Emoji 替代 | 可接受差异，不计入差异率 | 环比箭头 ↑↓、AI 机器人 🤖 |
+| CSS 渐变 + 文字组合（如头像） | 渐变方向、色值、圆角、文字大小一致 | 客户头像（8 种渐变色 135deg） |
+| 帮助"?"图标（文字+圆形背景） | 圆形背景 size/color、文字 font-size 一致 | board-finance 指标标签旁 |
+
+图标缺失或尺寸严重偏差属于阶段一结构级问题；尺寸/颜色微调属于阶段二。
+
+#### 2.7.3 带文字的标签（Badge / Tag）
+
+标签是高频偏差元素，涉及背景色、圆角、字号、内边距的组合，任一偏差都会在截图中明显可见：
+
+| 标签类型 | 精调维度 | 已审计偏差案例 |
+|----------|---------|---------------|
+| 状态 Badge（跟/弃） | 背景渐变、font-size、min-width、height、border-radius | 弃 badge radius 10rpx→应为 12rpx |
+| 超期标签（超期>7天/≤7天） | 背景透明度、padding、border-radius、文字色 | radius 6rpx→应为 8rpx |
+| 潜力标签（高频/高客单/高余额） | 背景色、文字色、font-weight | 已正确迁移 |
+| 高消费标签 | `bg-warning/10` + `text-warning` + `font-bold` | 已正确迁移 |
+| 板块标题标签（Emoji + 文字） | Emoji 渲染、font-size、间距 | 板块 Emoji 📈💳💰🧾📤🎱 已正确 |
+
+标签精调规则：
+- 背景色优先查 `docs/h5_ui/design-tokens.json`，禁止使用非标准色值
+- `border-radius` 是标签最常见偏差（±2rpx），必须逐个核对
+- `padding` 注意 H5 Tailwind 的 `px-1.5 py-0.5` 换算（×2×0.875）
+- 渐变背景标签（如跟/弃 badge）的渐变方向和双色值必须精确
+
+#### 2.7.4 组合元素（图标+文字+背景）
+
+多个基础元素组合成的复合 UI 单元，整体偏差会被放大：
+
+| 组合元素 | 构成 | 精调关注点 |
+|----------|------|-----------|
+| 筛选按钮 | 文字 + 下拉箭头 + 背景 + 圆角 | 整体高度、内边距、箭头与文字间距 |
+| 环比指标 | 数值 + 箭头(↑↓) + 百分比 + 颜色 | 上升色 #e34d59 / 下降色 #00a870、font-size |
+| 确认收入横条 | 标签 + 金额 + 半透明背景 | `bg-white/10` 透明度、padding、border-radius |
+| 迷你柱状图 | 柱条 + 数字 + 标签 | 柱条高度/gap/圆角/透明度渐变、数字 font-size |
+| 助教服务行 | 头像 + 姓名 + 分隔符 + 跟/弃 badge | 分隔符颜色/间距、badge 与文字对齐 |
+| AI 悬浮按钮 | 图标 + 渐变背景 + 圆角 + 阴影 | 整体 size、border-radius、渐变色 |
+
+组合元素精调策略：先确认整体布局（flex 方向、对齐方式）正确，再逐个子元素微调。
+
+## 3. 两阶段收敛流程
+
+### 3.1 流程图
+
+```
+获取双端截图
+    ↓
+image_compare 对比 → 初始差异率
+    ↓
+首轮审计报告（截图 + H5 源码 + MP 源码 三方对照）
+    ↓
+┌─ 差异率 > 10% ──→ 阶段一：结构级修正（每轮 2-5 处）
+│                      ↓ 循环直到 ≤ 10%
+├─ 差异率 5%~10% ─→ 阶段二：像素级精调（每轮 1-3 处）
+│                      ↓ 循环直到 < 5%
+├─ 差异率 < 5% ───→ ✅ 通过
+└─ > 15% 且无法收敛 → 🔄 触发重写
+```
+
+### 3.2 首轮审计报告（强制）
+
+第一轮对比完成后，必须同时读取 H5 源码（HTML + 内联 CSS 的 Tailwind 类名和 `<style>` 块）和 MP 源码（WXML + WXSS），结合 diff 截图三方对照，产出一份完整的审计报告。此报告是后续所有修改的指导依据。
+
+审计报告格式包含：
+
+| 章节 | 内容 | 数据来源 |
+|------|------|---------|
+| A. 结构对照 | 页面区域结构是否完整、顺序是否一致 | diff 截图 + H5 HTML 结构 |
+| B. CSS 风险点 | 不支持的 CSS 特性（`::after` 复杂场景、`clip-path`、`backdrop-filter` 等） | H5 `<style>` 块 |
+| C. 关键样式映射 | 逐元素核对：Tailwind 类名 → computed 值 → WXSS 现值 → 是否一致 | H5 源码 + MP WXSS |
+| D. 图标处理 | 每个 SVG/图标的迁移决策和当前状态 | H5 源码 + MP WXML |
+| E. 偏差清单 | 所有 ⚠️ 偏差项汇总，按优先级排序 | C/D 节中标记的偏差 |
+
+审计报告输出到 `docs/h5_ui/compare/<page>/audit.md`。
+
+关键原则：
+- 不能只看 diff 图猜测问题，必须回溯到 H5 源码确认正确值
+- Tailwind 类名是唯一可信的样式来源（不是肉眼估算）
+- 每个偏差项必须记录：H5 值（含 Tailwind 类名）→ 换算后的 rpx 值 → MP 现值 → 差异
+- 审计报告完成后，阶段一/二的修正严格按报告中的偏差清单执行
+
+### 3.3 阶段一：结构级修正
+
+目标：消除明显的视觉差异，将差异率从 >10% 降到 ≤10%。
+
+修正重点（按优先级）：
+1. 区域缺失或顺序错误
+2. 整块背景色/渐变色不匹配
+3. 字号明显偏差（≥4rpx）
+4. 间距明显偏差（≥4rpx）
+
+操作模式：
+- 按审计报告偏差清单逐项修正，不靠肉眼猜测
+- 对照 H5 源码 Tailwind 类名 + `docs/h5_ui/design-tokens.json` 确认正确值
+- 修改 WXSS → 重新截图 → 重新对比
+
+### 3.4 阶段二：像素级精调
+
+目标：消除细微差异，将差异率从 5%~10% 降到 <5%。
+
+修正重点（按优先级）：
+1. 小边距偏差（padding/margin/gap ±2rpx，如卡片 30→28rpx、列表容器 24→28rpx、分隔符 margin 6→10rpx）
+2. 圆角（border-radius）偏差（±2rpx，如标签 6→8rpx、卡片 28→32rpx）
+3. 颜色色值微调（灰阶偏差如 #c5c5c5→#a6a6a6、透明度差 0.1）
+4. 行高（line-height）缺失或偏差、字重（font-weight）微调（如 600→500）
+5. 阴影（box-shadow）参数微调
+
+操作模式：
+- 使用 image_compare 精确定位差异像素区域
+- 参考 computed-styles.json（如有）或 H5 源码精确值
+- 每次只改 1-3 处，验证不引入新差异
+
+### 3.5 收敛停滞处理
+
+当差异率连续 3 轮未下降超过 1% 时：
+1. 分析剩余差异是否为不可消除的结构性差异（字体渲染、抗锯齿、头部区域）
+2. 若是 → 标注为可接受差异，记录到 report.md，停止该区域精调
+3. 若否 → 尝试不同修正策略（如换用 flex 布局替代绝对定位）
+
+## 4. 修改优先级规则（经验提炼）
+
+基于 board-finance（17 项偏差）、board-coach（17 项偏差）、board-customer（42 项偏差）的实际审计经验，提炼出以下规则：
+
+### 4.1 高频偏差类型
+
+| 偏差类型 | 出现频率 | 典型案例 | 修正策略 |
+|----------|---------|---------|---------|
+| font-size 偏差 | 极高 | Tab 26rpx→24rpx, 金额 28rpx→32rpx | 查 Tailwind 类名换算 |
+| border-radius 偏差 | 高 | 标签 6rpx→8rpx, 卡片 28rpx→32rpx, 头像 14rpx→24rpx | 查 `design-tokens.json` |
+| padding/margin 偏差 | 高 | 卡片 30rpx→28rpx, 列表容器 24rpx→28rpx | 查 Tailwind 类名换算 |
+| line-height 缺失 | 中 | Tab 文字未写 line-height | 补 `line-height: 36rpx` |
+| 颜色偏差 | 中 | 灰色 #c5c5c5→#a6a6a6, 边框 #eeeeee→#e7e7e7 | 查 `design-tokens.json` 灰阶 |
+| font-weight 偏差 | 低 | 数据行 600→500 | 查 Tailwind 类名 |
+| flex 比例偏差 | 低 | 筛选按钮 1.8→2 | 查 H5 源码 |
+
+### 4.2 跨页面共性偏差
+
+以下偏差在三个看板页面中重复出现，修正一个页面后应同步检查其他页面：
+
+- Tab 导航：font-size 26→24rpx, padding 24→22rpx, line-height 缺失→36rpx
+- 筛选栏内层：border-radius 14→16rpx（或 32rpx，取决于页面）
+- 卡片：padding-top/bottom 30→28rpx, margin-bottom 20→22rpx
+- 标签：border-radius 6→8rpx
+
+### 4.3 不修复的差异
+
+以下差异属于结构性差异或设计决策差异，不计入差异率：
+- 头部区域（H5 safe-area-top vs MP 状态栏+胶囊）
+- 字体渲染差异（H5 Noto Sans SC vs MP 系统字体）
+- 环比箭头（H5 SVG vs MP 文字 ↑↓，已确认可接受）
+- AI 浮动按钮区域（H5 已隐藏，MP 端如存在则忽略该区域差异）
+
+## 5. 页面清单与截图参数
+
+所有页面统一使用固定 600px 步长滚动截图，不依赖锚点。步数基于 Playwright 实测的 `maxScroll = scrollHeight - viewportHeight`，公式：`N = floor(maxScroll / 600) + 1`；`maxScroll ≤ 10` 视为单屏（N=1）。
+
+> 以下数据基于 2026-03-10 Playwright 实测（430×752 视口，DPR=1.5，展开所有折叠区域），验证脚本 `scripts/ops/_verify_step_counts.py`，原始数据 `export/SYSTEM/REPORTS/h5_page_heights/step_counts_verified.json`。
+
+| # | 页面 | scrollHeight | maxScroll | 实测步数 | scrollTop 序列 | 主要内容区域 |
+|---|------|-------------|-----------|---------|---------------|-------------|
+| 1 | board-finance | 5600 | 4848 | 10 | 0,600,...,4800,4848 | 经营一览 / 预收资产 / 应计收入确认 / 现金流入 / 现金流出 / 助教分析 |
+| 2 | board-coach | 754 | 2 | 1★ | 0 | 助教卡片列表（×4 排序维度：perf/salary/sv/task） |
+| 3 | board-customer | 752 | 0 | 1 | 0 | 客户卡片列表（×8 客户维度：recall/potential/balance/recharge/recent/spend60/freq60/loyal） |
+| 4 | task-detail | 2995 | 2243 | 5 | 0,600,1200,1800,2243 | Banner / 关系 / 建议 / 线索 / 备注 |
+| 5 | task-detail-callback | 2397 | 1645 | 4 | 0,600,1200,1645 | 同上（teal 主题） |
+| 6 | task-detail-priority | 2389 | 1637 | 4 | 0,600,1200,1637 | 同上（orange 主题） |
+| 7 | task-detail-relationship | 2275 | 1523 | 4 | 0,600,1200,1523 | 同上（pink 主题） |
+| 8 | coach-detail | 2918 | 2166 | 5 | 0,600,1200,1800,2166 | Banner / 绩效概览 / 收入明细 / 前10客户 |
+| 9 | customer-detail | 3070 | 2318 | 5 | 0,600,1200,1800,2318 | Banner / AI洞察 / 线索 / 任务 / 最爱助教 / 消费记录 |
+| 10 | performance | 7705 | 6953 | 13 | 0,600,...,6600,6953 | Banner / 收入 / 本月业绩 / 上月收入 / 新客 / 常客（最长页面） |
+| 11 | task-list | 1428 | 676 | 3 | 0,600,676 | Banner业绩卡 / 任务列表 |
+| 12 | my-profile | 752 | 0 | 1 | 0 | 整页（单屏） |
+| 13 | customer-service-records | 961 | 209 | 2 | 0,209 | Banner统计 / 记录列表 |
+| 14 | performance-records | 2677 | 1925 | 5 | 0,600,1200,1800,1925 | Banner / 统计概览 / 记录列表 |
+| 15 | chat | 1061 | 309 | 2 | 0,309 | 对话区 / 输入区 |
+| 16 | chat-history | 752 | 0 | 1 | 0 | 整页（单屏） |
+| 17 | notes | 1709 | 957 | 3 | 0,600,957 | 导航 / 备注列表 |
+
+> ★ board-coach maxScroll=2px，按实用主义规则（≤10px）视为单屏。
+> 单屏页面（board-coach、board-customer、my-profile、chat-history）只需 step-0 一张截图。多维度页面需切换维度后分别截图：board-coach ×4 排序维度（通过排序筛选下拉切换）、board-customer ×8 客户维度（通过维度筛选下拉切换）。
+
+### 5.1 对照处理单元计算
+
+对照处理单元 = 每页实测步数 × 维度数（无维度的页面维度数=1）。数据来源：2026-03-10 Playwright 实测（`scripts/ops/_verify_step_counts.py`）。
+
+| 页面 | 步数 | 维度数 | 单元数 |
+|------|------|--------|--------|
+| board-finance | 10 | 1 | 10 |
+| board-coach | 1★ | 4 | 4 |
+| board-customer | 1 | 8 | 8 |
+| task-detail | 5 | 1 | 5 |
+| task-detail-callback | 4 | 1 | 4 |
+| task-detail-priority | 4 | 1 | 4 |
+| task-detail-relationship | 4 | 1 | 4 |
+| coach-detail | 5 | 1 | 5 |
+| customer-detail | 5 | 1 | 5 |
+| performance | 13 | 1 | 13 |
+| task-list | 3 | 1 | 3 |
+| my-profile | 1 | 1 | 1 |
+| customer-service-records | 2 | 1 | 2 |
+| performance-records | 5 | 1 | 5 |
+| chat | 2 | 1 | 2 |
+| chat-history | 1 | 1 | 1 |
+| notes | 3 | 1 | 3 |
+| **合计** | | | **79** |
+
+> ★ board-coach maxScroll=2px，按实用主义规则（≤10px）视为单屏。
+
+## 6. 产出物归档结构
+
+所有截图、diff、审计报告统一归入 `docs/h5_ui/compare/`，按页面分子目录。
+
+```
+docs/h5_ui/compare/
+├── board-finance/
+│   ├── h5--step-0.png          # H5 截图（645×1128）
+│   ├── h5--step-600.png
+│   ├── mp--step-0.png          # MP 截图（645×1128）
+│   ├── mp--step-600.png
+│   ├── diff--step-0.png        # 像素对比 diff 图
+│   ├── diff--step-600.png
+│   ├── report.md               # 差异率汇总 + 对比分析
+│   └── audit.md                # 三方对照审计报告
+├── board-coach/
+│   ├── perf/                   # 多维度页面按排序维度分子目录
+│   │   ├── h5--step-0.png
+│   │   ├── mp--step-0.png
+│   │   └── diff--step-0.png
+│   ├── salary/
+│   ├── sv/
+│   ├── task/
+│   ├── report.md
+│   └── audit.md
+├── board-customer/
+│   ├── recall/                 # 8 种客户维度各一个子目录
+│   ├── potential/
+│   ├── balance/
+│   ├── recharge/
+│   ├── recent/
+│   ├── spend60/
+│   ├── freq60/
+│   ├── loyal/
+│   ├── report.md
+│   └── audit.md
+├── my-profile/                 # 单屏页面
+│   ├── h5--step-0.png
+│   ├── mp--step-0.png
+│   ├── diff--step-0.png
+│   ├── report.md
+│   └── audit.md
+...（17 个页面各一个子目录）
+```
+
+文件命名规则：
+- `h5--step-<scrollTop>.png` / `mp--step-<scrollTop>.png` / `diff--step-<scrollTop>.png`
+- scrollTop 值：0, 600, 1200, 1800 ...
+- 文件名不含页面名（已在子目录中）
+- 单屏页面只有 `--step-0` 一组
+- 多维度页面（board-coach ×4 排序维度、board-customer ×8 客户维度）按维度分子目录
+
+废弃目录（不再使用）：
+- `docs/h5_ui/screenshots/` → 已清理
+- `docs/h5_ui/mp-screenshots/` → 已清理
+- `docs/h5_ui/h5-segments/` → 已清理
+- `docs/h5_ui/diffs/` → 已清理
+- `docs/h5_ui/anchors/` → 已清理
+- `docs/h5_ui/analysis/` → 审计报告迁入各页面子目录
+
+## 7. 风险与依赖
+
+### 7.1 外部依赖
+
+| 依赖项 | 风险等级 | 说明 | Fallback |
+|--------|---------|------|----------|
+| 微信开发者工具 MCP 连接 | 中 | MCP 连接偶尔断开（超时/端口占用），需重连 | `reconnect_devtools` 重连；若反复失败，手动截图后放入 `compare/<page>/` |
+| Playwright 浏览器 | 低 | 首次运行需 `playwright install chromium` | `uv run playwright install chromium` |
+| image_compare MCP | 低 | MCP server 未启动时 compare_images 不可用 | 使用 `anchor_compare.py compare` 命令行替代 |
+
+### 7.2 已知限制
+
+- 字体渲染引擎差异（Chromium vs 微信 webview）可能引入约 1-2% 的固有差异率
+- 字体渲染差异（H5 Noto Sans SC vs MP 系统字体）不可消除，属于可接受差异
+- 微信开发者工具截图不支持指定 DPR，实际 DPR 取决于模拟器设置（当前 iPhone 15 Pro Max 有效 DPR=1.5）
+- board-coach/board-customer 的多维度截图验证（4/8 种维度）需要 Mock 数据支持不同维度的展示
+
+## 8. 页面执行顺序
+
+### 8.0 前置任务：TS 零诊断基线检查与共性偏差批量修复
+
+在进入 A 批次之前，需完成两项前置工作：
+
+#### 8.0.1 TS 零诊断基线检查
+
+对 17 个页面的 `.ts` 文件运行 `getDiagnostics`，确认全部为零诊断。这是 Step 0-5 结构迁移的交付基线，如果此时已有 TS 错误，必须先修复再进入像素精调，否则精调过程中引入的新错误会与历史错误混淆。
+
+#### 8.0.2 跨页面共性偏差批量修复
+
+基于 4.2 节已识别的跨页面共性偏差，在 `app.wxss` 或共享组件样式中统一修正：
+
+| 共性偏差 | 涉及页面 | 修正方案 |
+|----------|---------|---------|
+| Tab 导航 font-size 26→24rpx | board-finance/coach/customer | 统一修正各页面 Tab 样式 |
+| Tab 导航 padding 24→22rpx | board-finance/coach/customer | 同上 |
+| Tab 导航 line-height 缺失→36rpx | board-finance/coach/customer | 同上 |
+| 筛选栏内层 border-radius 14→16rpx | board-finance/coach/customer | 统一修正筛选栏样式 |
+| 卡片 padding-top/bottom 30→28rpx | board-finance/coach/customer | 统一修正卡片容器样式 |
+| 标签 border-radius 6→8rpx | board-finance/coach/customer | 统一修正标签样式 |
+
+先批量修复共性偏差，再进入各页面的个性化精调，可显著减少重复工作量。修复后需对三个看板页面快速截图验证，确认共性修正未引入新问题。
+
+### 8.1 批次执行顺序
+
+按原批次顺序，简单页面优先积累经验：
+
+| 批次 | 页面 | 预估复杂度 | 对照单元总数 |
+|------|------|-----------|------------|
+| A | board-finance, board-coach, board-customer | 高 | 22 |
+| B | task-list, my-profile | 低-中 | 4 |
+| C | task-detail（主页面 5 单元）+ 3 变体（各 4 单元，仅验证主题色） | 中 | 17 |
+| D | coach-detail, customer-detail, customer-service-records | 中 | 12 |
+| E | performance, performance-records | 高 | 18 |
+| F | chat, chat-history | 低 | 3 |
+| G | notes | 低 | 3 |
+| | **合计** | | **79** |