553 lines
20 KiB
Markdown
553 lines
20 KiB
Markdown
# 技术设计文档：H5 → 微信小程序批量迁移
|
||
|
||
## 1. 概述
|
||
|
||
本设计文档基于 33 条需求（`requirements.md`），为 17 个 H5 原型页面迁移到微信小程序提供技术实现方案。权威参考：`docs/prd/MIGRATION-PLAYBOOK.md`。
|
||
|
||
核心约束：
|
||
- 纯前端迁移，不涉及后端 API 或数据库变更
|
||
- 输入物分两批：第一批（结构迁移 Step 1-5）、第二批（像素精调 Step 6-7）
|
||
- 迁移粒度：以"屏/交互态"为最小单位，非整页
|
||
|
||
## 2. 架构总览
|
||
|
||
### 2.1 目录结构（现有 + 新增）
|
||
|
||
```
|
||
apps/miniprogram/miniprogram/
|
||
├── app.json / app.ts / app.wxss # 全局配置与样式
|
||
├── assets/icons/ # SVG 图标（已有 + 新导出）
|
||
├── components/ # 共享组件
|
||
│ ├── ai-float-button/ # ✅ 已有
|
||
│ ├── board-tab-bar/ # ✅ 已有
|
||
│ ├── filter-dropdown/ # ✅ 已有
|
||
│ ├── heart-icon/ # ✅ 已有
|
||
│ ├── star-rating/ # ✅ 已有
|
||
│ ├── note-modal/ # ✅ 已有
|
||
│ ├── metric-card/ # ✅ 已有
|
||
│ ├── hobby-tag/ # ✅ 已有
|
||
│ ├── banner/ # ✅ 已有
|
||
│ └── dev-fab/ # ✅ 已有
|
||
├── pages/ # 页面目录（17 个迁移目标）
|
||
│ ├── board-finance/ # A 批次 - 看板
|
||
│ ├── board-coach/
|
||
│ ├── board-customer/
|
||
│ ├── task-list/ # B 批次 - 核心
|
||
│ ├── my-profile/
|
||
│ ├── task-detail/ # C 批次 - 任务详情
|
||
│ ├── task-detail-callback/
|
||
│ ├── task-detail-priority/
|
||
│ ├── task-detail-relationship/
|
||
│ ├── coach-detail/ # D 批次 - 详情
|
||
│ ├── customer-detail/
|
||
│ ├── customer-service-records/
|
||
│ ├── performance/ # E 批次 - 绩效
|
||
│ ├── performance-records/
|
||
│ ├── chat/ # F 批次 - 对话
|
||
│ ├── chat-history/
|
||
│ └── notes/ # G 批次 - 其他
|
||
└── utils/ # 工具模块
|
||
├── ai-color.ts # 🆕 AI 图标随机配色
|
||
├── format.wxs # ✅ 已有 WXS 格式化
|
||
├── request.ts # ✅ 已有 网络请求
|
||
├── router.ts # ✅ 已有 路由工具
|
||
└── ... # 其他已有工具
|
||
```
|
||
|
||
### 2.2 页面四文件结构
|
||
|
||
每个页面输出标准四文件：
|
||
|
||
```
|
||
pages/<page>/
|
||
├── <page>.wxml # 视图模板
|
||
├── <page>.wxss # 样式
|
||
├── <page>.ts # 逻辑（TypeScript）
|
||
└── <page>.json # 页面配置（usingComponents）
|
||
```
|
||
|
||
## 3. 单页迁移工作流设计
|
||
|
||
### 3.1 工作流总览（7 步 + 屏级粒度）
|
||
|
||
迁移以"屏/交互态"为最小工作单位，而非整页。每个页面的迁移流程：
|
||
|
||
```
|
||
Step 0: 页面分析（确认屏数、子页面、变种、工作量）
|
||
↓
|
||
Step 1: 输入物冻结（第一批：结构材料）
|
||
↓
|
||
Step 2: 迁移审计报告（7 项审计，不写代码）
|
||
↓
|
||
Step 3: 规则化转换（按屏逐个开发）
|
||
↓
|
||
Step 4: 编译验证（7 项检查）
|
||
↓
|
||
Step 5: 结构还原验证（9 项核对，按屏逐个验证）
|
||
↓
|
||
── 第二批输入物补充（截图 + computed-styles）──
|
||
↓
|
||
Step 6: 像素级对比（按屏逐段对比 + 微调循环）
|
||
↓
|
||
Step 7: 验收签收（12 项清单）
|
||
```
|
||
|
||
### 3.2 Step 0：页面分析（新增步骤）
|
||
|
||
在正式迁移前，先对目标页面做结构分析：
|
||
|
||
1. 打开 H5 原型截图 + 交互说明文档
|
||
2. 确认页面总长度（几个屏？）
|
||
3. 识别子页面/变种（如 task-detail 的 3 个主题色变体）
|
||
4. 列出所有交互态（弹窗、筛选展开、空状态等）
|
||
5. 输出工作量估算表：
|
||
|
||
```
|
||
| 单位 | 类型 | 描述 | 预估复杂度 |
|
||
|------|------|------|-----------|
|
||
| 屏-1 | 默认态首屏 | Banner + 筛选栏 + 第一板块 | 中 |
|
||
| 屏-2 | 默认态第二屏 | 第二~三板块 | 中 |
|
||
| 交互-1 | 筛选下拉 | 时间筛选 + 区域筛选 | 低 |
|
||
| 交互-2 | 指标弹窗 | 长按指标卡片 | 低 |
|
||
| ... | ... | ... | ... |
|
||
```
|
||
|
||
### 3.3 Step 3：按屏逐个开发
|
||
|
||
规则化转换不是一次性写完整页，而是按屏/交互态逐个推进：
|
||
|
||
1. 先完成首屏结构 → 编译通过 → 截图粗看
|
||
2. 再完成第二屏 → 编译通过 → 截图粗看
|
||
3. 所有屏完成后 → 处理交互态（弹窗、筛选等）
|
||
4. 最后处理三态（loading/empty/error）
|
||
|
||
### 3.4 Step 5：按屏逐个验证
|
||
|
||
结构还原验证同样按屏进行：
|
||
|
||
1. 截取小程序当前屏 → 与 H5 原型截图粗略比对
|
||
2. 9 项核对清单逐项确认
|
||
3. 通过 → 下一屏；未通过 → 修复后重新验证
|
||
4. 所有屏 + 所有交互态全部通过 → 进入 Step 6
|
||
|
||
### 3.5 差异率过大的处理策略
|
||
|
||
当 Step 6 像素对比差异率 > 15% 且多轮微调无法收敛时：
|
||
- 放弃修补，从零重写该页面（需求 2 第 5 条）
|
||
- 复杂 Banner 背景 → 导出为 SVG，`<image>` 引用（需求 2 第 6 条）
|
||
- 复杂 Icon → 导出为 SVG，`<image>` 引用（需求 2 第 7 条）
|
||
|
||
## 4. 样式转换系统设计
|
||
|
||
### 4.1 缩放公式
|
||
|
||
```
|
||
rpx = H5 px × 2 × 0.875
|
||
结果取偶数（向最近偶数取整）
|
||
```
|
||
|
||
特例：`borderRadius` 使用简单 ×2（A/B 对比验证差异 < 0.02%）。
|
||
|
||
### 4.2 design-tokens 映射
|
||
|
||
全局设计令牌来自 `docs/h5_ui/design-tokens.json`，直接映射到 WXSS 变量：
|
||
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| fontSize.xs | 22rpx | 辅助文字 |
|
||
| fontSize.sm | 24rpx | 次要文字 |
|
||
| fontSize.base | 28rpx | 正文 |
|
||
| fontSize.lg | 32rpx | 小标题 |
|
||
| fontSize.xl | 36rpx | 标题 |
|
||
| fontSize.2xl | 42rpx | 大标题 |
|
||
| borderRadius.sm | 8rpx | 小圆角 |
|
||
| borderRadius.md | 16rpx | 中圆角 |
|
||
| borderRadius.lg | 24rpx | 大圆角 |
|
||
| borderRadius.xl | 32rpx | 特大圆角 |
|
||
| borderRadius.3xl | 48rpx | 全圆角 |
|
||
|
||
颜色使用 `colors` 中定义的灰阶（gray-1 ~ gray-13），禁止使用 `#333`、`#666`、`#999` 等非标准灰色。
|
||
|
||
### 4.3 两阶段样式数据源
|
||
|
||
**结构迁移阶段（Step 3）**：
|
||
1. H5 源码 Tailwind 类名 → 查速查表换算
|
||
2. design-tokens.json Token 值
|
||
3. 目测估算（必须标注 `/* 目测值，待校准 */`）
|
||
|
||
**像素精调阶段（Step 6）**：
|
||
1. computed-styles.json 精确 px 值（最高优先级）
|
||
2. H5 源码 Tailwind 类名
|
||
3. design-tokens.json
|
||
4. H5 截图目测（最低）
|
||
|
||
### 4.4 七维度核对
|
||
|
||
每个可见元素写 WXSS 时逐项确认：
|
||
1. font-size
|
||
2. font-weight
|
||
3. color
|
||
4. line-height（必须显式写出）
|
||
5. padding
|
||
6. margin / gap
|
||
7. border / border-radius
|
||
|
||
## 5. AI 图标配色系统设计
|
||
|
||
### 5.1 配色方案定义
|
||
|
||
6 种配色，每种 4 个 CSS 变量：
|
||
|
||
```typescript
|
||
// utils/ai-color.ts
|
||
const AI_COLOR_SCHEMES = {
|
||
red: { from: '#e74c3c', to: '#f39c9c', fromDeep: '#c0392b', toDeep: '#e74c3c' },
|
||
orange: { from: '#e67e22', to: '#f5c77e', fromDeep: '#ca6c17', toDeep: '#e67e22' },
|
||
yellow: { from: '#d4a017', to: '#f7dc6f', fromDeep: '#b8860b', toDeep: '#d4a017' },
|
||
blue: { from: '#2980b9', to: '#7ec8e3', fromDeep: '#1a5276', toDeep: '#2980b9' },
|
||
indigo: { from: '#667eea', to: '#a78bfa', fromDeep: '#4a5fc7', toDeep: '#667eea' },
|
||
purple: { from: '#764ba2', to: '#c084fc', fromDeep: '#5b3080', toDeep: '#764ba2' },
|
||
};
|
||
```
|
||
|
||
### 5.2 小程序实现方案
|
||
|
||
H5 通过 DOM `querySelectorAll` + `classList.add` 实现随机配色。小程序无 DOM API，改用 `setData` + 条件样式：
|
||
|
||
```typescript
|
||
// 页面 onLoad 中调用
|
||
import { getRandomAiColor } from '../../utils/ai-color';
|
||
|
||
Page({
|
||
data: {
|
||
aiColorClass: '', // 'ai-color-red' | 'ai-color-orange' | ...
|
||
aiColorVars: {}, // CSS 变量值对象
|
||
},
|
||
onLoad() {
|
||
const color = getRandomAiColor();
|
||
this.setData({
|
||
aiColorClass: color.className,
|
||
aiColorVars: color.vars,
|
||
});
|
||
},
|
||
});
|
||
```
|
||
|
||
```xml
|
||
<!-- WXML 中使用 -->
|
||
<view class="ai-inline-icon {{aiColorClass}}">
|
||
<image src="/assets/icons/ai-robot-sm.svg" mode="aspectFit" />
|
||
</view>
|
||
|
||
<view class="ai-title-badge {{aiColorClass}}">
|
||
<view class="ai-title-badge-icon">
|
||
<image src="/assets/icons/ai-robot.svg" mode="aspectFit" />
|
||
</view>
|
||
<text>AI 推荐</text>
|
||
</view>
|
||
```
|
||
|
||
### 5.3 两个系列的 WXSS 实现
|
||
|
||
**ai-inline-icon**（行首小图标，28rpx）：
|
||
- 渐变背景 + 白色机器人 SVG
|
||
- 微光扫过动画（12s 周期 `ai-shimmer`）
|
||
- 尺寸：28rpx × 28rpx（H5 16px × 2 × 0.875 ≈ 28）
|
||
|
||
**ai-title-badge**（标题行右侧标识）：
|
||
- 浅色背景 + 主题色文字 + 主题色边框
|
||
- 呼吸脉冲动画（3s 周期 `ai-pulse`）
|
||
- 高光扫过动画（14s 周期 `ai-shimmer`）
|
||
|
||
### 5.4 ai-float-button 排除
|
||
|
||
`ai-float-button` 组件已有固定渐变动画（`#667eea → #764ba2 → #f093fb → #f5576c`），不参与页面级随机配色。无需修改。
|
||
|
||
### 5.5 机器人 SVG 复用
|
||
|
||
- 大系列（ai-title-badge）：复用已有 `assets/icons/ai-robot.svg`
|
||
- 小系列（ai-inline-icon）：从 H5 源码导出白色填充版本，保存为 `assets/icons/ai-robot-sm.svg`
|
||
|
||
## 6. 共享组件设计
|
||
|
||
### 6.1 已有组件（直接复用）
|
||
|
||
| 组件 | 路径 | 用途 | 使用页面 |
|
||
|------|------|------|---------|
|
||
| ai-float-button | components/ai-float-button/ | AI 悬浮按钮 | 所有业务页面 |
|
||
| board-tab-bar | components/board-tab-bar/ | 自定义底部导航 | board-coach, board-customer |
|
||
| filter-dropdown | components/filter-dropdown/ | 筛选下拉面板 | board-finance/coach/customer |
|
||
| heart-icon | components/heart-icon/ | 心形评分 | board-customer |
|
||
| star-rating | components/star-rating/ | 星级评价 | notes |
|
||
| note-modal | components/note-modal/ | 备注弹窗 | task-list/detail, coach-detail |
|
||
| metric-card | components/metric-card/ | 指标卡片 | board-finance, performance |
|
||
| hobby-tag | components/hobby-tag/ | 爱好标签 | board-customer, customer-detail |
|
||
| banner | components/banner/ | 顶部 Banner | task-list, performance |
|
||
| dev-fab | components/dev-fab/ | 开发调试按钮 | 所有页面（开发环境） |
|
||
|
||
### 6.2 组件注册规范
|
||
|
||
每个页面的 `.json` 文件中注册所需组件：
|
||
|
||
```json
|
||
{
|
||
"usingComponents": {
|
||
"t-button": "tdesign-miniprogram/button/button",
|
||
"t-icon": "tdesign-miniprogram/icon/icon",
|
||
"t-loading": "tdesign-miniprogram/loading/loading",
|
||
"ai-float-button": "/components/ai-float-button/ai-float-button",
|
||
"filter-dropdown": "/components/filter-dropdown/filter-dropdown"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. 事件与路由转换设计
|
||
|
||
### 7.1 事件映射表
|
||
|
||
| H5 | 小程序 | 说明 |
|
||
|----|--------|------|
|
||
| `onclick="fn()"` | `bindtap="fn"` | 基础点击 |
|
||
| `onclick="fn(id)"` | `data-id="{{id}}" bindtap="fn"` | dataset 传参 |
|
||
| `event.target.value` | `e.detail.value` | 表单取值 |
|
||
| `event.target.dataset` | `e.currentTarget.dataset` | dataset 取值 |
|
||
| `event.preventDefault()` | `catchtap` | 阻止冒泡 |
|
||
| `classList.toggle` | `setData` + 条件 class | 样式切换 |
|
||
| `innerHTML` | `setData` + WXML 绑定 | 视图更新 |
|
||
| `history.back()` | `wx.navigateBack()` | 返回 |
|
||
| `localStorage` | `wx.setStorageSync` | 本地存储 |
|
||
| `alert()/confirm()` | `wx.showToast()/wx.showModal()` | 弹窗 |
|
||
| `longpress` | `bindlongpress` | 长按 |
|
||
|
||
### 7.2 路由规则
|
||
|
||
| 目标页面类型 | API | 示例 |
|
||
|-------------|-----|------|
|
||
| TabBar 页面 | `wx.switchTab` | task-list, board-finance, my-profile |
|
||
| 普通页面 | `wx.navigateTo` | task-detail, coach-detail, chat |
|
||
| 重定向 | `wx.redirectTo` | 登录后跳转 |
|
||
| 返回 | `wx.navigateBack` | 详情页返回 |
|
||
| 重启 | `wx.reLaunch` | 切换身份 |
|
||
|
||
路径规则：以 `/` 开头，不带 `.wxml` 后缀。
|
||
|
||
## 8. 弹窗与 z-index 分层设计
|
||
|
||
### 8.1 全局 z-index 分层
|
||
|
||
```
|
||
10-29 sticky 元素（Tab 栏 20, 筛选栏 15）
|
||
30 AI 悬浮按钮
|
||
50 底部固定操作栏
|
||
100 自定义底部导航栏（board-tab-bar）
|
||
999 遮罩层
|
||
1000 弹窗内容
|
||
9999 Toast / Loading
|
||
```
|
||
|
||
### 8.2 弹窗实现模式
|
||
|
||
所有弹窗遵循统一模式：
|
||
- 同一时刻只允许一个弹窗打开（互斥）
|
||
- 遮罩 `bindtap` 关闭，内容区 `catchtap` 防穿透
|
||
- 背景滚动锁定：`catchtouchmove` 在遮罩层
|
||
- 底部弹出类添加 `padding-bottom: env(safe-area-inset-bottom)`
|
||
- 动画统一 200-220ms + `ease`
|
||
|
||
## 9. 三态处理设计
|
||
|
||
每个页面统一处理 4 种状态：
|
||
|
||
```xml
|
||
<!-- 通用三态模板 -->
|
||
<view wx:if="{{pageState === 'loading'}}">
|
||
<t-loading text="加载中..." />
|
||
</view>
|
||
<view wx:elif="{{pageState === 'error'}}">
|
||
<view class="error-state">
|
||
<text>加载失败，请点击重试</text>
|
||
<t-button bindtap="onRetry">重试</t-button>
|
||
</view>
|
||
</view>
|
||
<view wx:elif="{{pageState === 'empty'}}">
|
||
<text class="empty-text">{{emptyText}}</text>
|
||
</view>
|
||
<view wx:else>
|
||
<!-- 正常内容 -->
|
||
</view>
|
||
```
|
||
|
||
各页面空状态文案见需求 14。
|
||
|
||
## 10. 像素对比工具链设计
|
||
|
||
### 10.1 工具链流程
|
||
|
||
```
|
||
H5 截图（DPR=3, 1290px 宽）
|
||
↓
|
||
MP 截图（DPR=1.5, 645px）→ ×2 缩放 → 1290px
|
||
↓
|
||
pixelmatch 逐像素对比
|
||
↓
|
||
按 150px 条带分析差异密度
|
||
↓
|
||
定位差异区域 → WXSS 微调 → 循环
|
||
```
|
||
|
||
### 10.2 逐段对比（v2 方案）
|
||
|
||
长页面使用 `scripts/ops/anchor_compare.py`：
|
||
|
||
```bash
|
||
# 提取 H5 锚点 + 截图
|
||
python scripts/ops/anchor_compare.py extract-h5 <page>
|
||
|
||
# 生成 MP 截图指令
|
||
python scripts/ops/anchor_compare.py mp-inst <page>
|
||
|
||
# 执行 MP 截图（通过微信开发者工具 MCP）
|
||
|
||
# 逐段配对 + 对比
|
||
python scripts/ops/anchor_compare.py compare <page>
|
||
```
|
||
|
||
### 10.3 scroll-view 页面截图
|
||
|
||
使用 `scroll-into-view` 模式：
|
||
1. `page.setData({ scrollIntoView: '' })` — 清空
|
||
2. `page.setData({ scrollIntoView: '<section-id>' })` — 设目标
|
||
3. 等待 1000ms → 截图
|
||
|
||
### 10.4 达标标准
|
||
|
||
- 前半屏差异率 < 5%：优秀
|
||
- 前半屏差异率 ≤ 10%：达标
|
||
- 前半屏差异率 > 15% 且无法收敛：触发重写
|
||
|
||
## 11. task-detail 变体策略
|
||
|
||
### 11.1 实现方式
|
||
|
||
1. 先完成 task-detail 主页面的完整迁移和验收
|
||
2. 复制 task-detail 四文件到变体目录
|
||
3. 替换主题色变量（banner 背景色、按钮配色）
|
||
4. 保持数据结构和布局完全一致
|
||
|
||
### 11.2 变体清单
|
||
|
||
| 变体 | 差异点 |
|
||
|------|--------|
|
||
| task-detail-callback | banner 背景色 + 按钮配色（对照 H5 原型校准） |
|
||
| task-detail-priority | banner 背景色 + 按钮配色（对照 H5 原型校准） |
|
||
| task-detail-relationship | banner 背景色 + 按钮配色（对照 H5 原型校准） |
|
||
|
||
## 12. 认证与联调设计
|
||
|
||
### 12.1 认证守卫
|
||
|
||
每个业务页面 `onLoad` 检查登录态：
|
||
|
||
```typescript
|
||
onLoad() {
|
||
const token = wx.getStorageSync('token');
|
||
if (!token) {
|
||
wx.redirectTo({ url: '/pages/login/login' });
|
||
return;
|
||
}
|
||
// 正常加载逻辑
|
||
}
|
||
```
|
||
|
||
### 12.2 开发联调
|
||
|
||
- `utils/request.ts` 中 `BASE_URL` 指向 `http://localhost:8000`
|
||
- 后端 `WX_DEV_MODE=true` 支持 `/api/xcx/dev-login` Mock 登录
|
||
- Storage + header token 维持登录态
|
||
|
||
## 13. 不支持的 CSS 特性替代方案
|
||
|
||
| H5 特性 | 小程序替代 |
|
||
|---------|-----------|
|
||
| `backdrop-filter: blur()` | `background: rgba(255,255,255,0.95)` |
|
||
| `*` 通配符选择器 | 逐个元素设置 |
|
||
| `filter: blur()` | `radial-gradient` 模拟 |
|
||
| `url("data:image/svg+xml,...")` | CSS 渐变模拟或导出 PNG/base64 |
|
||
| `::before/::after`（复杂场景） | 额外 `<view>` 模拟 |
|
||
|
||
直接支持的特性（无需替代）：CSS 变量 `var()`、`linear-gradient`、`animation`/`@keyframes`、`transition`。
|
||
|
||
## 14. 批次执行顺序与依赖
|
||
|
||
```
|
||
A-看板（board-finance → board-coach → board-customer）
|
||
↓ 共享组件验证完毕
|
||
B-核心（task-list → my-profile）
|
||
↓
|
||
C-任务（task-detail → 3 个变体）
|
||
↓
|
||
D-详情（coach-detail → customer-detail → customer-service-records）
|
||
↓
|
||
E-绩效（performance → performance-records）
|
||
↓
|
||
F-对话（chat → chat-history）
|
||
↓
|
||
G-其他（notes）
|
||
```
|
||
|
||
A 批次优先：验证共享组件（filter-dropdown、board-tab-bar、metric-card）在实际页面中的表现，为后续批次建立基线。
|
||
|
||
## 15. 产出物与中间生成物归档
|
||
|
||
迁移过程中会产生大量截图、diff 图、逐段对比图等中间文件。所有生成物必须按类型分目录存放，禁止散放在项目根目录或临时位置。
|
||
|
||
### 15.1 目录结构
|
||
|
||
```
|
||
docs/h5_ui/
|
||
├── screenshots/ # H5 原型截图（输入物，已有）
|
||
│ ├── <page>.png # 默认态截图
|
||
│ └── <page>--<state>.png # 交互态截图
|
||
├── mp-screenshots/ # 🆕 小程序截图（迁移过程生成）
|
||
│ ├── <page>/ # 按页面分子目录
|
||
│ │ ├── <page>.png # 默认态全屏截图
|
||
│ │ ├── <page>--<state>.png # 交互态截图
|
||
│ │ └── seg-<N>-<section>.png # 逐段截图（anchor_compare 生成）
|
||
│ └── ...
|
||
├── diffs/ # 🆕 像素对比结果（迁移过程生成）
|
||
│ ├── <page>/ # 按页面分子目录
|
||
│ │ ├── diff-<page>.png # 全屏 diff 图
|
||
│ │ ├── diff-seg-<N>-<section>.png # 逐段 diff 图
|
||
│ │ └── report.md # 该页面的对比结果摘要（差异率、问题区域）
|
||
│ └── ...
|
||
├── h5-segments/ # 🆕 H5 逐段截图（anchor_compare 生成）
|
||
│ ├── <page>/
|
||
│ │ └── seg-<N>-<section>.png
|
||
│ └── ...
|
||
└── ...
|
||
```
|
||
|
||
### 15.2 归档规则
|
||
|
||
| 生成物类型 | 目标目录 | 命名规则 | 说明 |
|
||
|-----------|---------|---------|------|
|
||
| H5 原型截图 | `docs/h5_ui/screenshots/` | `<page>.png` / `<page>--<state>.png` | 输入物，已有，不动 |
|
||
| MP 全屏截图 | `docs/h5_ui/mp-screenshots/<page>/` | `<page>.png` / `<page>--<state>.png` | 每轮对比更新覆盖 |
|
||
| MP 逐段截图 | `docs/h5_ui/mp-screenshots/<page>/` | `seg-<N>-<section>.png` | anchor_compare 生成 |
|
||
| H5 逐段截图 | `docs/h5_ui/h5-segments/<page>/` | `seg-<N>-<section>.png` | anchor_compare 生成 |
|
||
| 全屏 diff 图 | `docs/h5_ui/diffs/<page>/` | `diff-<page>.png` | pixelmatch 输出 |
|
||
| 逐段 diff 图 | `docs/h5_ui/diffs/<page>/` | `diff-seg-<N>-<section>.png` | pixelmatch 输出 |
|
||
| 对比报告 | `docs/h5_ui/diffs/<page>/` | `report.md` | 差异率 + 问题区域摘要 |
|
||
| 新导出 SVG | `assets/icons/` | `icon-<用途>.svg` / `logo-<名称>.svg` | 小程序工程内 |
|
||
| 图标映射更新 | `docs/h5_ui/icon-mapping.md` | — | 追加新条目 |
|
||
| 小程序页面代码 | `apps/miniprogram/miniprogram/pages/<page>/` | 四文件组合 | 最终交付物 |
|
||
|
||
### 15.3 管理规则
|
||
|
||
1. 按页面分子目录：MP 截图、H5 逐段截图、diff 图均按 `<page>/` 分目录，避免数百张图片平铺
|
||
2. 每轮覆盖更新：像素精调循环中，每轮新截图覆盖上一轮同名文件，不保留历史版本（git 有历史）
|
||
3. 逐段截图编号连续：`seg-0`、`seg-1`、`seg-2`...，与 anchor_compare.py 输出一致
|
||
4. report.md 格式统一：每个页面的 `diffs/<page>/report.md` 记录最终差异率和遗留问题，作为验收依据
|
||
5. .gitignore 不排除：这些中间文件需要入库，便于团队复查和回溯
|
||
6. H5 原型截图目录只读：`docs/h5_ui/screenshots/` 是输入物，迁移过程中不往里写 MP 截图或 diff 图
|