# 需求文档：H5 → 微信小程序像素精调

## 简介

本 spec 承接 `h5-miniprogram-migration` 的 Step 0-5 结构迁移成果。17 个页面已全部完成结构迁移、编译验证和结构还原验证。本 spec 专注于 Step 6-7：像素级视觉还原与验收签收。

核心单位是「对照处理单元」——每个页面被分解为多个可独立截图、独立对比、独立修正的最小区域段。17 个页面共分解为 79 个对照处理单元（详见 design.md §5.1，基于 2026-03-10 Playwright 实测校准）。

权威参考：
- 迁移规则：`docs/prd/MIGRATION-PLAYBOOK.md`
- 样式标准：`docs/h5_ui/design-tokens.json`（颜色、字号、圆角、阴影的标准值）
- 工具链：`scripts/ops/anchor_compare.py`（固定步长截图 + 逐屏对比）

## 术语表

| 术语 | 定义 |
|------|------|
| 对照处理单元 | 一个页面内可独立截图、独立对比、独立修正的最小区域段（如"经营一览"板块、"助教卡片列表"区域） |
| 差异率 | pixelmatch / image_compare 输出的像素差异百分比，仅针对内容区域计算（头部导航栏/状态栏不计入） |
| 结构级修正 | 差异率 > 10% 时的修正阶段，修复明显的布局/颜色/缺失问题 |
| 像素级精调 | 差异率 5%~10% 时的精调阶段，微调 padding/font-size/color 等 |
| 固定步长 | 600px 逻辑像素为一步，两端使用完全相同的 scrollTop 序列逐屏截图 |
| 双端截图 | 同一页面的 H5 截图（DPR=1.5, 645×1128）和 MP 截图（DPR=1.5, 645×1128），两端参数完全一致，无需缩放 |

## 需求

### 需求 1：页面分解与对照处理单元建立

**用户故事：** 作为迁移执行者，我希望每个页面被分解为可独立处理的最小对照单元，以便逐屏精确对比和修正。

#### 验收标准

1. THE 分解流程 SHALL 对每个页面执行以下步骤：分析 H5 原型结构 → 识别语义区域 → 按固定 600px 步长计算截图屏数 → 建立对照处理单元清单
2. THE 对照处理单元 SHALL 满足以下条件：每屏为一个对照单元（645×1128 像素），语义完整性由审计报告人工确认
3. THE 步数计算 SHALL 基于 Playwright 实测的 `maxScroll = scrollHeight - viewportHeight`：`N = floor(maxScroll / 600) + 1`；`maxScroll ≤ 10` 的页面视为单屏（N=1）
4. WHEN 页面为多维度页面（如 board-coach ×4 排序维度、board-customer ×8 客户维度）时，THE 分解流程 SHALL 按维度分子目录，每个维度独立截图和对比。维度切换通过页面筛选栏下拉操作完成（board-coach 通过排序筛选切换 perf/salary/sv/task 四种卡片模板；board-customer 通过维度筛选切换 recall/potential/balance/recharge/recent/spend60/freq60/loyal 八种卡片模板）
5. THE 分解结果 SHALL 输出为每页一份的对照单元清单，包含：单元编号（step-N）、scrollTop 值、预估复杂度

### 需求 2：双端截图标准

**用户故事：** 作为迁移执行者，我希望 H5 和 MP 的截图在尺寸、视口、DPR 上严格统一，以确保像素对比结果有意义。

#### 验收标准

1. THE H5 截图 SHALL 使用以下参数：viewport 430×752, DPR=1.5, 输出 645×1128；通过 Playwright 截取（Live Server `http://localhost:5500`），等待 Tailwind CDN JIT 渲染 1500ms
2. THE MP 截图 SHALL 使用以下参数：viewport 430×752, DPR=1.5（MCP 有效 DPR）, 输出 645×1128；通过微信开发者工具 MCP 截取。两端输出尺寸完全一致，无需任何缩放
3. WHEN 对比页面时，THE 截图流程 SHALL 使用固定 600px 步长滚动截图，两端使用完全相同的 scrollTop 序列（0, 600, 1200, ...），不依赖锚点
4. THE H5 截图前 SHALL 隐藏底部浮动元素：`#bottomNav`（64px fixed 底部导航）和 `.ai-float-btn-container`（56px 浮动按钮），通过 JS 设置 `display: none`。MP 端原生 tabBar 不在截图中，无需处理
5. THE 头部区域（H5 safe-area-top ~46px / MP 状态栏+胶囊 ~88px）SHALL 不计入像素差异率，属结构性差异
6. WHEN 截图流程中发现 H5 页面或 MP 页面无法正常渲染时，THE 流程 SHALL 暂停并报告问题，禁止使用异常截图进行对比
7. WHEN MP 端页面高度与 H5 不一致时，THE 截图流程 SHALL 先截双端 step-0（首屏）确认基线，再截 step-600（第二屏）校准双端高度差异，之后逐屏推进。每屏截图前读取 MP 端实际 scrollTop，确认到达预期位置

### 需求 3：两阶段收敛流程

**用户故事：** 作为迁移执行者，我希望像素精调按差异率分阶段处理——先修大问题再调细节——以高效收敛到达标标准。

#### 验收标准

1. THE 收敛流程 SHALL 分为两个阶段：
   - 阶段一（结构级修正）：差异率 > 10%，每轮修复 2-5 处明显差异（布局/颜色/缺失/字号）
   - 阶段二（像素级精调）：差异率 5%~10%，每轮修复 1-3 处精细差异（padding ±2rpx / line-height / border-radius / 色值）
2. THE 达标标准 SHALL 为：差异率 < 5% 标记通过；差异率 > 15% 且多轮无法收敛则触发重写
3. WHEN 进入每轮修正时，THE 流程 SHALL 先截图对比 → 肉眼审查 diff 图 → 定位差异区域 → 修改 WXSS/WXML → 重新截图验证
4. THE 每轮修正 SHALL 控制修改范围（阶段一 2-5 处、阶段二 1-3 处），避免一次改太多难以定位效果
5. WHEN 差异率在连续 3 轮内未下降超过 1% 时，THE 流程 SHALL 评估是否为结构性差异（如头部区域、字体渲染差异），若是则标注为可接受差异并停止该区域的精调

### 需求 4：分析报告持久化

**用户故事：** 作为项目管理者，我希望每个页面的对比分析结果持久化为 MD 文件，以便追溯和复查。

#### 验收标准

1. THE 每个页面 SHALL 在 `docs/h5_ui/compare/<page>/report.md` 输出对比分析报告
2. THE 报告 SHALL 包含：初始差异率、每轮修正记录（轮次/修改内容/修正后差异率）、最终差异率、遗留的可接受差异说明
3. THE 报告 SHALL 在每轮修正后更新，记录收敛过程
4. THE 截图产出物 SHALL 统一归入 `docs/h5_ui/compare/<page>/`，按页面分子目录：
   - H5 截图：`h5--step-<scrollTop>.png`
   - MP 截图：`mp--step-<scrollTop>.png`
   - Diff 图：`diff--step-<scrollTop>.png`
   - 审计报告：`audit.md`
   - 对比报告：`report.md`
   - 多维度页面按维度再分子目录（如 `board-coach/perf/`）
5. THE 每轮新截图 SHALL 覆盖上一轮同名文件，不保留历史版本（依赖 git 追溯）

### 需求 5：修改优先级规则

**用户故事：** 作为迁移执行者，我希望有明确的修改优先级指导，以便在每轮修正中优先处理影响最大的差异。

#### 验收标准

1. THE 修改优先级 SHALL 按以下顺序排列（从高到低）：
   - P0：区域缺失或顺序错误（结构性问题）
   - P1：整块背景色/渐变色不匹配
   - P2：字号（font-size）明显偏差（≥4rpx）
   - P3：间距（padding/margin/gap）明显偏差（≥4rpx）
   - P4：圆角（border-radius）偏差
   - P5：颜色色值微调（灰阶偏差、透明度）
   - P6：行高（line-height）/ 字重（font-weight）微调
   - P7：阴影（box-shadow）参数微调
2. WHEN 阶段一修正时，THE 流程 SHALL 优先处理 P0-P3 级别的差异
3. WHEN 阶段二精调时，THE 流程 SHALL 处理 P4-P7 级别的差异
4. THE 修改 SHALL 优先使用 `docs/h5_ui/design-tokens.json` 中定义的标准值，禁止使用非标准灰色（#333/#666/#999 等）
5. THE 修改 SHALL 优先使用 flex/盒模型的确定性方案，禁止使用"碰运气"的魔法数

### 需求 6：验收签收标准

**用户故事：** 作为项目管理者，我希望每个页面有明确的验收标准，以确保交付质量一致。

#### 验收标准

1. THE 单页验收 SHALL 满足以下条件：
   - 内容区差异率 < 5%
   - TS 编译零诊断
   - 所有对照处理单元均已逐屏对比
   - report.md 已归档且记录完整
2. THE 批次验收 SHALL 满足以下条件：
   - 批次内所有页面单页验收通过
   - 共享组件在批次内所有页面中表现一致
   - 所有截图和 diff 图已按目录归档
3. THE 全局验收 SHALL 满足以下条件：
   - 17 个页面（79 个对照处理单元）全部单页验收通过
   - 差异率汇总表已输出（页面名 / 初始差异率 / 最终差异率 / 修正轮数）
   - TS 编译零诊断复查通过

### 需求 7：工具链使用规范

**用户故事：** 作为迁移执行者，我希望工具链的使用有明确规范，以确保截图和对比结果的一致性和可复现性。

#### 验收标准

1. THE H5 截图 SHALL 统一通过 `scripts/ops/anchor_compare.py extract-h5 <page>` 获取（固定 600px 步长滚动截图，viewport 430×752, DPR=1.5；通过 Live Server `http://localhost:5500` 访问页面）
2. THE MP 截图 SHALL 通过微信开发者工具 MCP 截取，按相同的 scrollTop 序列（0, 600, 1200, ...）逐屏截图
3. THE 像素对比 SHALL 使用 `image_compare` power 的 `compare_images` 工具，或 `anchor_compare.py compare <page>` 命令
4. WHEN 页面需要逐屏对比时，THE 流程 SHALL 使用 anchor_compare.py 的两步流程：`extract-h5` → `compare`（MP 截图通过 MCP 工具独立获取）
5. THE 工具链输出 SHALL 统一存放到 `docs/h5_ui/compare/<page>/`（见需求 4），禁止散放在项目根目录或临时位置

### 需求 8：风险与异常处理

**用户故事：** 作为迁移执行者，我希望在工具链故障或环境异常时有明确的 Fallback 方案，以避免流程阻塞。

#### 验收标准

1. WHEN 微信开发者工具 MCP 连接断开时，THE 流程 SHALL 先尝试 `reconnect_devtools` 重连，若连续 3 次失败则暂停该页面任务并报告问题
2. WHEN Live Server 端口 5500 被占用时，THE 流程 SHALL 检查端口占用并提示用户释放端口，不得使用其他端口截图（避免 URL 不一致）
3. WHEN image_compare MCP 不可用时，THE 流程 SHALL 使用 `anchor_compare.py compare` 命令行作为替代
4. WHEN 某页面差异率 > 15% 且连续 5 轮无法收敛时，THE 流程 SHALL 暂停并输出问题分析报告，由用户决定是否触发重写
5. THE 每个批次任务 SHALL 在开始前验证页面 TS 零诊断基线，如有编译错误则先修复再进入精调