微信小程序页面迁移校验之前 P5任务处理之前
This commit is contained in:
1
.kiro/specs/h5-miniprogram-migration/.config.kiro
Normal file
1
.kiro/specs/h5-miniprogram-migration/.config.kiro
Normal file
@@ -0,0 +1 @@
|
||||
{"specId": "cd30e87b-ce7a-4ff5-8587-f5ae75013e58", "workflowType": "requirements-first", "specType": "feature"}
|
||||
552
.kiro/specs/h5-miniprogram-migration/design.md
Normal file
552
.kiro/specs/h5-miniprogram-migration/design.md
Normal file
@@ -0,0 +1,552 @@
|
||||
# 技术设计文档：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 图
|
||||
424
.kiro/specs/h5-miniprogram-migration/requirements.md
Normal file
424
.kiro/specs/h5-miniprogram-migration/requirements.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# 需求文档：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 追溯历史）
|
||||
321
.kiro/specs/h5-miniprogram-migration/tasks.md
Normal file
321
.kiro/specs/h5-miniprogram-migration/tasks.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 实现计划：H5 → 微信小程序批量迁移
|
||||
|
||||
## 概述
|
||||
|
||||
基于 33 条需求和技术设计文档，将 17 个 H5 原型页面迁移为原生微信小程序页面。按 A-G 七个批次执行，每页走完 7 步标准流程（含 Step 0 页面分析）。输入物分两批提供：第一批（结构迁移 Step 0-5）、第二批（像素精调 Step 6-7）。
|
||||
|
||||
## 任务
|
||||
|
||||
- [ ] 1. 全局基础设施搭建
|
||||
- [ ] 1.1 创建 AI 图标配色工具模块
|
||||
- 文件：`utils/ai-color.ts`
|
||||
- 实现 `AI_COLOR_SCHEMES` 常量（6 种配色：red/orange/yellow/blue/indigo/purple）
|
||||
- 实现 `getRandomAiColor()` 函数，返回 `{ className, vars }` 对象
|
||||
- _需求: 32.1, 32.3, 32.5_
|
||||
|
||||
- [ ] 1.2 创建 AI 图标全局 WXSS 样式
|
||||
- 在 `app.wxss` 中添加 `.ai-inline-icon`、`.ai-title-badge`、`.ai-color-*` 6 个配色类
|
||||
- 实现 `ai-shimmer`（12s）和 `ai-pulse`（3s）两个 `@keyframes` 动画
|
||||
- _需求: 32.1, 32.2_
|
||||
|
||||
- [ ] 1.3 导出小系列机器人 SVG
|
||||
- 从 H5 源码提取白色填充版机器人 SVG，保存为 `assets/icons/ai-robot-sm.svg`
|
||||
- 复用已有 `assets/icons/ai-robot.svg`（大系列）
|
||||
- 更新 `docs/h5_ui/icon-mapping.md`
|
||||
- _需求: 32.6, 33.2, 33.3_
|
||||
|
||||
- [ ] 1.4 创建中间生成物目录结构
|
||||
- 创建 `docs/h5_ui/mp-screenshots/`（MP 截图，按页面分子目录）
|
||||
- 创建 `docs/h5_ui/diffs/`（像素对比结果，按页面分子目录）
|
||||
- 创建 `docs/h5_ui/h5-segments/`（H5 逐段截图，按页面分子目录）
|
||||
- 确认 `.gitignore` 不排除这些目录
|
||||
- _需求: 33.1_
|
||||
|
||||
- [ ] 1.5 验证全局基础设施
|
||||
- 编译验证 `app.wxss` 无警告
|
||||
- 在任意已有页面中测试 AI 配色工具模块可正常导入和调用
|
||||
- _需求: 17.1_
|
||||
|
||||
- [ ] 2. A 批次 — board-finance（看板-财务）
|
||||
- [ ] 2.1 Step 0: 页面分析
|
||||
- 打开 H5 原型截图 + `interactions/board-finance.md`
|
||||
- 确认屏数（预计 6 段：经营一览/预收资产/应计收入/现金流入/现金流出/助教分析）
|
||||
- 列出所有交互态（时间筛选/区域筛选/指标弹窗/目录面板/长按菜单）
|
||||
- 输出工作量估算表
|
||||
- _需求: 1.1, 1.3_
|
||||
|
||||
- [ ] 2.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- 冻结第一批输入物（Playbook + design-tokens + icon-mapping + HTML + CSS + interactions）
|
||||
- 输出《迁移审计报告》7 项（页面结构/CSS 风险/样式映射/图标处理/交互映射/外部依赖/缺失信息）
|
||||
- _需求: 3.1, 3.2, 4.1, 4.2, 4.3_
|
||||
|
||||
- [ ] 2.3 Step 3: 规则化转换（按屏逐个开发）
|
||||
- 创建四文件骨架 → .json 注册组件 → 按屏转换 WXML/WXSS/TS
|
||||
- 包含：filter-dropdown 复用、metric-card 复用、ai-float-button 集成
|
||||
- filter-bar 高度统一 70 逻辑像素
|
||||
- Mock 数据 + 三态处理
|
||||
- _需求: 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 21, 23.1, 32_
|
||||
|
||||
- [ ] 2.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- 7 项编译检查（WXML/WXSS/控制台/图片/组件/路由/TS 类型）
|
||||
- 9 项结构核对（按屏逐个验证）
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 2.5 Step 6-7: 像素精调 + 验收签收
|
||||
- 补充第二批输入物（computed-styles + 截图）
|
||||
- 使用 anchor_compare.py v2 逐段对比
|
||||
- H5 逐段截图 → `docs/h5_ui/h5-segments/board-finance/`
|
||||
- MP 逐段截图 → `docs/h5_ui/mp-screenshots/board-finance/`
|
||||
- Diff 图 → `docs/h5_ui/diffs/board-finance/`
|
||||
- 输出 `docs/h5_ui/diffs/board-finance/report.md`（差异率 + 问题区域）
|
||||
- 每轮 2-5 处修改，循环至差异率 ≤ 10%
|
||||
- 12 项验收清单
|
||||
- _需求: 3.3, 19, 20_
|
||||
|
||||
- [ ] 3. A 批次 — board-coach（看板-助教）
|
||||
- [ ] 3.1 Step 0: 页面分析
|
||||
- 确认屏数、交互态（排序筛选/擅长项目筛选/时间筛选）
|
||||
- _需求: 1.1, 1.3_
|
||||
|
||||
- [ ] 3.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- _需求: 3.1, 3.2, 4_
|
||||
|
||||
- [ ] 3.3 Step 3: 规则化转换
|
||||
- 包含：board-tab-bar 复用、filter-dropdown 复用
|
||||
- _需求: 5-16, 21, 23.2, 23.4, 23.5, 32_
|
||||
|
||||
- [ ] 3.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 3.5 Step 6-7: 像素精调 + 验收签收
|
||||
- _需求: 19, 20_
|
||||
|
||||
- [ ] 4. A 批次 — board-customer（看板-客户）
|
||||
- [ ] 4.1 Step 0: 页面分析
|
||||
- 确认屏数、交互态（客户类型筛选/偏爱项目筛选）
|
||||
- _需求: 1.1, 1.3_
|
||||
|
||||
- [ ] 4.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- _需求: 3.1, 3.2, 4_
|
||||
|
||||
- [ ] 4.3 Step 3: 规则化转换
|
||||
- 包含：board-tab-bar 复用、filter-dropdown 复用、heart-icon 复用、hobby-tag 复用
|
||||
- _需求: 5-16, 21, 23.3, 23.4, 23.5, 32_
|
||||
|
||||
- [ ] 4.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 4.5 Step 6-7: 像素精调 + 验收签收
|
||||
- _需求: 19, 20_
|
||||
|
||||
- [ ] 5. 检查点 A — 看板批次验收
|
||||
- 确认 3 个看板页面全部通过 12 项验收清单
|
||||
- 确认共享组件（filter-dropdown、board-tab-bar、metric-card、heart-icon）在实际页面中表现正常
|
||||
- 确认 AI 图标配色系统在看板页面中正常工作
|
||||
- 总结 A 批次经验，调整后续批次策略（如有）
|
||||
|
||||
- [ ] 6. B 批次 — task-list（任务列表）
|
||||
- [ ] 6.1 Step 0: 页面分析
|
||||
- 确认屏数、交互态（长按菜单/备注弹窗/空状态）
|
||||
- _需求: 1.1_
|
||||
|
||||
- [ ] 6.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- _需求: 3, 4_
|
||||
|
||||
- [ ] 6.3 Step 3: 规则化转换
|
||||
- 包含：banner 复用、note-modal 复用、ai-float-button 集成
|
||||
- 长按菜单实现（bindlongpress + 黑底圆角浮层）
|
||||
- TabBar 页面路由配置
|
||||
- _需求: 5-16, 21, 24.1, 13, 32_
|
||||
|
||||
- [ ] 6.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 6.5 Step 6-7: 像素精调 + 验收签收
|
||||
- _需求: 19, 20_
|
||||
|
||||
- [ ] 7. B 批次 — my-profile（个人中心）
|
||||
- [ ] 7.1 Step 0: 页面分析
|
||||
- _需求: 1.1_
|
||||
|
||||
- [ ] 7.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- _需求: 3, 4_
|
||||
|
||||
- [ ] 7.3 Step 3: 规则化转换
|
||||
- TabBar 页面路由配置
|
||||
- _需求: 5-16, 21, 24.2, 24.3, 32_
|
||||
|
||||
- [ ] 7.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 7.5 Step 6-7: 像素精调 + 验收签收
|
||||
- _需求: 19, 20_
|
||||
|
||||
- [ ] 8. 检查点 B — 核心批次验收
|
||||
- 确认 task-list 和 my-profile 通过验收
|
||||
- 确认 TabBar 导航在三个 TabBar 页面间切换正常
|
||||
- 确认长按菜单交互正常（长按 vs 点击互不干扰）
|
||||
|
||||
- [ ] 9. C 批次 — task-detail（任务详情主页面）
|
||||
- [ ] 9.1 Step 0: 页面分析
|
||||
- 确认屏数、交互态（放弃弹窗/备注弹窗/底部固定栏）
|
||||
- _需求: 1.1_
|
||||
|
||||
- [ ] 9.2 Step 1-2: 输入物冻结 + 迁移审计
|
||||
- _需求: 3, 4_
|
||||
|
||||
- [ ] 9.3 Step 3: 规则化转换
|
||||
- 包含：note-modal 复用、ai-float-button 集成、底部固定栏
|
||||
- _需求: 5-16, 21, 25.1, 32_
|
||||
|
||||
- [ ] 9.4 Step 4-5: 编译验证 + 结构还原验证
|
||||
- _需求: 17, 18_
|
||||
|
||||
- [ ] 9.5 Step 6-7: 像素精调 + 验收签收
|
||||
- _需求: 19, 20_
|
||||
|
||||
- [ ] 10. C 批次 — task-detail 三个变体
|
||||
- [ ] 10.1 复制 task-detail 生成 task-detail-callback
|
||||
- 复制四文件 → 替换 banner 背景色 + 按钮配色
|
||||
- _需求: 22.2, 22.3, 22.4, 25.2_
|
||||
|
||||
- [ ] 10.2 复制 task-detail 生成 task-detail-priority
|
||||
- _需求: 22.2, 22.3, 22.4, 25.2_
|
||||
|
||||
- [ ] 10.3 复制 task-detail 生成 task-detail-relationship
|
||||
- _需求: 22.2, 22.3, 22.4, 25.2_
|
||||
|
||||
- [ ] 10.4 三个变体编译验证 + 像素校准
|
||||
- 对照各自 H5 原型截图校准色值
|
||||
- _需求: 17, 19, 20_
|
||||
|
||||
- [ ] 11. 检查点 C — 任务批次验收
|
||||
- 确认 task-detail + 3 个变体全部通过验收
|
||||
- 确认从 task-list 点击卡片可正确跳转到对应变体页面
|
||||
|
||||
- [ ] 12. D 批次 — coach-detail（助教详情）
|
||||
- [ ] 12.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 12.2 Step 3: 规则化转换
|
||||
- 包含：note-modal 复用、ai-float-button 集成、底部固定栏
|
||||
- _需求: 5-16, 21, 26.1, 32_
|
||||
|
||||
- [ ] 12.3 Step 4-7: 编译验证 → 结构还原 → 像素精调 → 验收
|
||||
- _需求: 17, 18, 19, 20_
|
||||
|
||||
- [ ] 13. D 批次 — customer-detail（客户详情）
|
||||
- [ ] 13.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 13.2 Step 3: 规则化转换
|
||||
- 包含：hobby-tag 复用、ai-float-button 集成、底部固定栏
|
||||
- _需求: 5-16, 21, 26.2, 32_
|
||||
|
||||
- [ ] 13.3 Step 4-7: 编译验证 → 结构还原 → 像素精调 → 验收
|
||||
- _需求: 17, 18, 19, 20_
|
||||
|
||||
- [ ] 14. D 批次 — customer-service-records（客户服务记录）
|
||||
- [ ] 14.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 14.2 Step 3-7: 规则化转换 → 编译 → 结构 → 像素 → 验收
|
||||
- _需求: 5-21, 26.3, 32_
|
||||
|
||||
- [ ] 15. 检查点 D — 详情批次验收
|
||||
- 确认 3 个详情页全部通过验收
|
||||
- 确认从看板页面点击卡片可正确跳转到对应详情页
|
||||
|
||||
- [ ] 16. E 批次 — performance（业绩总览）
|
||||
- [ ] 16.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 16.2 Step 3: 规则化转换
|
||||
- 包含：banner 复用、metric-card 复用、ai-float-button 集成
|
||||
- _需求: 5-16, 21, 27.1, 32_
|
||||
|
||||
- [ ] 16.3 Step 4-7: 编译验证 → 结构还原 → 像素精调 → 验收
|
||||
- _需求: 17, 18, 19, 20_
|
||||
|
||||
- [ ] 17. E 批次 — performance-records（业绩明细）
|
||||
- [ ] 17.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 17.2 Step 3-7: 规则化转换 → 编译 → 结构 → 像素 → 验收
|
||||
- _需求: 5-21, 27.2, 32_
|
||||
|
||||
- [ ] 18. 检查点 E — 绩效批次验收
|
||||
- 确认 2 个绩效页全部通过验收
|
||||
- 确认从 task-list Banner 可跳转到 performance 页面
|
||||
|
||||
- [ ] 19. F 批次 — chat（AI 对话）
|
||||
- [ ] 19.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 19.2 Step 3: 规则化转换
|
||||
- 仿微信对话界面（左助手/右用户气泡）
|
||||
- 引用内容卡片、输入区（文本框 + 语音按钮 + 发送）
|
||||
- scroll-view 消息区（独立滚动）
|
||||
- _需求: 5-16, 21, 28.1, 32_
|
||||
|
||||
- [ ] 19.3 Step 4-7: 编译验证 → 结构还原 → 像素精调 → 验收
|
||||
- _需求: 17, 18, 19, 20_
|
||||
|
||||
- [ ] 20. F 批次 — chat-history（对话历史）
|
||||
- [ ] 20.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- _需求: 1.1, 3, 4_
|
||||
|
||||
- [ ] 20.2 Step 3-7: 规则化转换 → 编译 → 结构 → 像素 → 验收
|
||||
- _需求: 5-21, 28.2, 32_
|
||||
|
||||
- [ ] 21. 检查点 F — 对话批次验收
|
||||
- 确认 chat 和 chat-history 通过验收
|
||||
- 确认从 ai-float-button 可跳转到 chat 页面
|
||||
- 确认从 chat-history 点击可打开对应会话
|
||||
|
||||
- [ ] 22. G 批次 — notes（备忘录）
|
||||
- [ ] 22.1 Step 0-2: 页面分析 + 输入物冻结 + 迁移审计
|
||||
- 已有历史实现，按标准流程重新审计
|
||||
- _需求: 1.1, 1.3, 3, 4_
|
||||
|
||||
- [ ] 22.2 Step 3-7: 规则化转换 → 编译 → 结构 → 像素 → 验收
|
||||
- 包含：star-rating 复用
|
||||
- _需求: 5-21, 29, 32_
|
||||
|
||||
- [ ] 23. 检查点 G — 最终验收
|
||||
- 确认 notes 通过验收
|
||||
- 确认 my-profile 菜单中"备注记录"可跳转到 notes 页面
|
||||
|
||||
- [ ] 24. 全局收尾
|
||||
- [ ] 24.1 全量导航验证
|
||||
- 验证所有页面间的跳转路径正确（TabBar 切换、navigateTo、navigateBack）
|
||||
- 验证认证守卫（未登录自动跳转登录页）
|
||||
- _需求: 7, 20, 30, 31_
|
||||
|
||||
- [ ] 24.2 全量 AI 图标配色验证
|
||||
- 抽查 3-5 个页面，确认 AI 图标随机配色正常
|
||||
- 确认 ai-float-button 保持固定渐变（不参与随机）
|
||||
- _需求: 32_
|
||||
|
||||
- [ ] 24.3 icon-mapping.md 最终更新
|
||||
- 确认所有新导出的 SVG 已记录在 icon-mapping.md 中
|
||||
- _需求: 33.3_
|
||||
|
||||
- [ ] 24.4 中间生成物归档验证
|
||||
- 确认所有 MP 截图按页面分目录存放在 `docs/h5_ui/mp-screenshots/<page>/`
|
||||
- 确认所有 diff 图和 report.md 按页面分目录存放在 `docs/h5_ui/diffs/<page>/`
|
||||
- 确认所有 H5 逐段截图按页面分目录存放在 `docs/h5_ui/h5-segments/<page>/`
|
||||
- 确认 `docs/h5_ui/screenshots/` 目录未被写入 MP 截图或 diff 图（只读输入物）
|
||||
- 清理可能遗留在项目根目录或其他位置的临时截图文件
|
||||
- _需求: 33_
|
||||
|
||||
## 备注
|
||||
|
||||
- 每个页面的 Step 0（页面分析）输出工作量估算表，用户确认后再开始 Step 1
|
||||
- 输入物分两批：第一批（Step 0-5 结构迁移）、第二批（Step 6-7 像素精调）
|
||||
- 检查点任务用于批次间的质量门禁，确认通过后再进入下一批次
|
||||
- 有历史实现的页面（board-coach/customer/finance/notes）走审计→对比→修复→验收流程
|
||||
- task-detail 变体通过复制+替换主题色实现，不重复走完整流程
|
||||
- 所有需求编号引用 `requirements.md` 中的需求序号
|
||||
- 中间生成物（MP 截图/H5 逐段截图/diff 图）按页面分子目录存放，每轮覆盖更新，不保留历史版本
|
||||
- `docs/h5_ui/screenshots/` 为只读输入物目录，禁止写入迁移过程生成的文件
|
||||
Reference in New Issue
Block a user