Neo-ZQYY/.kiro/specs/h5-miniprogram-migration/requirements.md

需求文档：H5 → 微信小程序批量迁移

简介

将 docs/h5_ui/pages/ 下 17 个 HTML 原型页面迁移为原生微信小程序页面（WXML/WXSS/TS/JSON）。迁移范围覆盖 7 个批次（A-看板、B-核心、C-任务、D-详情、E-绩效、F-对话、G-其他），每页需走完 7 步标准流程（输入物冻结 → 迁移审计 → 规则化转换 → 编译验证 → 结构还原验证 → 像素级对比 → 验收签收）。本工程为纯前端迁移，不涉及后端 API 开发或数据库变更。

权威参考文档：docs/prd/MIGRATION-PLAYBOOK.md（唯一迁移执行手册）。

术语表

• Playbook：docs/prd/MIGRATION-PLAYBOOK.md，H5→小程序迁移的唯一权威执行手册
• H5_原型：docs/h5_ui/pages/<page>.html，基于 Tailwind CDN + 内联 SVG + 原生 JS 的单文件 HTML 原型
• 小程序页面：apps/miniprogram/miniprogram/pages/<page>/ 下的 .wxml/.wxss/.ts/.json 四文件组合
• WXML：微信小程序标记语言，替代 HTML
• WXSS：微信小程序样式表，替代 CSS，支持 rpx 单位
• rpx：微信小程序响应式像素单位，750rpx = 屏幕宽度
• 缩放公式：rpx = H5 px × 2 × 0.875，结果取偶数（向最近偶数取整）
• design-tokens：docs/h5_ui/design-tokens.json，全局颜色/间距/字号/圆角/阴影定义
• computed-styles：docs/h5_ui/computed-styles.json，H5 元素的浏览器计算样式精确 px 值
• 交互说明：docs/h5_ui/interactions/<page>.md，每页的状态变量 + 操作响应 + 状态枚举
• icon-mapping：docs/h5_ui/icon-mapping.md，H5 图标到小程序实现的映射表
• TDesign：腾讯开源的微信小程序 UI 组件库
• 结构还原验证：对照 H5 原型截图和交互说明，逐项确认区域划分、元素层级、文本内容、图标、导航、弹窗、滚动、三态占位等 9 项结构要素
• 像素级对比：使用工具链（截图 → 尺寸统一 → pixelmatch → 差异分析）量化小程序与 H5 原型的视觉差异百分比
• 七维度核对：每个可见元素写 WXSS 时必须逐一确认的 7 个属性维度（字号、字重、文字颜色、行高、内间距、外间距、边框与圆角）
• 三态处理：每个页面必须处理的 loading / empty / error / normal 四种状态
• TabBar_页面：task-list、board-finance、my-profile，使用 wx.switchTab 跳转
• 迁移审计报告：Step 2 输出的 7 项审计内容（页面结构、CSS 风险点、关键样式映射、图标处理、交互映射、外部依赖、缺失信息）
• 差异率：pixelmatch 对比输出的像素差异百分比，前半屏 < 5% 为优秀，≤ 10% 为达标

需求

需求 1：迁移范围与批次管理

用户故事： 作为项目管理者，我希望 17 个页面按批次有序迁移，以便控制进度和质量。

验收标准

1. THE 迁移工程 SHALL 覆盖以下 17 个页面，按 7 个批次组织：A-看板（board-finance、board-coach、board-customer）、B-核心（task-list、my-profile）、C-任务（task-detail、task-detail-callback、task-detail-priority、task-detail-relationship）、D-详情（coach-detail、customer-detail、customer-service-records）、E-绩效（performance、performance-records）、F-对话（chat、chat-history）、G-其他（notes）
2. THE 迁移工程 SHALL 排除以下页面：login、no-permission、reviewing、apply（用户指定不迁移）、home-settings（无交互说明）、ai-icon-demo（无截图和交互说明）
3. WHEN 迁移 board-coach、board-customer、board-finance、notes 页面时，THE 迁移流程 SHALL 对已有历史实现按标准流程重新审计、对比 H5 原型、差异修复、像素级验收
4. WHEN 迁移其余 13 个页面时，THE 迁移流程 SHALL 从零开始执行全流程迁移

需求 2：7 步标准迁移流程

用户故事： 作为迁移执行者，我希望每个页面都走完标准化的 7 步流程，以确保迁移质量一致且可追溯。

验收标准

1. THE 迁移流程 SHALL 对每个页面依次执行以下 7 步：Step 1 输入物冻结、Step 2 迁移审计、Step 3 规则化转换、Step 4 编译验证、Step 5 结构还原验证、Step 6 像素级视觉对比、Step 7 验收签收
2. THE 迁移流程 SHALL 禁止跳过任何步骤，后续步骤的执行以前置步骤通过为前提
3. WHEN Step 5 结构还原验证未全部通过时，THE 迁移流程 SHALL 禁止进入 Step 6 像素级对比
4. WHEN 验收未通过时，THE 迁移流程 SHALL 按问题类型回退到对应步骤（结构错误→Step 5、样式偏差→Step 6、交互缺陷→Step 3、编译报错→Step 4、真机差异→Step 6），并从回退步骤开始重新往下走完所有后续步骤
5. WHEN Step 6 像素级对比的差异率过大（前半屏 > 15%）且多轮微调无法收敛时，THE 迁移流程 SHALL 放弃修补，直接按后续规则（需求 5-9、需求 21）从零重写该小程序页面
6. WHEN H5 原型页面包含渐变复杂、条纹复杂的 Banner 背景时，THE 迁移流程 SHALL 将该背景生成为 SVG 文件，存放到 assets/icons/ 目录，在 WXML 中通过 <image src="/assets/icons/bg-<name>.svg"> 引用
7. WHEN H5 原型页面包含精美复杂的 Icon 或装饰性按钮（非标准 TDesign 图标可覆盖）时，THE 迁移流程 SHALL 将其生成为 SVG 文件导出，通过 <image> 引用，而非尝试用 WXSS 手动还原

需求 3：输入物分批提供

用户故事： 作为迁移执行者，我希望输入物按阶段分批提供——结构迁移阶段只需结构和行为材料，像素精调阶段再补充视觉校验材料——以避免因截图等材料未就绪而阻塞结构迁移工作。

验收标准

1. THE 输入物 SHALL 分为两批提供：
   • 第一批（结构迁移，Step 1-5）：规则层（Playbook）→ 全局资源层（design-tokens.json、icon-mapping.md）→ 页面源码层（H5 HTML docs/h5_ui/pages/<page>.html、自定义 CSS docs/h5_ui/css/<page>.css（如有））→ 行为层（docs/h5_ui/interactions/<page>.md）
   • 第二批（像素精调，Step 6-7）：computed-styles.json 中该页面的精确 px 值、H5 默认态截图 docs/h5_ui/screenshots/<page>.png（DPR=3, 1290px 宽）、交互态截图 docs/h5_ui/screenshots/<page>--<state>.png
2. WHEN 开始结构迁移（Step 1-5）时，THE 迁移流程 SHALL 仅要求第一批输入物齐全；第二批输入物缺失不阻塞结构迁移
3. WHEN 进入像素精调（Step 6）时，THE 迁移流程 SHALL 要求第二批输入物齐全；IF 第二批输入物缺失，THEN 标记缺失项并暂停像素精调，不猜测
4. IF 第一批中任何必需输入物缺失，THEN THE 迁移流程 SHALL 标记缺失项并暂停该页面迁移，禁止猜测缺失内容
5. THE 结构迁移阶段的样式转换 SHALL 基于 H5 源码中的 Tailwind 类名和 design-tokens.json 进行换算，不依赖 computed-styles.json；computed-styles.json 仅在像素精调阶段用于精确校准

需求 4：迁移审计报告（Step 2）

用户故事： 作为迁移执行者，我希望在写代码前先输出审计报告，以识别风险点和制定转换策略。

验收标准

1. WHEN 输入物冻结完成后，THE 迁移流程 SHALL 输出《迁移审计报告》，包含 7 项：A.页面结构（区域划分+组件化边界）、B.CSS 风险点（不支持特性+替代方案）、C.关键样式映射（Tailwind→computed→WXSS 七维度核对）、D.图标处理（每个 SVG 的处理决策）、E.交互映射（H5 DOM→setData+事件绑定）、F.外部依赖（CDN 本地化方案）、G.缺失信息（需补充材料清单）
2. THE 迁移审计报告 SHALL 在写任何转换代码之前完成输出
3. THE 迁移审计报告中每个 CSS 风险点 SHALL 包含原因、影响、处理方案、验收方式四项说明

需求 5：标签与结构转换规则

用户故事： 作为迁移执行者，我希望有明确的 HTML→WXML 标签映射规则，以确保转换的一致性和正确性。

验收标准

1. THE 转换引擎 SHALL 按以下映射执行标签转换：<div>→<view>、<span>/<p>→<text>、<img>→<image mode="">（必须指定 mode 和宽高）、<svg>→<image src="xx.svg"> 或 <t-icon>、<button>→<t-button>、<input>→<t-input>、<textarea>→<t-textarea>、<select>→<t-picker>、<a>→bindtap+wx.navigateTo、<ul>/<li>→<view wx:for>（必须加 wx:key）、<table>→<view> 手动布局、scroll 容器→<scroll-view>（必须设固定高度）
2. THE 转换引擎 SHALL 禁止在 WXML 中使用任何 HTML 标签
3. THE 转换引擎 SHALL 确保 <text> 内只嵌套 <text>，需要块级布局时外层使用 <view>
4. WHEN 列表渲染时，THE 转换引擎 SHALL 为每个 wx:for 提供 wx:key 属性

需求 6：样式转换与缩放规则

用户故事： 作为迁移执行者，我希望所有样式值都按统一公式换算，以确保像素级视觉还原。

验收标准

1. THE 样式转换 SHALL 使用核心缩放公式 rpx = H5 px × 2 × 0.875，结果取偶数（向最近偶数取整）
2. THE 样式转换 SHALL 按以下数据源优先级取值，且区分两个阶段：
   • 结构迁移阶段（Step 3）：H5 源码 Tailwind 类名（查速查表换算）→ design-tokens.json Token 值（颜色/圆角/阴影）→ 目测估算（必须标注 /* 目测值，待校准 */）
   • 像素精调阶段（Step 6）：computed-styles.json 精确 px 值（最高优先级，覆盖结构阶段的换算值）→ H5 源码 Tailwind 类名 → design-tokens.json → H5 截图目测估算（最低）
3. THE 样式转换 SHALL 对每个可见元素按七维度逐项核对：字号（font-size）、字重（font-weight）、文字颜色（color）、行高（line-height）、内间距（padding）、外间距（margin/gap）、边框与圆角（border/border-radius）
4. THE 样式转换 SHALL 禁止使用不在 design-tokens.json 色阶表中的灰色值（禁止 #333、#666、#999 等非标准灰色）
5. THE 样式转换 SHALL 显式写出 line-height 值，禁止依赖小程序默认行高
6. THE 样式转换 SHALL 使用最小 2rpx 的边框宽度（1rpx 在部分设备不显示）
7. THE 样式转换 SHALL 禁止不查任何数据源直接写"看起来差不多"的值

需求 7：事件与路由转换规则

用户故事： 作为迁移执行者，我希望 H5 事件和路由逻辑有明确的小程序对应方案，以确保交互行为正确迁移。

验收标准

1. THE 转换引擎 SHALL 按以下映射执行事件转换：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、event.preventDefault()→catchtap、classList.toggle→setData+条件 class 绑定、innerHTML→setData+WXML 数据绑定、history.back()→wx.navigateBack()、localStorage→wx.setStorageSync、alert()/confirm()→wx.showToast()/wx.showModal()
2. WHEN 跳转到 TabBar 页面（task-list、board-finance、my-profile）时，THE 路由逻辑 SHALL 使用 wx.switchTab，禁止使用 wx.navigateTo
3. THE 路由逻辑 SHALL 确保所有路径以 / 开头且不带 .wxml 后缀
4. THE 转换引擎 SHALL 禁止使用 addEventListener、document.getElementById 等 DOM API，所有视图更新通过 this.setData() 驱动

需求 8：SVG 图标处理

用户故事： 作为迁移执行者，我希望每个 H5 页面中的 SVG 图标都有明确的处理决策，以避免图标缺失或显示异常。

验收标准

1. WHEN H5 页面包含内联 SVG 时，THE 图标处理流程 SHALL 按以下优先级决策：TDesign 有语义等价图标→使用 <t-icon>、品牌/自定义图标→导出为 apps/miniprogram/miniprogram/assets/icons/<name>.svg
2. THE 图标处理流程 SHALL 按命名规则导出 SVG：功能图标用 icon-<用途>.svg、Logo 类用 logo-<名称>.svg
3. THE 图标处理流程 SHALL 在导出 SVG 时保留原始 viewBox、fill、path
4. WHEN 在小程序中引用 SVG 时，THE 图标引用 SHALL 使用 <image src="/assets/icons/<name>.svg" mode="aspectFit" />，并指定宽高
5. WHEN 迁移新页面导出新 SVG 时，THE 图标处理流程 SHALL 将新导出的 SVG 追加到 icon-mapping.md 清单

需求 9：不支持的 CSS 特性替代方案

用户故事： 作为迁移执行者，我希望所有小程序不支持的 CSS 特性都有明确的替代方案，以避免样式失效。

验收标准

1. WHEN H5 使用 backdrop-filter: blur() 时，THE 样式转换 SHALL 替换为 background: rgba(255,255,255,0.95) 半透明背景
2. WHEN H5 使用 * 通配符选择器时，THE 样式转换 SHALL 逐个元素设置对应属性
3. WHEN H5 使用 filter: blur() 时，THE 样式转换 SHALL 使用 radial-gradient 模拟扩散效果
4. WHEN H5 使用 url("data:image/svg+xml,...") 时，THE 样式转换 SHALL 使用 CSS 渐变模拟或导出为 PNG/base64
5. WHEN H5 使用 ::before/::after 伪元素且场景复杂时，THE 样式转换 SHALL 使用额外 <view> 元素模拟
6. THE 样式转换 SHALL 确保 CSS 变量 var()、linear-gradient、animation/@keyframes、transition 直接迁移（小程序支持）

需求 10：状态栏与安全区适配

用户故事： 作为用户，我希望小程序页面在各种机型（含刘海屏）上正确显示，内容不被遮挡。

验收标准

1. WHEN 页面使用自定义导航栏（navigationStyle: 'custom'）时，THE 页面 SHALL 通过 JS wx.getSystemInfoSync().statusBarHeight 获取状态栏高度，并设置 padding-top
2. THE 页面 SHALL 禁止使用 env(safe-area-inset-top) 获取顶部安全区（部分机型不生效），改用 JS 方案
3. WHEN 页面包含底部固定栏或底部弹窗时，THE 页面 SHALL 添加 padding-bottom: env(safe-area-inset-bottom) 适配刘海屏底部
4. WHEN 页面为一屏布局（不滚动）时，THE 页面 SHALL 使用 height: 100vh + box-sizing: border-box，确保 padding-top 从 100vh 中扣除

需求 11：长页面滚动与吸顶处理

用户故事： 作为用户，我希望长页面（超过一屏）能正常滚动，吸顶元素在滚动时保持固定位置。

验收标准

1. THE 长页面 SHALL 优先使用页面自然滚动（min-height: 100vh），禁止用 scroll-view 包裹整个页面
2. WHEN 页面中某个区域需要独立滚动时（如 chat 页消息区），THE 页面 SHALL 使用 <scroll-view scroll-y> 并设固定高度
3. THE 吸顶元素 SHALL 使用 position: sticky，且父容器不设 overflow: hidden
4. WHEN 多个 sticky 元素叠加时，THE 页面 SHALL 确保 z-index 从上到下递减（20→15→10）
5. THE sticky 元素 SHALL 设置 background-color，防止内容穿透
6. WHEN 页面包含底部固定操作栏时，THE 页面 SHALL 使用 position: fixed + z-index: 50，并在内容区末尾添加占位 <view> 防止内容被遮挡
7. WHERE 页面适用下拉刷新（task-list、board-finance、board-coach、board-customer、notes、chat-history），THE 页面 SHALL 启用下拉刷新功能
8. WHEN 页面包含 filter-bar（筛选栏）时，THE filter-bar SHALL 统一高度为 70 逻辑像素，所有看板页面（board-finance、board-coach、board-customer）保持一致。此约束确保两端 sticky 区域高度一致（~116px），v2 逐段截图自然对齐。编辑小程序前端页面时须 check 并修正不符合此高度的 filter-bar。

需求 12：交互弹窗与状态管理

用户故事： 作为用户，我希望所有弹窗、浮层、下拉面板的交互行为与 H5 原型一致，且不出现穿透、滚动异常等问题。

验收标准

1. THE 弹窗系统 SHALL 遵循统一的 z-index 分层策略：sticky 元素 10-29、AI 悬浮按钮 30、底部固定栏 50、自定义底部导航栏 100、遮罩 999、弹窗内容 1000、Toast/Loading 9999
2. THE 弹窗系统 SHALL 确保同一时刻只允许一个弹窗打开（互斥）
3. WHEN 弹窗打开时，THE 弹窗 SHALL 使用 catchtouchmove 阻止背景页面滚动
4. THE 遮罩层 SHALL 使用 bindtap 关闭弹窗，弹窗内容区 SHALL 使用 catchtap 防止点击穿透
5. WHEN 弹窗为底部弹出类型时，THE 弹窗 SHALL 添加 padding-bottom: env(safe-area-inset-bottom)
6. THE 弹窗动画 SHALL 统一使用 200-220ms 时长和 ease 缓动函数
7. WHEN 使用筛选下拉面板时，THE 页面 SHALL 复用共享组件 filter-dropdown（规范见 Playbook 第八章 8.3）

需求 13：长按菜单交互

用户故事： 作为用户，我希望在 task-list 页面长按任务卡片时弹出操作菜单，且长按和点击手势互不干扰。

验收标准

1. WHEN 用户长按任务卡片时，THE task-list 页面 SHALL 使用 bindlongpress 触发长按菜单，菜单定位在触摸点附近
2. THE 长按菜单 SHALL 包含以下操作项：任务置底、问问助手、备注
3. THE 长按菜单 SHALL 使用黑底圆角样式（rgba(0,0,0,0.85) 背景、16rpx 圆角、白色文字）
4. WHEN 长按菜单显示时，THE task-list 页面 SHALL 在 onTaskTap 中跳过跳转逻辑，防止长按后误触发点击跳转
5. WHEN 用户点击遮罩或菜单项时，THE 长按菜单 SHALL 关闭

需求 14：三态处理

用户故事： 作为用户，我希望每个页面在加载中、无数据、出错时都有明确的 UI 反馈，而不是空白页面。

验收标准

1. THE 每个页面 SHALL 处理 loading、empty、error、normal 四种状态
2. WHEN 页面处于 loading 状态时，THE 页面 SHALL 显示 <t-loading> 组件和"加载中..."文字
3. WHEN 页面处于 empty 状态时，THE 页面 SHALL 显示对应的空状态文案（task-list→"暂无任务"、board-coach→"暂无助教数据"、board-customer→"暂无客户数据"、board-finance→"暂无财务数据"、chat-history→"暂无对话记录"、notes→"暂无备注记录"、performance-records→"暂无业绩明细"、customer-service-records→"暂无服务记录"、其他→"暂无数据"）
4. WHEN 页面处于 error 状态时，THE 页面 SHALL 显示"加载失败，请点击重试"文字和重试按钮
5. WHEN 用户点击重试按钮时，THE 页面 SHALL 重新加载数据

需求 15：共享组件复用

用户故事： 作为迁移执行者，我希望跨页面复用的 UI 元素抽取为共享组件，以保持一致性并减少重复代码。

验收标准

1. THE 迁移工程 SHALL 复用以下已有共享组件：ai-float-button（AI 悬浮按钮，所有业务页面右下角）、board-tab-bar（自定义底部导航栏，board-coach/board-customer 使用）、filter-dropdown（筛选下拉面板，board-finance/coach/customer 使用）、heart-icon（心形评分图标，board-customer 使用）、dev-fab（开发调试按钮）
2. THE ai-float-button 组件 SHALL 在所有业务页面右下角显示，默认 bottom 220rpx，使用固定渐变动画（不参与页面级随机配色，详见需求 32）
3. THE board-tab-bar 组件 SHALL 用于非 TabBar 的看板子页面，高度 100rpx，包含 safe-area 底部适配
4. THE filter-dropdown 组件 SHALL 实现全屏宽度面板 + 半透明遮罩 + 动态 top 计算
5. THE heart-icon 组件 SHALL 使用 TS observers 监听 score 属性变化计算 emoji（WXS 不支持 emoji surrogate pair）

需求 16：TDesign 组件使用规范

用户故事： 作为迁移执行者，我希望 TDesign 组件的使用遵循统一规范，以避免样式冲突和事件绑定错误。

验收标准

1. THE 迁移工程 SHALL 按以下替代关系使用 TDesign 组件：<button>→<t-button>、<input>→<t-input>、<textarea>→<t-textarea>、<select>→<t-picker>、SVG 图标→<t-icon>、加载动画→<t-loading>、确认弹窗→<t-dialog>、底部弹出→<t-popup>
2. WHEN TDesign 组件事件绑定时，THE 迁移工程 SHALL 使用 bind:change 而非 bindinput
3. WHEN 需要覆盖 TDesign 组件样式时，THE 迁移工程 SHALL 优先使用 CSS 变量，其次外部样式类，再次利用 addGlobalClass，最后使用 style 属性
4. WHEN 组件与 H5 原型差异过大时，THE 迁移工程 SHALL 使用原生 view 实现而非强行定制 TDesign 组件
5. THE 迁移工程 SHALL 确保 app.json 中不包含 "style": "v2" 配置（会导致 TDesign 样式错乱）
6. WHEN 安装新 npm 包后，THE 迁移工程 SHALL 在微信开发者工具中执行"构建 npm"

需求 17：编译验证（Step 4）

用户故事： 作为迁移执行者，我希望每个页面转换后通过编译验证，以确保代码无语法错误和运行时问题。

验收标准

1. WHEN 规则化转换完成后，THE 编译验证 SHALL 检查以下 7 项：WXML 编译无错误、WXSS 编译无警告（检查不支持的选择器）、控制台无 JS 运行时错误、图片加载无 404/500 错误（所有 /assets/ 引用的文件必须存在）、组件注册无 "component not found" 警告、路由跳转无 "navigateTo:fail" 错误、TS 类型定义完整（Page<IData>() 中 data 所有字段有初始值）
2. THE 编译验证 SHALL 特别检查 WXML 中不包含 JS 方法调用（如 .toFixed()），需要格式化的逻辑使用 WXS 模块 utils/format.wxs
3. IF 编译验证发现错误，THEN THE 迁移流程 SHALL 修复错误后重新验证，直到全部通过

需求 18：结构还原验证（Step 5）

用户故事： 作为迁移执行者，我希望在像素对比前先确认页面结构与 H5 原型一致，以避免在结构错误的基础上做无意义的像素调整。

验收标准

1. WHEN 编译验证通过后，THE 结构还原验证 SHALL 逐项对照 H5 原型截图和交互说明，确认以下 9 项：区域划分（header/content/footer/tabbar 与 H5 一致）、元素层级（嵌套层级与 H5 DOM 结构对应）、列表/卡片数量（Mock 数据条数与 H5 一致）、文本内容（标题/标签/按钮文案完全一致）、图标完整性（所有图标位置有对应实现）、导航结构（自定义导航栏/返回按钮/TabBar 行为正确）、弹窗/浮层（所有弹窗能正常触发和关闭）、滚动行为（长页面可滚动、吸顶元素正确固定）、三态占位（loading/empty/error 三种状态有对应 UI 结构）
2. THE 结构还原验证 SHALL 9 项全部通过后才可进入 Step 6 像素级对比
3. IF 结构还原验证未通过，THEN THE 迁移流程 SHALL 记录问题、修复、重新验证，循环直到全部通过

需求 19：像素级视觉对比（Step 6）

用户故事： 作为迁移执行者，我希望通过工具链量化小程序与 H5 原型的视觉差异，以系统性地收敛渲染偏差。

验收标准

1. WHEN 结构还原验证全部通过后，THE 像素级对比 SHALL 按以下流程执行：截图（微信开发者工具）→ 尺寸统一（H5 保持 1290px 宽，MP ×2 缩放到 1290px）→ pixelmatch 对比 → 差异分析（按 150px 条带分析差异密度）→ 定位差异区域 → WXSS 微调 → 循环
2. THE 像素级对比 SHALL 以前半屏差异率 < 5% 为优秀、≤ 10% 为达标的标准评估
3. THE 像素级对比 SHALL 每轮控制 2-5 处修改，避免一次改太多难以定位效果
4. THE 像素级对比 SHALL 优先使用 flex/盒模型的确定性方案，禁止使用"碰运气"的魔法数
5. THE 像素级对比 SHALL 确保 rpx 换算统一，禁止同一类间距混用 rpx 和 px
6. WHEN 需要对比交互态时，THE 像素级对比 SHALL 对弹窗/筛选/空状态等交互态进行视觉检查（弹窗位置、遮罩透明度），交互态不要求像素精确

需求 20：验收签收（Step 7）

用户故事： 作为项目管理者，我希望每个页面迁移完成后通过 12 项验收清单，以确保交付质量。

验收标准

1. THE 验收签收 SHALL 逐项检查以下 12 项：编译零报错、默认态像素对比差异率 ≤ 10%、关键交互态截图齐全、87.5% 缩放一致（抽查 3 个关键元素）、颜色 Token 一致（使用 design-tokens.json 定义的颜色）、TDesign 组件正确使用、共享组件复用、交互逻辑完整（对照 interactions/*.md）、空/错误/加载态已处理、真机预览（iOS + Android 各一台无异常）、导航正确（返回/跳转/TabBar 行为符合 PRD）、认证守卫（未登录自动跳转登录页）
2. WHEN 验收未通过时，THE 验收签收 SHALL 按问题严重度回退到对应步骤修复，修复后从回退步骤重新走完所有后续步骤
3. THE 验收签收 SHALL 确保每次返工修复后不引入新的编译错误（修 A 不坏 B）

需求 21：转换执行顺序

用户故事： 作为迁移执行者，我希望每个页面的代码转换按固定顺序执行，以确保依赖关系正确。

验收标准

1. THE 规则化转换（Step 3）SHALL 按以下顺序执行：创建 4 文件骨架（.wxml/.wxss/.ts/.json）→ .json 注册 usingComponents（TDesign + 自定义组件）→ 转换 WXML（标签映射，保持层级一致）→ 转换 WXSS（Tailwind→手写 WXSS，87.5% 缩放）→ 转换 TS（DOM→setData，事件→bindtap）→ Mock 数据（贴近真实 API 格式，标记 TODO）→ 三态处理（loading/empty/normal/error）
2. THE 每个页面 SHALL 输出到 apps/miniprogram/miniprogram/pages/<page>/ 目录下
3. WHEN 页面需要新的 SVG 图标时，THE 转换流程 SHALL 将 SVG 导出到 apps/miniprogram/miniprogram/assets/icons/ 目录

需求 22：task-detail 变体页面迁移策略

用户故事： 作为迁移执行者，我希望 task-detail 的 3 个主题色变体页面高效迁移，避免重复劳动。

验收标准

1. THE 迁移流程 SHALL 先完成 task-detail 主页面的完整迁移和验收
2. WHEN task-detail 验收通过后，THE 迁移流程 SHALL 通过复制 task-detail 并替换主题色变量的方式生成 task-detail-callback、task-detail-priority、task-detail-relationship 三个变体
3. THE 变体页面 SHALL 仅在以下方面与 task-detail 不同：banner 背景色、按钮配色、页面主题色（对照各自 H5 原型截图校准色值）
4. THE 变体页面 SHALL 保持与 task-detail 完全相同的数据结构和页面布局

需求 23：页面级功能需求 — A 批次（看板）

用户故事： 作为门店管理者，我希望在小程序中查看财务、助教、客户三个维度的看板数据，以便掌握门店经营状况。

验收标准

1. THE board-finance 页面 SHALL 包含：时间月份筛选（9 选项+指定周期，最大 366 天）+ 区域筛选（全部/大厅ABC/麻将房/团建房/具体台桌）、财务汇总行（实际收入/支出/净利润三列）、四个板块（营业数据/收入构成/支出构成/利润构成，每行 3 个指标卡片）、长按指标卡片启动助手对话、指标说明弹窗、目录导航面板
2. THE board-coach 页面 SHALL 包含：排序维度筛选（7 选项）+ 擅长项目筛选 + 时间月份筛选、助教卡片列表（姓名+等级+擅长项目 | 关系最好客户前三 | 排序维度数值）、点击卡片跳转助教详情页
3. THE board-customer 页面 SHALL 包含：客户类型筛选（8 维度）+ 偏爱项目筛选、客户卡片列表（名称+等级+VIP标识 | 最喜欢助教前三 | 核心指标+最近到店）、heart-icon 组件显示、最专一客户表格、点击卡片跳转客户详情页
4. THE board-coach 和 board-customer 页面 SHALL 使用 board-tab-bar 共享组件作为底部导航栏
5. THE 三个看板页面 SHALL 使用 filter-dropdown 共享组件实现筛选下拉

需求 24：页面级功能需求 — B 批次（核心）

用户故事： 作为助教用户，我希望在小程序首页查看任务列表和个人信息，以便快速了解待办事项和管理账户。

验收标准

1. THE task-list 页面 SHALL 包含：顶部自定义导航栏（标题"任务"，无返回按钮）、Banner 区（用户名+身份+业绩概览+预计收入，整块可点击跳转业绩详情页）、任务列表（单列，按紧急程度排序：红→橙→粉→蓝，不分组）、单条卡片（类型标签带颜色+客户姓名+右箭头+补充信息行）、长按卡片弹出黑底浮层菜单（任务置底/问问助手/备注）、备注弹窗、空状态"暂无任务"
2. THE my-profile 页面 SHALL 包含：顶部用户信息区、列表菜单（备注记录/助手对话记录/首页设置/退出账号）
3. THE task-list 和 my-profile 页面 SHALL 作为 TabBar 页面，使用 wx.switchTab 跳转

需求 25：页面级功能需求 — C 批次（任务详情）

用户故事： 作为助教用户，我希望查看任务详情（含客户信息、消费习惯、关系等级、任务建议），以便有针对性地服务客户。

验收标准

1. THE task-detail 页面 SHALL 包含：客户基本信息模块 → 消费习惯模块 → 与我的关系模块（等级+说明）→ 任务建议模块、底部固定栏（问问助手+备注按钮）、放弃任务确认弹窗、备注弹窗
2. THE task-detail-callback、task-detail-priority、task-detail-relationship 页面 SHALL 与 task-detail 保持相同的数据结构和布局，仅 banner 背景色和按钮配色不同

需求 26：页面级功能需求 — D 批次（详情页）

用户故事： 作为门店管理者，我希望查看助教和客户的详细信息及服务记录，以便深入了解业务情况。

验收标准

1. THE coach-detail 页面 SHALL 包含：基本信息模块 → 流水与业绩模块 → 工资与上课时长模块 → 前 10 客户指数列表、底部固定栏（问问助手+备注）、备注弹窗
2. THE customer-detail 页面 SHALL 包含：基本信息模块 → 消费习惯模块（标签+文本）→ 与我的关系模块（等级+说明）、底部固定栏（问问助手+备注）
3. THE customer-service-records 页面 SHALL 展示客户的服务记录列表

需求 27：页面级功能需求 — E 批次（绩效）

用户故事： 作为助教用户，我希望查看本月业绩总览和明细，以便了解自己的工作成果和收入情况。

验收标准

1. THE performance 页面 SHALL 包含：顶部 Banner（用户名+身份+本月业绩进度+预计收入）、多组指标两列卡片网格（收入构成/台球助教业绩/充值业绩/酒水业绩）、指标卡片（名称+当前值+目标值+完成度%）、仅展示本月数据（无时间切换）
2. THE performance-records 页面 SHALL 展示业绩明细列表

需求 28：页面级功能需求 — F 批次（对话）

用户故事： 作为用户，我希望与 AI 助手对话并查看历史对话记录，以便获取业务建议和回顾历史咨询。

验收标准

1. THE chat 页面 SHALL 包含：仿微信对话界面（左助手气泡/右用户气泡）、引用内容（灰底小卡片：来源类型+标题+摘要）、输入区（文本框+按住说话语音转文字+发送按钮）、会话管理（超 1 小时提示"新对话主题/继续对话"）
2. THE chat-history 页面 SHALL 包含：对话列表（对话标题+最近时间+消息条数，按更新时间倒序）、点击打开对应会话并滚动到最后一条

需求 29：页面级功能需求 — G 批次（其他）

用户故事： 作为用户，我希望查看所有备注记录，以便回顾之前对客户和任务的备注。

验收标准

1. THE notes 页面 SHALL 包含：备注列表按时间倒序平铺、每条备注显示：备注全文+关联对象+创建时间、不支持编辑/删除功能
2. THE notes 页面 SHALL 对已有历史实现按标准流程重新审计验收

需求 30：认证守卫与开发联调

用户故事： 作为迁移执行者，我希望小程序页面在开发阶段能正常联调后端 API，且未登录时自动跳转登录页。

验收标准

1. THE 每个业务页面 SHALL 在加载时检查登录态，未登录时自动跳转登录页
2. WHEN 开发联调时，THE 小程序 SHALL 通过 utils/request.ts 中的 BASE_URL 指向 http://localhost:8000
3. WHEN 开发联调时，THE 后端 SHALL 启用 WX_DEV_MODE=true 开发模式，支持 /api/xcx/dev-login Mock 登录
4. THE 小程序 SHALL 使用 Storage + header token 方式维持登录态（小程序无 Cookie）

需求 31：全局设计规范

用户故事： 作为用户，我希望小程序的视觉风格和交互模式在所有页面保持一致。

验收标准

1. THE 小程序 SHALL 使用简体中文，金额元取整，万元保留两位小数
2. THE 小程序 SHALL 使用底部 TabBar 导航：任务（task-list）/ 看板（board-finance）/ 我的（my-profile）
3. THE 二级/详情页 SHALL 隐藏原生导航栏，使用自定义头部（左上角返回图标）
4. THE 所有业务页面 SHALL 在右下角显示 AI 悬浮助手按钮，点击进入助手对话页
5. THE 错误态 SHALL 统一显示"加载失败，请点击重试"+ 重试按钮
6. THE 空数据态 SHALL 使用纯文字提示（无插画）
7. THE 加载态 SHALL 使用"加载中..."纯文字（无骨架屏）

需求 32：AI 图标配色系统

用户故事： 作为用户，我希望页面中的 AI 标识每次加载时随机呈现不同配色，整页统一，增加视觉新鲜感。

验收标准

1. THE AI 图标配色系统 SHALL 支持 6 种配色方案（红/橙/黄/蓝/靛/紫），每种配色通过 CSS 变量定义渐变色对（--ai-from/--ai-to/--ai-from-deep/--ai-to-deep），色值参照 docs/h5_ui/css/ai-icons.css 中的定义
2. THE AI 图标配色系统 SHALL 包含两个系列的 AI 标识：
   • ai-inline-icon：行首小图标（H5 16px → 28rpx），渐变背景 + 白色机器人 SVG + 微光扫过动画（12s 周期）
   • ai-title-badge：标题行右侧标识（浅色背景 + 主题色文字 + 主题色边框 + 呼吸脉冲动画 3s 周期 + 高光扫过 14s 周期）
3. WHEN 页面加载时，THE 配色系统 SHALL 从 6 种配色中随机选取一种，统一应用到该页面所有 ai-inline-icon 和 ai-title-badge 元素，确保同一页面内所有 AI 标识使用同一配色
4. THE ai-float-button（悬浮按钮）SHALL 不参与随机配色，保持固定渐变动画（#667eea → #764ba2 → #f093fb → #f5576c）
5. THE 配色系统 SHALL 在小程序中通过页面级 onLoad 随机选色并 setData 传递 class 名的方式实现（替代 H5 的 DOM querySelectorAll + classList.add）
6. THE 机器人 SVG 图标 SHALL 复用已有的 assets/icons/ai-robot.svg（大系列）和导出对应的小系列 SVG，不重新生成

需求 33：迁移产出物管理

用户故事： 作为项目管理者，我希望迁移过程中的所有产出物（审计报告、截图、diff 图）有序归档，以便追溯和复查。

验收标准

1. THE 迁移工程 SHALL 将 H5 原型截图保留在 docs/h5_ui/screenshots/ 目录（只读输入物），命名规则：默认态 <page>.png、交互态 <page>--<state>.png；迁移过程中禁止向此目录写入 MP 截图或 diff 图
2. THE 迁移工程 SHALL 将小程序截图按页面分子目录存放在 docs/h5_ui/mp-screenshots/<page>/ 目录，命名规则：默认态 <page>.png、交互态 <page>--<state>.png、逐段截图 seg-<N>-<section>.png
3. THE 迁移工程 SHALL 将 H5 逐段截图按页面分子目录存放在 docs/h5_ui/h5-segments/<page>/ 目录，命名规则：seg-<N>-<section>.png
4. THE 迁移工程 SHALL 将像素对比结果按页面分子目录存放在 docs/h5_ui/diffs/<page>/ 目录，包含：全屏 diff 图 diff-<page>.png、逐段 diff 图 diff-seg-<N>-<section>.png、对比报告 report.md（差异率 + 问题区域摘要）
5. THE 迁移工程 SHALL 将新导出的 SVG 图标存放在 apps/miniprogram/miniprogram/assets/icons/ 目录
6. WHEN 迁移新页面导出新 SVG 时，THE 迁移工程 SHALL 更新 docs/h5_ui/icon-mapping.md 图标映射表
7. THE 迁移工程 SHALL 确保小程序代码输出到 apps/miniprogram/miniprogram/pages/<page>/ 目录结构下
8. THE 像素精调循环中，每轮新截图 SHALL 覆盖上一轮同名文件，不保留历史版本（依赖 git 追溯历史）