499 lines
26 KiB
Markdown
499 lines
26 KiB
Markdown
# 技术设计文档：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** |
|