# 截图+审计+修正+验证 执行手册

> 合并原 screenshot.md / audit.md / fix.md / verify.md 四个文件。
> 硬性规则（rpx、标签映射、颜色）已在 always-on steering `mp-h5-rules.md` 中，此处不重复。

---

## 一、截图

### H5 截图（Playwright Power → `browser_run_code`）

```javascript
async (page) => {
  const browser = page.context().browser();
  const ctx = await browser.newContext({
    viewport: { width: 430, height: 752 },
    deviceScaleFactor: 1.5
  });
  const p = await ctx.newPage();
  await p.goto('file:///C:/NeoZQYY/docs/h5_ui/pages/<page>.html',
    { waitUntil: 'domcontentloaded', timeout: 30000 });
  await p.waitForTimeout(3000); // Tailwind CDN JIT

  await p.evaluate(() => {
    const nav = document.getElementById('bottomNav');
    if (nav) nav.style.display = 'none';
    const safeArea = document.querySelector('.safe-area-top');
    if (safeArea) safeArea.style.paddingTop = '0px';
    const aiFab = document.querySelector('.ai-float-btn-container');
    if (aiFab) aiFab.style.display = 'none';
    const s = document.createElement('style');
    s.textContent = '::-webkit-scrollbar{display:none!important}*{scrollbar-width:none!important}';
    document.head.appendChild(s);
  });

  await p.evaluate((scrollTop) => window.scrollTo(0, scrollTop), <scrollTop>);
  await p.waitForTimeout(300);
  await p.screenshot({
    path: 'C:/NeoZQYY/docs/h5_ui/compare/<page>/h5--step-<scrollTop>.png',
    type: 'png', scale: 'device'
  });
  await ctx.close();
  return { saved: true };
}
```

步数 ≥3 的页面可在同一 context 中循环截图。

### MP 截图（weixin-devtools Power）

```
1. relaunch → url: "/pages/<page>/<page>"（禁止 switch_tab/navigate_to）
2. waitFor → delay: 2000
3. 前置：WXML 中 dev-fab/ai-float-button 加 wx:if="{{false}}"
4. 滚动到目标 scrollTop
5. screenshot
6. 模式 B 页面裁剪头部 96px（PIL: img.crop((0, 96, 645, 1224))）
```

### 滚动策略

标准：直接使用 H5 相同 scrollTop。

窗口错位判断：上下大块红绿(>200px)=整体偏移→锚点对齐法 | 散布多区域=样式差异→继续修正 | 底部全黑/白>100px=内容更短→锚点对齐法

锚点对齐法：确定锚点元素 → `wx.createSelectorQuery` 获取绝对 top → `MP_target = absoluteTop - sticky高度` → 滚动到该位置

### 多维度切换

board-coach/customer：获取快照 → 点击筛选下拉 → 选择维度 → 等待刷新
board-finance：H5 `toggleCompare()` / MP 点击环比开关

### 截图后行为（严格遵守）

- 直接进入审计流程，禁止用 PIL/pixelmatch/image-compare 检查尺寸或做像素 diff
- 截图参数已固定，尺寸必然正确

---

## 二、审计

### 三阶段流程

```
阶段 0：结构拆解（自顶向下）
  H5 源码 → 首层容器 → 递归到叶子 → 建立 H5↔MP 映射表
  结构完整性校验（缺失/多余/顺序错误 → P0）

阶段 1：逐级测量（自底向上）
  叶子：自身尺寸 + 样式属性
  容器：内边距 + 子元素间距 + 总尺寸
  页面级：全局内边距 + 区块间距
  工具：pixel-audit Power → readSteering("measure.md")

阶段 2：偏差审计
  逐属性对比 H5 rpx 理论值 vs MP 实测值 → 按偏差量分级
```

### 迁移前置准备（step-0 必做）

1. H5 页面结构预扫描：全局结构、CSS 风险特性、字体确认
2. MP 骨架检查：根容器、navigationBar、safe-area 移除、背景色、浮动按钮隐藏
3. mock 数据一致性预核对（不一致 = P0）
4. 多屏页面：测量 MP scrollHeight，与编排值差异 >50px 则重算序列

### 审计报告格式

产出 `docs/h5_ui/compare/<page>/audit.md`：

| 章节 | 内容 |
|------|------|
| A. 结构对照 | 区域完整性、顺序 |
| B. CSS 风险点 | 不支持的 CSS |
| C. 关键样式映射 | Tailwind→computed→WXSS 现值→是否一致 |
| D. 图标处理 | 每个图标迁移状态 |
| E. 偏差清单 | P0-P7 排序，含 H5 值→rpx→MP 现值→差异 |
| F. 复杂结构专项 | Banner/AI 图标/盖戳/inline SVG/渐变文字 |

关键原则：不能只看 diff 图猜测，必须回溯 H5 源码。Tailwind 类名是唯一可信样式来源。

---

## 三、修正

### 优先级定义

| 级别 | 类型 | 判定标准 | 阶段 |
|------|------|---------|------|
| P0 | 区域缺失/顺序错误 | 整块缺失 | 阶段一 |
| P1 | 背景色/渐变色不匹配 | 大面积色差 | 阶段一 |
| P2 | 字号明显偏差 | font-size 差 ≥4rpx | 阶段一 |
| P3 | 间距明显偏差 | padding/margin/gap 差 ≥4rpx | 阶段一 |
| P4 | 圆角偏差 | border-radius 差 ±2rpx | 阶段二 |
| P5 | 颜色微调 | 灰阶偏差、透明度差 0.1 | 阶段二 |
| P6 | 行高/字重微调 | line-height 缺失或偏差 | 阶段二 |
| P7 | 阴影微调 | box-shadow 偏差 | 阶段二 |

### 两阶段收敛

```
P0-P3 >10 → 结构级重写（每轮 3-8 处）→ 循环
P0-P3 >0  → 阶段一：结构级修正（每轮 2-5 处）→ 循环直到 P0-P3=0
P4-P7 >0  → 阶段二：像素级精调（每轮 1-3 处）→ 循环直到可接受
全部 ≤2rpx → ✅ 通过
```

### 回滚规则（强制）

每轮修正后重新截图对比，差异率上升（哪怕 0.01%）→ 立即回滚 → 逐项排查 → 每次只改一处

### 最大重试限制

差异率下降 >0.5% → 重试计数归零 | 下降 ≤0.5% → 计数+1 | 计数=5 且仍 ≥5% → 跳过（记录到 report.md）

### 首屏 >20% 触发结构重写

| 页面类型 | 重写范围 | 禁止修改 |
|---|---|---|
| 单屏 | 当前维度完整 WXML/WXSS | 其他维度 |
| 多屏(step-0) | 页面顶部结构 | step-600 以下 |
| 多屏(step-N>0) | 当前视口内节点 | 其他屏和全局样式 |
| 变体 | 与主页面差异部分 | 共享布局 |

### 修改范围约束

- 只改当前屏可见元素
- 偏差根因在前序屏 → 标注"需回退到 step-X"返回主代理
- 偏差根因是全局样式 → 标注"全局样式变更"返回主代理
- 修改后 `getDiagnostics` 确认零 TS 错误，有错误立即回退

### 收敛停滞

连续 3 轮差异率未下降 >0.5%：分析是否为不可消除结构性差异 → 是则标注可接受 → 否则缩小粒度

---

## 四、验证

### 修正后验证

```
1. 重新截图 → 重新审计
2. P0-P3=0 → ✅ 通过
3. P0-P3 减少 → 继续修正
4. P0-P3 未减少或增加 → 回滚 + 重试计数+1
5. 重试=5 → 跳过
```

### 全量回归校验（多屏页面所有屏通过后强制执行）

```
1. 逐屏截取双端截图
2. 每屏结构化审计
3. 禁止修改任何源码
4. P0-P3 增加 → 标记"回归"
5. 返回主代理决定处理方式
```

### Sticky 元素专项

step-0 完成后先检测 sticky 差异 → 优先修复（一次修复所有屏受益）→ 再继续后续步骤

### 异常处理

| 故障 | 处理 | 升级 |
|------|------|------|
| MCP 断开 | reconnect_devtools；3次失败→mcp_recompile+5s | 重编译后仍失败→暂停 |
| Playwright 不可用 | 用已有截图继续审计 | 无截图→报告主代理 |
| 截图异常(白屏) | 暂停检查页面状态 | 禁止使用异常截图 |
| MCP 超时 | 重试最多 2 次 | 3次均超时→跳过 |