136 lines
7.2 KiB
Markdown
136 lines
7.2 KiB
Markdown
# 实现计划：H5 → 微信小程序视觉还原
|
||
|
||
## 概述
|
||
|
||
17 个页面（共 79 个对照处理单元）已完成 Step 0-5 结构迁移。本计划覆盖 Step 6-7：视觉还原与验收。
|
||
|
||
采用固定 600px 步长滚动截图方案：两端使用完全相同的 scrollTop 序列（0, 600, 1200, ...），不依赖锚点，消除 H5/MP 元素位置差异导致的对齐问题。
|
||
|
||
采用混合组织方式：前置阶段按流程批量操作（截图→对比→共性修复），修正阶段按页面逐个完成（审计→修正→验收）。
|
||
|
||
## 截图方案要点
|
||
|
||
- 双端参数：viewport 430×752, DPR=1.5, 输出 645×1128, 无需缩放
|
||
- 步长：600px（逻辑像素）
|
||
- H5 截图：`scripts/ops/anchor_compare.py extract-h5 <page>`（Playwright + Live Server localhost:5500）
|
||
- MP 截图：MCP 工具（`wx.pageScrollTo` + `screenshot`）
|
||
- 产出物根目录：`docs/h5_ui/compare/<page>/`
|
||
- 文件命名：`h5--step-<scrollTop>.png` / `mp--step-<scrollTop>.png` / `diff--step-<scrollTop>.png`
|
||
- 审计报告：`docs/h5_ui/compare/<page>/audit.md`
|
||
- 对比报告：`docs/h5_ui/compare/<page>/report.md`
|
||
- 多维度页面：`docs/h5_ui/compare/<page>/<dimension>/`（如 board-coach/perf/、board-customer/recall/）
|
||
- 维度切换：board-coach 通过排序筛选下拉切换 perf/salary/sv/task；board-customer 通过维度筛选下拉切换 recall/potential/balance/recharge/recent/spend60/freq60/loyal
|
||
|
||
## 逐页视觉还原流程（阶段 3 每页统一流程）
|
||
|
||
每个页面子任务按以下步骤执行：
|
||
|
||
1. **截图**：先截双端 step-0（首屏）确认基线，再截 step-600（第二屏）校准双端高度差异，之后按固定步长序列逐屏推进。每屏读取 MP 端实际 scrollTop 确认到达预期位置
|
||
2. **审计报告**：同时读取 H5 源码（HTML + Tailwind 类名）、MP 源码（WXML + WXSS）、diff 截图，三方对照产出 `docs/h5_ui/compare/<page>/audit.md`
|
||
3. **浮动元素检测**（长页面）：对比多屏截图中持续相同位置的差异，识别 sticky/fixed 元素，优先修复（一次修复所有屏受益）
|
||
4. **阶段一修正循环**（差异率 > 10%）：按审计报告偏差清单修正 → 每轮修 2-5 处 → 重新截图对比 → 循环至 ≤ 10%
|
||
5. **阶段二精调循环**（差异率 5%~10%）：精确定位差异区域 → 每轮修 1-3 处 → 重新截图对比 → 循环至 < 5%
|
||
6. **验收**：差异率 < 5% → 更新 report.md → 标记通过
|
||
|
||
### 长页面级联规则
|
||
|
||
修正某一屏的 WXSS 后，所有屏必须重新截图对比（布局变化会影响每屏内容）。优先修复 sticky 区域差异，从 step-0 开始顺序审查。
|
||
|
||
---
|
||
|
||
## 任务
|
||
|
||
### 阶段 0 — 前置准备
|
||
|
||
- [x] 0. 工具链验证与基线检查
|
||
- [x] 0.1 验证截图工具链：确认 Playwright 可通过 Live Server (localhost:5500) 截图 H5 页面、微信开发者工具 MCP 可连接截图、image_compare 可对比
|
||
- [x] 0.2 TS 零诊断基线检查：对 17 个页面的 .ts 文件运行 getDiagnostics，确认全部为零诊断
|
||
- [x] 0.3 固定步长方案验证：board-finance 实测 10 屏（step 0-4848，scrollHeight=5600, maxScroll=4848），两端精确命中目标 scrollTop，截图 645×1128 完全一致
|
||
|
||
---
|
||
|
||
### 阶段 1 — 批量截图与初始对比
|
||
|
||
- [ ] 1. 批量获取 H5 截图（board-finance 已完成 10 屏验证）
|
||
- [ ] 1.1 board-finance H5 固定步长截图（10 屏，step 0-4848）— 已通过 test_fixed_step.py 完成
|
||
- [x] 1.2 重构 anchor_compare.py 为固定步长模式，支持 `extract-h5 <page>` 自动计算页面高度和步数
|
||
- [ ] 1.3 对剩余 16 个页面运行 H5 固定步长截图
|
||
|
||
- [ ] 2. 批量获取 MP 截图（board-finance 已完成 10 屏验证）
|
||
- [x] 2.1 board-finance MP 固定步长截图（10 屏，step 0-4848）— 已通过 MCP 工具完成
|
||
- [ ] 2.2 对剩余 16 个页面通过 MCP 工具截取 MP 固定步长截图
|
||
|
||
- [ ] 3. 批量初始对比与差异率采集
|
||
- [x] 3.1 board-finance 逐屏对比完成（差异率 5.01%~17.71%，差异来自组件未精校）
|
||
- [ ] 3.2 对剩余 16 个页面运行逐屏对比，输出 diff 图到 `docs/h5_ui/compare/<page>/`
|
||
- [ ] 3.3 汇总差异率表（页面名 / 屏数 / 各屏差异率），按差异率降序排列
|
||
|
||
---
|
||
|
||
### 阶段 2 — 共性偏差批量修复
|
||
|
||
- [ ] 4. 跨页面共性偏差修复
|
||
- [ ] 4.1 根据阶段 1 差异率和 design.md §4.2 已识别的共性偏差（Tab 导航 font-size/padding/line-height、筛选栏 border-radius、卡片 padding、标签 border-radius），在各页面 WXSS 或共享组件中统一修正
|
||
- [ ] 4.2 共性修复后重新截图验证：对涉及修改的页面重新截图 + 对比，确认共性修正未引入新问题
|
||
|
||
---
|
||
|
||
### 阶段 3 — 逐页视觉还原
|
||
|
||
按批次组织，每页按「逐页视觉还原流程」执行（截图→审计→浮动元素检测→修正循环→验收）。
|
||
|
||
#### A 批次 — 看板页面
|
||
|
||
- [ ] 5. board-finance 视觉还原（长页面，10 屏 step 0-4848）。含 sticky 区域检测（safe-area-top 45px + filterBar 71px = 116px）
|
||
- [ ] 6. board-coach 视觉还原（短页面，4 种排序维度 perf/salary/sv/task 需逐维度截图验证，通过排序筛选下拉切换）
|
||
- [ ] 7. board-customer 视觉还原（短页面，8 种客户维度 recall/potential/balance/recharge/recent/spend60/freq60/loyal 需逐维度截图验证，通过维度筛选下拉切换）
|
||
- [ ] 8. A 批次检查点：3 页全部差异率 < 5%，共享组件跨页表现一致
|
||
|
||
#### B 批次 — 核心页面
|
||
|
||
- [ ] 9. task-list 视觉还原（约 3 屏）
|
||
- [ ] 10. my-profile 视觉还原（单屏页面）
|
||
- [ ] 11. B 批次检查点：2 页全部差异率 < 5%
|
||
|
||
#### C 批次 — 任务详情页面
|
||
|
||
> task-detail 系列 4 个页面共享相同布局，仅 Banner 主题色不同。主页面做完整还原，3 个变体只验证主题色差异。
|
||
|
||
- [ ] 12. task-detail 视觉还原（主页面，约 5 屏，完整审计→修正→验收）
|
||
- [ ] 13. task-detail 变体主题色验证（callback=teal / priority=orange / relationship=pink）：逐个截图 → 仅对比含主题色的屏 → 确认主题色正确应用
|
||
- [ ] 14. C 批次检查点：4 页全部差异率 < 5%
|
||
|
||
#### D 批次 — 详情页面
|
||
|
||
- [ ] 15. coach-detail 视觉还原（约 5 屏）
|
||
- [ ] 16. customer-detail 视觉还原（约 5 屏）
|
||
- [ ] 17. customer-service-records 视觉还原（约 2 屏）
|
||
- [ ] 18. D 批次检查点：3 页全部差异率 < 5%
|
||
|
||
#### E 批次 — 绩效页面
|
||
|
||
- [ ] 19. performance 视觉还原（约 13 屏，本 spec 最长页面）
|
||
- [ ] 20. performance-records 视觉还原（约 5 屏）
|
||
- [ ] 21. E 批次检查点：2 页全部差异率 < 5%
|
||
|
||
#### F 批次 — 对话页面
|
||
|
||
- [ ] 22. chat 视觉还原（约 2 屏）
|
||
- [ ] 23. chat-history 视觉还原（单屏页面）
|
||
- [ ] 24. F 批次检查点：2 页全部差异率 < 5%
|
||
|
||
#### G 批次 — 其他页面
|
||
|
||
- [ ] 25. notes 视觉还原（约 3 屏）
|
||
- [ ] 26. G 批次检查点：差异率 < 5%
|
||
|
||
---
|
||
|
||
### 阶段 4 — 全局验收
|
||
|
||
- [ ] 27. 全局验收
|
||
- [ ] 27.1 汇总 17 页面差异率表（页面名 / 屏数 / 初始差异率 / 共性修复后差异率 / 最终差异率 / 修正轮数），共 79 个对照处理单元
|
||
- [ ] 27.2 确认所有 `compare/<page>/report.md` 已归档
|
||
- [ ] 27.3 TS 编译零诊断复查（17 个页面）
|
||
- [ ] 27.4 标记 spec 完成
|