root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
72bb11b34fd0f5593d14afbb1d637bd8685dd52d
Neo-ZQYY/.kiro/specs/h5-miniprogram-migration-subsequent/requirements.md
Neo 72bb11b34f 1
2026-03-15 10:15:02 +08:00

10 KiB
Raw Blame History

需求文档：H5 → 微信小程序像素精调

简介

本 spec 承接 h5-miniprogram-migration 的 Step 0-5 结构迁移成果。17 个页面已全部完成结构迁移、编译验证和结构还原验证。本 spec 专注于 Step 6-7：像素级视觉还原与验收签收。

核心单位是「对照处理单元」——每个页面被分解为多个可独立截图、独立对比、独立修正的最小区域段。17 个页面共分解为 79 个对照处理单元（详见 design.md §5.1，基于 2026-03-10 Playwright 实测校准）。

权威参考：

  • 迁移规则：docs/prd/MIGRATION-PLAYBOOK.md
  • 样式标准：docs/h5_ui/design-tokens.json（颜色、字号、圆角、阴影的标准值）
  • 工具链：scripts/ops/anchor_compare.py（固定步长截图 + 逐屏对比）

术语表

术语 定义
对照处理单元 一个页面内可独立截图、独立对比、独立修正的最小区域段（如"经营一览"板块、"助教卡片列表"区域）
差异率 pixelmatch / image_compare 输出的像素差异百分比，仅针对内容区域计算（头部导航栏/状态栏不计入）
结构级修正 差异率 > 10% 时的修正阶段，修复明显的布局/颜色/缺失问题
像素级精调 差异率 5%~10% 时的精调阶段，微调 padding/font-size/color 等
固定步长 600px 逻辑像素为一步，两端使用完全相同的 scrollTop 序列逐屏截图
双端截图 同一页面的 H5 截图（DPR=1.5, 645×1128）和 MP 截图（DPR=1.5, 645×1128），两端参数完全一致，无需缩放

需求

需求 1：页面分解与对照处理单元建立

用户故事： 作为迁移执行者，我希望每个页面被分解为可独立处理的最小对照单元，以便逐屏精确对比和修正。

验收标准

  1. THE 分解流程 SHALL 对每个页面执行以下步骤：分析 H5 原型结构 → 识别语义区域 → 按固定 600px 步长计算截图屏数 → 建立对照处理单元清单
  2. THE 对照处理单元 SHALL 满足以下条件：每屏为一个对照单元（645×1128 像素），语义完整性由审计报告人工确认
  3. THE 步数计算 SHALL 基于 Playwright 实测的 maxScroll = scrollHeight - viewportHeight：N = floor(maxScroll / 600) + 1；maxScroll ≤ 10 的页面视为单屏（N=1）
  4. WHEN 页面为多维度页面（如 board-coach ×4 排序维度、board-customer ×8 客户维度）时，THE 分解流程 SHALL 按维度分子目录，每个维度独立截图和对比。维度切换通过页面筛选栏下拉操作完成（board-coach 通过排序筛选切换 perf/salary/sv/task 四种卡片模板；board-customer 通过维度筛选切换 recall/potential/balance/recharge/recent/spend60/freq60/loyal 八种卡片模板）
  5. THE 分解结果 SHALL 输出为每页一份的对照单元清单，包含：单元编号（step-N）、scrollTop 值、预估复杂度

需求 2：双端截图标准

用户故事： 作为迁移执行者，我希望 H5 和 MP 的截图在尺寸、视口、DPR 上严格统一，以确保像素对比结果有意义。

验收标准

  1. THE H5 截图 SHALL 使用以下参数：viewport 430×752, DPR=1.5, 输出 645×1128；通过 Playwright 截取（Live Server http://localhost:5500），等待 Tailwind CDN JIT 渲染 1500ms
  2. THE MP 截图 SHALL 使用以下参数：viewport 430×752, DPR=1.5（MCP 有效 DPR）, 输出 645×1128；通过微信开发者工具 MCP 截取。两端输出尺寸完全一致，无需任何缩放
  3. WHEN 对比页面时，THE 截图流程 SHALL 使用固定 600px 步长滚动截图，两端使用完全相同的 scrollTop 序列（0, 600, 1200, ...），不依赖锚点
  4. THE H5 截图前 SHALL 隐藏底部浮动元素：#bottomNav（64px fixed 底部导航）和 .ai-float-btn-container（56px 浮动按钮），通过 JS 设置 display: none。MP 端原生 tabBar 不在截图中，无需处理
  5. THE 头部区域（H5 safe-area-top ~46px / MP 状态栏+胶囊 ~88px）SHALL 不计入像素差异率，属结构性差异
  6. WHEN 截图流程中发现 H5 页面或 MP 页面无法正常渲染时，THE 流程 SHALL 暂停并报告问题，禁止使用异常截图进行对比
  7. WHEN MP 端页面高度与 H5 不一致时，THE 截图流程 SHALL 先截双端 step-0（首屏）确认基线，再截 step-600（第二屏）校准双端高度差异，之后逐屏推进。每屏截图前读取 MP 端实际 scrollTop，确认到达预期位置

需求 3：两阶段收敛流程

用户故事： 作为迁移执行者，我希望像素精调按差异率分阶段处理——先修大问题再调细节——以高效收敛到达标标准。

验收标准

  1. THE 收敛流程 SHALL 分为两个阶段：
    • 阶段一（结构级修正）：差异率 > 10%，每轮修复 2-5 处明显差异（布局/颜色/缺失/字号）
    • 阶段二（像素级精调）：差异率 5%~10%，每轮修复 1-3 处精细差异（padding ±2rpx / line-height / border-radius / 色值）
  2. THE 达标标准 SHALL 为：差异率 < 5% 标记通过；差异率 > 15% 且多轮无法收敛则触发重写
  3. WHEN 进入每轮修正时，THE 流程 SHALL 先截图对比 → 肉眼审查 diff 图 → 定位差异区域 → 修改 WXSS/WXML → 重新截图验证
  4. THE 每轮修正 SHALL 控制修改范围（阶段一 2-5 处、阶段二 1-3 处），避免一次改太多难以定位效果
  5. WHEN 差异率在连续 3 轮内未下降超过 1% 时，THE 流程 SHALL 评估是否为结构性差异（如头部区域、字体渲染差异），若是则标注为可接受差异并停止该区域的精调

需求 4：分析报告持久化

用户故事： 作为项目管理者，我希望每个页面的对比分析结果持久化为 MD 文件，以便追溯和复查。

验收标准

  1. THE 每个页面 SHALL 在 docs/h5_ui/compare/<page>/report.md 输出对比分析报告
  2. THE 报告 SHALL 包含：初始差异率、每轮修正记录（轮次/修改内容/修正后差异率）、最终差异率、遗留的可接受差异说明
  3. THE 报告 SHALL 在每轮修正后更新，记录收敛过程
  4. THE 截图产出物 SHALL 统一归入 docs/h5_ui/compare/<page>/，按页面分子目录：
    • H5 截图：h5--step-<scrollTop>.png
    • MP 截图：mp--step-<scrollTop>.png
    • Diff 图：diff--step-<scrollTop>.png
    • 审计报告：audit.md
    • 对比报告：report.md
    • 多维度页面按维度再分子目录（如 board-coach/perf/）
  5. THE 每轮新截图 SHALL 覆盖上一轮同名文件，不保留历史版本（依赖 git 追溯）

需求 5：修改优先级规则

用户故事： 作为迁移执行者，我希望有明确的修改优先级指导，以便在每轮修正中优先处理影响最大的差异。

验收标准

  1. THE 修改优先级 SHALL 按以下顺序排列（从高到低）：
    • P0：区域缺失或顺序错误（结构性问题）
    • P1：整块背景色/渐变色不匹配
    • P2：字号（font-size）明显偏差（≥4rpx）
    • P3：间距（padding/margin/gap）明显偏差（≥4rpx）
    • P4：圆角（border-radius）偏差
    • P5：颜色色值微调（灰阶偏差、透明度）
    • P6：行高（line-height）/ 字重（font-weight）微调
    • P7：阴影（box-shadow）参数微调
  2. WHEN 阶段一修正时，THE 流程 SHALL 优先处理 P0-P3 级别的差异
  3. WHEN 阶段二精调时，THE 流程 SHALL 处理 P4-P7 级别的差异
  4. THE 修改 SHALL 优先使用 docs/h5_ui/design-tokens.json 中定义的标准值，禁止使用非标准灰色（#333/#666/#999 等）
  5. THE 修改 SHALL 优先使用 flex/盒模型的确定性方案，禁止使用"碰运气"的魔法数

需求 6：验收签收标准

用户故事： 作为项目管理者，我希望每个页面有明确的验收标准，以确保交付质量一致。

验收标准

  1. THE 单页验收 SHALL 满足以下条件：
    • 内容区差异率 < 5%
    • TS 编译零诊断
    • 所有对照处理单元均已逐屏对比
    • report.md 已归档且记录完整
  2. THE 批次验收 SHALL 满足以下条件：
    • 批次内所有页面单页验收通过
    • 共享组件在批次内所有页面中表现一致
    • 所有截图和 diff 图已按目录归档
  3. THE 全局验收 SHALL 满足以下条件：
    • 17 个页面（79 个对照处理单元）全部单页验收通过
    • 差异率汇总表已输出（页面名 / 初始差异率 / 最终差异率 / 修正轮数）
    • TS 编译零诊断复查通过

需求 7：工具链使用规范

用户故事： 作为迁移执行者，我希望工具链的使用有明确规范，以确保截图和对比结果的一致性和可复现性。

验收标准

  1. THE H5 截图 SHALL 统一通过 scripts/ops/anchor_compare.py extract-h5 <page> 获取（固定 600px 步长滚动截图，viewport 430×752, DPR=1.5；通过 Live Server http://localhost:5500 访问页面）
  2. THE MP 截图 SHALL 通过微信开发者工具 MCP 截取，按相同的 scrollTop 序列（0, 600, 1200, ...）逐屏截图
  3. THE 像素对比 SHALL 使用 image_compare power 的 compare_images 工具，或 anchor_compare.py compare <page> 命令
  4. WHEN 页面需要逐屏对比时，THE 流程 SHALL 使用 anchor_compare.py 的两步流程：extract-h5 → compare（MP 截图通过 MCP 工具独立获取）
  5. THE 工具链输出 SHALL 统一存放到 docs/h5_ui/compare/<page>/（见需求 4），禁止散放在项目根目录或临时位置

需求 8：风险与异常处理

用户故事： 作为迁移执行者，我希望在工具链故障或环境异常时有明确的 Fallback 方案，以避免流程阻塞。

验收标准

  1. WHEN 微信开发者工具 MCP 连接断开时，THE 流程 SHALL 先尝试 reconnect_devtools 重连，若连续 3 次失败则暂停该页面任务并报告问题
  2. WHEN Live Server 端口 5500 被占用时，THE 流程 SHALL 检查端口占用并提示用户释放端口，不得使用其他端口截图（避免 URL 不一致）
  3. WHEN image_compare MCP 不可用时，THE 流程 SHALL 使用 anchor_compare.py compare 命令行作为替代
  4. WHEN 某页面差异率 > 15% 且连续 5 轮无法收敛时，THE 流程 SHALL 暂停并输出问题分析报告，由用户决定是否触发重写
  5. THE 每个批次任务 SHALL 在开始前验证页面 TS 零诊断基线，如有编译错误则先修复再进入精调
Reference in New Issue View Git Blame Copy Permalink