
## 二、测量工具：measure_gaps.py

路径：`scripts/ops/measure_gaps.py`

### 2.1 基本用法

```bash
# 测量页面内所有 .task-card 元素的尺寸和间距
uv run python scripts/ops/measure_gaps.py task-list --selectors ".task-card"

# 测量多个选择器（按 DOM 顺序，计算相邻间距）
uv run python scripts/ops/measure_gaps.py board-finance --selectors ".summary-header" ".summary-content" ".grid-cols-3"

# 指定两个元素的直接间距
uv run python scripts/ops/measure_gaps.py task-list --pairs ".sticky-header" ".task-card:first-child"

# 页面中下方元素（需 scrollTop）
uv run python scripts/ops/measure_gaps.py performance --selectors ".perf-section" --scroll 1200
```

### 2.2 输出解读

输出包含：
- 元素尺寸表：top_px, h_px, paddingT/B, marginT/B, gap, fontSize, lineHeight, h_rpx
- 相邻元素垂直间距表：gap_px 和 gap_rpx
- audit.md 可直接粘贴的 Markdown 表格

### 2.3 常用 CSS 选择器快查

| 元素类型 | 选择器示例 |
|---|---|
| 页面内边距容器 | `.px-4`, `.px-6`, `[class*="px-"]` |
| 卡片 | `.task-card`, `[class*="card"]` |
| 列表项间距 | `.list-item`, `li`, `[class*="item"]` |
| Sticky 头部 | `.sticky`, `.filter-bar`, `[class*="sticky"]` |
| Banner | `.banner-bg`, `[class*="banner"]` |
| 标签/徽章 | `.tag`, `.badge`, `[class*="tag"]` |

---

## 三、测量步骤（每页标准流程）

### 3.1 H5 侧测量

1. 确定要测量的元素（审计代理提供偏差元素列表）
2. 确定 CSS 选择器（参照 2.3 快查表）
3. 运行 measure_gaps.py，记录输出的 px 和 rpx 尺寸
4. 如果元素在页面中下方，加上 `--scroll 目标scrollTop`

### 3.2 MP 側反向验证

1. 在 MP 页面 WXML 中定位对应元素
2. 使用 `SelectorQuery`：
   ```js
   const query = wx.createSelectorQuery();
   query.select('.task-card').boundingClientRect(res => {
     console.log('top:', res.top, 'height:', res.height);
   }).exec();
   ```
3. 比较 MP 实测高度（px）与理论 rpx 下的预期实际宣染尺寸
4. 差异 > 4rpx 则标记为 P3 偏差，需要修正

### 3.3 图像反推验证（处理截图偏差时使用）

当 diff 图显示某个元素位置偏程时，用截图像素反推实际间距：

```
实际间距(px) = diff 图中偏程像素数 ÷ DPR
DPR = 1.5
示例：diff 图中元素 A 比 H5 下小 9 像素
      实际偏差 = 9 / 1.5 = 6px = 10rpx
      应描小 WXSS 中对应 margin/padding 10rpx
```

---

## 四、输出格式：audit.md 间距表

将 measure_gaps.py 输出的 Markdown 表格直接填入 audit.md 的 F 项：

```markdown
## G. 间距测量表

| 元素 | H5 top_px | H5 高度px | 预期 rpx | MP 实测 rpx | 差异 | 处理 |
|---|---|---|---|---|---|---|
| .task-card | 88.0 | 84.0 | 146rpx | 140rpx | -6rpx | 将 height 改为 146rpx |
| .task-card 间距 | - | - | 14rpx | 12rpx | -2rpx | margin-bottom 改为 14rpx |
| .sticky-header | 0.0 | 44.0 | 76rpx | 76rpx | 0 | 匹配 ✓ |
```

---

## 五、调用时机

| 场景 | 调用方 | 输出用途 |
|---|---|---|
| \u00a70.8 迁移前预计算 | 主代理在 step-0 审计前主动调用 | 填入 WXSS 的初始内边距/外边距/gap 尺寸 |
| 审计代理发现间距偏差 | 审计代理调用 | 补充 audit.md G 项 |
| 修正代理需要确认尺寸 | 修正代理调用 | 确认正确 rpx 尺寸再写入 WXSS |
| 差异率无法下降 | 修正代理调用 | 精确定位剩余偏差来源 |
