7.2 KiB
7.2 KiB
实现计划：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 每页统一流程）
每个页面子任务按以下步骤执行：
- 截图：先截双端 step-0（首屏）确认基线，再截 step-600（第二屏）校准双端高度差异，之后按固定步长序列逐屏推进。每屏读取 MP 端实际 scrollTop 确认到达预期位置
- 审计报告：同时读取 H5 源码（HTML + Tailwind 类名）、MP 源码（WXML + WXSS）、diff 截图，三方对照产出
docs/h5_ui/compare/<page>/audit.md - 浮动元素检测（长页面）：对比多屏截图中持续相同位置的差异，识别 sticky/fixed 元素，优先修复（一次修复所有屏受益）
- 阶段一修正循环（差异率 > 10%）：按审计报告偏差清单修正 → 每轮修 2-5 处 → 重新截图对比 → 循环至 ≤ 10%
- 阶段二精调循环（差异率 5%~10%）：精确定位差异区域 → 每轮修 1-3 处 → 重新截图对比 → 循环至 < 5%
- 验收：差异率 < 5% → 更新 report.md → 标记通过
长页面级联规则
修正某一屏的 WXSS 后，所有屏必须重新截图对比（布局变化会影响每屏内容）。优先修复 sticky 区域差异，从 step-0 开始顺序审查。
任务
阶段 0 — 前置准备
- 0. 工具链验证与基线检查
- 0.1 验证截图工具链：确认 Playwright 可通过 Live Server (localhost:5500) 截图 H5 页面、微信开发者工具 MCP 可连接截图、image_compare 可对比
- 0.2 TS 零诊断基线检查：对 17 个页面的 .ts 文件运行 getDiagnostics，确认全部为零诊断
- 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 完成
- 1.2 重构 anchor_compare.py 为固定步长模式，支持
extract-h5 <page>自动计算页面高度和步数 - 1.3 对剩余 16 个页面运行 H5 固定步长截图
-
2. 批量获取 MP 截图（board-finance 已完成 10 屏验证）
- 2.1 board-finance MP 固定步长截图（10 屏，step 0-4848）— 已通过 MCP 工具完成
- 2.2 对剩余 16 个页面通过 MCP 工具截取 MP 固定步长截图
-
3. 批量初始对比与差异率采集
- 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 完成