# H5 原型迁移到微信小程序页面手册（PRD + 技术规范）

版本：v1.0  
适用项目：球房运营助手 H5 原型 → 原生微信小程序页面  
依据：对上传原型代码包的静态审阅（24 个 HTML 页面、6 个 CSS、8 个 JS、1 个图片资源）+ 微信小程序 / Tailwind 官方文档调研

---

## 1. 文档目标

本手册用于指导将现有 H5 原型页面迁移为**原生微信小程序页面**，目标是：

1. 仅关注**前端页面层**迁移，不讨论后端真实联调。
2. 除字体渲染差异外，尽量做到**视觉样式、布局、动效、交互反馈的 1:1 还原**。
3. 当前原型的验收基准设备等效宽度为 **412px**，迁移后以该宽度为第一验收基准。
4. 先完成 Tailwind/H5 表达方式到 WXML/WXSS/小程序 JS 的等价改写，再进入接口联调阶段。

---

## 2. 原型项目现状审阅结论

### 2.1 页面与模块盘点

经静态审阅，原型共包含以下主要页面：

#### 账号与权限
- `login.html` 登录
- `apply.html` 账号申请
- `reviewing.html` 审核中
- `no-permission.html` 无权限
- `home-settings.html` 首页设置
- `my-profile.html` 我的

#### 任务与客户维护
- `task-list.html` 任务列表
- `task-detail.html` 任务详情（主版）
- `task-detail-priority.html` 任务详情（优先召回）
- `task-detail-callback.html` 任务详情（客户回访）
- `task-detail-relationship.html` 任务详情（关系构建）
- `notes.html` 备注
- `chat.html` 助手对话
- `chat-history.html` 助手对话记录

#### 看板与数据
- `board-finance.html` 财务看板
- `board-customer.html` 客户看板
- `board-coach.html` 助教看板

#### 业绩与服务
- `performance.html` 业绩详情
- `performance-records.html` 业绩明细
- `customer-service-records.html` 客户服务记录
- `coach-detail.html` 助教详情
- `customer-detail.html` 客户详情

#### 其他
- `benchmark.html` 基准测试页
- `ai-icon-demo.html` AI 图标演示页

### 2.2 Tailwind 使用特征（基于代码扫描）

项目中 Tailwind 用法整体偏“静态 UI utility class”，迁移难度低于常见 React/Vue + Tailwind 项目：

- 唯一 class 数约 **788**。
- 大多数是**基础 utility**，如：`flex`、`px-4`、`rounded-xl`、`text-sm`、`shadow-sm`、`bg-white`。
- 存在少量 **arbitrary value**，如：
  - `text-[9px]`
  - `top-[44px]`
  - `flex-[2]`
  - `max-h-[70vh]`
- 存在少量状态变体：
  - `hover:*`
  - `focus:*`
  - `active:*`
  - `group-hover:*`
- **几乎未发现响应式断点类**（例如 `sm:` / `md:` / `lg:`），这对小程序迁移是利好。
- 页面还混用了较多**内联 style**与页面内 `<style>` 自定义 CSS。
- 交互主要依赖：
  - `onclick`
  - `addEventListener`
  - `querySelector`
  - `classList`
  - `getBoundingClientRect`
  - `window.scrollY`
  - `history.back()`

### 2.3 项目级风险判断

**结论：可迁移，而且是中等复杂度，不是高危重构。**

原因：

1. Tailwind 并没有被用到很深的响应式系统，主要是静态视觉表达。
2. 大量视觉效果本质仍是普通 CSS：圆角、阴影、渐变、sticky、safe-area、卡片、标签、徽章、列表。
3. 真正需要重写的是**DOM 事件与状态切换方式**，不是颜色和间距本身。
4. 高风险点集中在：
   - 安全区与导航高度
   - 长按菜单
   - 滚动联动吸顶/隐藏筛选栏
   - 评分拖动
   - 动画/过渡
   - `hover/group-hover/backdrop-blur/sticky` 等特性在小程序上的表现差异

---

## 3. 迁移目标定义（PRD 口径）

## 3.1 目标

将现有 H5 原型页面迁移为原生微信小程序页面，满足以下目标：

### A. 视觉目标
- 在验收基准机型（等效宽度 412px）上，页面视觉与原型对齐。
- 除字体渲染差异外，颜色、圆角、阴影、间距、层级、边框、图标、插画、Safe Area 处理必须尽可能一致。
- 卡片、标签、列表、弹窗、Toast、浮层、筛选器、看板区块的版式必须保持一致。

### B. 交互目标
- 页面切换逻辑、点击反馈、弹窗开合、滚动联动、吸顶、长按、复制、备注填写、评分、筛选切换等交互必须在小程序中按原型还原。
- 原型中的 CSS 动画 / 过渡动画，优先使用 WXSS transition/animation 或小程序动画 API 还原。
- 关键路径交互不允许出现明显掉帧、闪烁、层级错乱。

### C. 工程目标
- 不在小程序中继续依赖 Tailwind 运行时。
- 页面最终产物为：`wxml + wxss + js + json` 的原生页面结构。
- 建立统一设计 token、页面骨架规范、组件命名规范、数据字段命名规范。
- 为后续接口联调预留稳定的数据结构。

### D. 非目标
- 本阶段不做后端真实联调。
- 本阶段不处理业务规则正确性，只保证页面需要的数据结构和状态位定义完整。
- 本阶段不追求“复用 H5 DOM 代码”，而追求“可维护的小程序产物”。

---

## 4. 微信小程序技术边界（必须纳入迁移设计）

微信小程序的页面由 `WXML + WXSS + JS + JSON` 构成；其中 WXML 负责结构，WXSS 负责样式，JS 负责逻辑与数据更新。小程序运行环境分为**逻辑层**和**渲染层**，二者分线程管理，通信通过宿主转发，因此 Web DOM 式写法不能直接照搬。  
参考：
- WXML 模板：https://www.tencentcloud.com/zh/document/product/1219/60345
- WXSS 样式：https://www.tencentcloud.com/zh/document/product/1219/60346
- 小程序宿主环境：https://www.tencentcloud.com/zh/document/product/1219/61737

### 4.1 必须接受的基础事实

1. **不能直接操作浏览器 DOM**
   - H5 中的 `document.querySelector`、`classList.add/remove`、`createElement`、`history.back()` 都不能原样迁入。
   - 需要改为：
     - 结构：WXML 条件渲染 / 列表渲染
     - 事件：`bindtap`、`bindinput`、`catchtouchmove` 等
     - 状态：`setData` / 页面数据驱动
     - 导航：`wx.navigateTo` / `wx.navigateBack`

2. **WXSS 不是完整 CSS**
   - 支持类选择器、id 选择器、元素选择器、`::before`、`::after`，但选择器能力明显比 Web 更保守。
   - 复杂后代/兄弟选择器、依赖 hover 链路的样式方案，不应作为主要实现方式。
   - 样式应尽量转成“显式 class + 数据状态位”。

3. **尺寸体系建议转为 rpx**
   - WXSS 引入 `rpx`，在 375 物理像素宽度下 `1rpx = 1px`，用于适配不同屏宽。
   - 你的验收基准是 **412px**，因此本项目建议建立“412px 原型稿 → rpx”的专用换算规则，而不是照抄 375 的 H5 px 值。

4. **动画可用，但实现方式要改**
   - 简单过渡优先用 WXSS transition/animation。
   - 复杂过程动画可用 `wx.createAnimation`。
   - 官方说明中也明确提示：连续用 `setData` 做动画通常会造成延迟或卡顿，应避免作为常规方案。
   - 参考：
     - 动画 API：https://www.tencentcloud.com/zh/document/product/1219/57764
     - 渲染层 / 动画说明：https://www.tencentcloud.com/zh/document/product/1219/61744

5. **调试方式不同于浏览器**
   - 小程序开发者工具提供 Wxml、Network、Appdata、Mock、Compatibility 等能力；Wxml 面板可实时查看转换后的页面结构和样式。
   - 参考：https://www.tencentcloud.com/zh/document/product/1219/61764

---

## 5. 适配基线：以 412px 为验收稿的尺寸换算规范

## 5.1 换算原则

原型验收基准宽度：**412px**  
小程序全宽：**750rpx**

因此推荐主换算公式：

```text
rpx = H5_px × (750 / 412)
    ≈ H5_px × 1.820388
```

常用换算表：

| H5 px | WXSS rpx（建议） |
|---|---:|
| 1 | 2rpx |
| 2 | 4rpx |
| 4 | 8rpx |
| 6 | 11rpx |
| 8 | 15rpx |
| 10 | 18rpx |
| 12 | 22rpx |
| 14 | 25rpx |
| 16 | 29rpx |
| 18 | 33rpx |
| 20 | 36rpx |
| 24 | 44rpx |
| 28 | 51rpx |
| 32 | 58rpx |
| 36 | 66rpx |
| 40 | 73rpx |
| 44 | 80rpx |
| 48 | 87rpx |

## 5.2 尺寸使用建议

### 推荐用 rpx 的场景
- 宽高
- padding / margin
- 圆角
- 定位偏移
- 字号（多数文本）
- 列表项高度
- 卡片尺寸
- 筛选器高度
- 顶部安全区以下的视觉结构

### 保留 px 的场景
- 1px 发丝线（边框）
- 阴影模糊半径微调
- 小图标描边
- 少量动画位移的精细校准
- 受宿主影响的真实像素边界校准

### 禁止做法
- 页面里同时大量混用 px / rpx / rem / vw / vh，导致统一性失控。
- 直接把 Tailwind `px-*` 数值等比抄到 WXSS 中。
- 不经校准地把 `top-[44px]`、`text-[9px]` 这类 arbitrary value 逐个硬搬。

---

## 6. Tailwind → WXSS 的迁移策略

Tailwind 本身是根据源码中的类名生成 CSS，而不是一张固定大样式表；同时它支持 `@apply` 将 utility 内联为普通 CSS 类。  
参考：
- Styling with utility classes：https://tailwindcss.com/docs/styling-with-utility-classes
- Functions and directives (`@apply`)：https://tailwindcss.com/docs/functions-and-directives
- Responsive design：https://tailwindcss.com/docs/responsive-design
- Hover/focus/states：https://tailwindcss.com/docs/hover-focus-and-other-states

## 6.1 不建议的做法

### 方案 X：逐页面手工把 class 翻译成散装 WXSS
问题：
- 重复劳动巨大
- 样式 token 不统一
- 后续维护困难
- 同一个 `rounded-xl` 会被翻译成多个版本

## 6.2 建议的做法

### 方案 Y：先做“语义层收敛”，再做 WXSS 落地

步骤：

1. **抽取设计 token**
   - 颜色
   - 间距
   - 字号
   - 圆角
   - 阴影
   - 层级
   - 渐变
   - 安全区参数

2. **抽取公共组件 class**
   - `card`
   - `tag`
   - `metric`
   - `section-title`
   - `filter-chip`
   - `sheet`
   - `modal`
   - `toast`
   - `avatar`
   - `list-cell`
   - `sticky-bar`

3. **将 Tailwind utility 合并成语义类**
   - 例如：
     - `bg-white rounded-xl shadow-sm p-4` → `.card`
     - `px-2 py-0.5 text-xs rounded-full` → `.pill`
     - `flex items-center justify-between` → `.row-between`

4. **在小程序侧用语义类重新实现**
   - 不是把 `px-4 py-3 text-sm` 直接变成 `.px-4` `.py-3` `.text-sm` 的 utility 体系。
   - 而是重新组织为“组件样式 + 状态类”。

## 6.3 Tailwind 映射原则

### 低风险：可以直接映射
- `flex` / `items-center` / `justify-between`
- `rounded-*`
- `shadow-*`
- `border`
- `text-*`
- `font-*`
- `bg-*`
- `p-*` / `m-*`
- `w-*` / `h-*`
- `overflow-hidden`
- `truncate`
- `absolute` / `relative`
- `z-*`

### 中风险：需要验收校准
- `sticky`
- `backdrop-blur-*`
- 渐变背景
- `min-h-screen`
- `object-cover`
- 安全区相关 `env(safe-area-inset-*)`
- 精细字号（`text-[9px]` 等）

### 高风险：必须改写交互方案
- `hover:*`
- `group-hover:*`
- `focus:*`
- `active:*`（要确认组件是否支持按压态或改为显式状态）
- 依赖复杂结构关系的选择器
- 任意复杂 selector / arbitrary variant
- 用 DOM 操作实现的 class 切换

---

## 7. 页面结构迁移规范

## 7.1 HTML → WXML 标签映射

建议的基础映射：

| H5 标签 | 小程序建议组件 |
|---|---|
| `div` | `view` |
| `span` | `text` 或 `view` |
| `img` | `image` |
| `a` | `navigator` 或 `view + bindtap` |
| `button` | `button` 或 `view + bindtap` |
| `input` | `input` |
| `textarea` | `textarea` |
| `svg` | 优先转图片 / iconfont / 组件化 SVG 方案 |

说明：
- 你的原型中 SVG 使用非常多，建议优先做“图标资产整理”，不要在页面里散落大量内联 SVG。
- 高频图标应统一为：
  1. 字体图标
  2. SVG 组件化
  3. PNG/WebP 资源
  三选一，不建议混乱并存。

## 7.2 页面目录规范（建议）

```text
miniprogram/
  app.js
  app.json
  app.wxss
  styles/
    tokens.wxss
    mixins.wxss
    components.wxss
  components/
    nav-bar/
    bottom-tab/
    card/
    metric-card/
    modal/
    toast/
    score-stars/
    filter-sheet/
  pages/
    login/
    apply/
    reviewing/
    no-permission/
    home-settings/
    my-profile/
    task-list/
    task-detail/
    task-detail-priority/
    task-detail-callback/
    task-detail-relationship/
    notes/
    chat/
    chat-history/
    board-finance/
    board-customer/
    board-coach/
    performance/
    performance-records/
    customer-service-records/
    coach-detail/
    customer-detail/
```

## 7.3 组件拆分建议

### 必拆公共组件
- 顶部导航栏
- 底部 TabBar / 自定义底部导航
- 通用卡片
- 标签 / badge / pill
- Toast
- Modal / Bottom Sheet
- AI 图标组件
- 客户/助教头像组件
- 评分星级组件
- 筛选条
- 数据指标块
- 空状态
- 无权限/审核状态卡片

### 不建议过早组件化
- 只在一个页面出现一次且结构极度特殊的业务块
- 尚未稳定的数据看板 section

---

## 8. 交互迁移规范

## 8.1 原型里的交互类型

代码审阅后，原型中的核心交互包括：

1. 点击跳转
2. Tab 切换
3. 筛选器展开/收起
4. 吸顶与滚动隐藏/显示
5. 长按弹出上下文菜单
6. 备注弹窗
7. 放弃客户弹窗
8. Toast 提示
9. AI 对话复制
10. 星级评分拖动
11. 月份切换
12. 比较开关
13. “展开更多/收起”
14. 底部导航激活态
15. 模态遮罩点按关闭

## 8.2 H5 DOM 交互 → 小程序数据驱动规范

### 禁止
- `document.querySelector`
- `element.classList.add/remove`
- `createElement` 生成 UI
- `innerHTML` 拼接界面
- `history.back()`
- 直接依赖浏览器事件模型

### 统一改法
- 页面 data 维护 UI 状态：
  - `showModal`
  - `activeTab`
  - `showFilter`
  - `selectedSort`
  - `selectedTimeRange`
  - `showToast`
  - `toastText`
  - `noteDraft`
  - `animationState`
- WXML 用条件渲染：
  - `wx:if`
  - `hidden`
  - `wx:for`
- 事件统一使用：
  - `bindtap`
  - `bindinput`
  - `bindchange`
  - `bindscroll`
  - `catchtouchmove`

## 8.3 长按菜单迁移

原型中 `task-list.html` 存在长按任务卡弹出上下文菜单的逻辑，且带“超过阈值判定移动、避免滑动误触”的处理。

### 风险
- 小程序端长按与滚动手势容易冲突。
- 不同机型触摸响应差异会更明显。
- 如果实现方式不对，列表滚动会卡或误触发频繁。

### 规范
1. 首选使用小程序支持的长按事件能力或触摸起止时序封装。
2. 菜单位置不要依赖浏览器 `clientX/clientY` 原样逻辑，改为：
   - 卡片锚点定位
   - 或简化为底部 action sheet
3. 若一定要做“锚点浮出菜单”，需用 selectorQuery 获取节点位置信息后定位。
4. 长按菜单必须有：
   - 遮罩点击关闭
   - 滚动时自动关闭
   - 跳页时自动关闭
   - 二次确认动作（例如放弃）

**建议：**
业务上允许的话，优先改成**底部 action sheet**，兼容性和可维护性更高。

## 8.4 吸顶 / 滚动联动筛选栏迁移

看板页中存在较复杂的：
- sticky 区块
- 下滑显示 / 上滑隐藏
- 阈值触发
- section 感知
- 导航同步

### 风险
- 小程序的滚动事件节奏与浏览器不同。
- 高频 `setData` 会引发掉帧。
- 如果把滚动值持续同步到很多节点，性能会明显下降。

### 规范
1. 先确认是否能纯 CSS / sticky 完成。
2. 必须 JS 联动时，只更新少量状态位：
   - `showFilterBar`
   - `currentSectionIndex`
   - `stickyTitle`
3. 滚动事件里要做节流，避免每帧 `setData`。
4. 将复杂 section 计算封装为单独工具函数。
5. 验收重点放在：
   - 回弹时状态是否抖动
   - 快速滑动是否闪烁
   - iOS / Android 表现是否一致

## 8.5 评分拖动迁移

原型中的星级评分通过 `touchstart/touchmove` + `getBoundingClientRect` 计算。

### 风险
- 小程序可实现，但细节容易出现触摸偏移。
- 如果星星是循环渲染，需要注意 index 与坐标换算一致。
- 拖动评分时要阻止页面滚动干扰。

### 规范
1. 保留“点击即评分”作为基本能力。
2. 拖动评分作为增强能力。
3. 星级区单独封装组件。
4. 组件输出：
   - `score`
   - `onChange`
5. 如拖动体验不稳定，可退化为“点击打分”，但点击命中精度必须足够。

## 8.6 动画与过渡迁移

### 原型现状
原型中有：
- `transition`
- `@keyframes`
- `opacity`
- `transform`
- `scale`
- `translateY`
- badge 动画
- 下拉浮层出现动画
- 浮动图形动画

### 建议实现优先级
1. **第一优先**：WXSS transition / animation
2. **第二优先**：`wx.createAnimation`
3. **第三优先**：必要时再考虑更复杂的方案

### 原则
- 能用样式动画解决的，不用 JS 驱动。
- 不要用连续 `setData` 逐帧更新位置。
- 复杂动画仅应用于关键体验点，不要全页过度动效。

---

## 9. 样式系统规范

## 9.1 设计 token（建议首批固化）

### 颜色
根据原型中的 Tailwind config，建议建立如下 token：

```css
--color-primary: #0052d9;
--color-primary-light: #ecf2fe;
--color-success: #00a870;
--color-warning: #ed7b2f;
--color-error: #e34d59;

--color-gray-1: #f3f3f3;
--color-gray-2: #eeeeee;
--color-gray-3: #e7e7e7;
--color-gray-4: #dcdcdc;
--color-gray-5: #c5c5c5;
--color-gray-6: #a6a6a6;
--color-gray-7: #8b8b8b;
--color-gray-8: #777777;
--color-gray-9: #5e5e5e;
--color-gray-10: #4b4b4b;
--color-gray-11: #393939;
--color-gray-12: #2c2c2c;
--color-gray-13: #242424;
```

### 圆角
- `radius-sm = 8rpx`
- `radius-md = 12rpx`
- `radius-lg = 16rpx`
- `radius-xl = 24rpx`
- `radius-2xl = 32rpx`
- `radius-pill = 999rpx`

### 间距
以 412px → 750rpx 换算后建立 4 进制或 2 进制 spacing system。

### 阴影
建议收敛为 3 档：
- `shadow-sm`
- `shadow-md`
- `shadow-lg`

### 字号
建议固定 8 档，不要维持太多 arbitrary 值：
- 20rpx
- 22rpx
- 24rpx
- 26rpx
- 28rpx
- 30rpx
- 32rpx
- 36rpx

## 9.2 页面级样式原则

1. 页面不得继续散落大量 utility class 的“翻译遗迹”。
2. 页面样式必须优先引用公共 token 与公共组件样式。
3. 同一种卡片在所有页面必须同源。
4. 渐变必须统一沉淀为命名类，不得每页重复抄写。
5. 模态层 / 遮罩层 / Toast / Sheet 的层级必须全局统一。

---

## 10. 本项目的高风险点清单（结合原型）

## 10.1 安全区与顶部导航

原型大量使用：

- `env(safe-area-inset-top, 44px)`
- sticky 顶部区
- 自定义导航高度 44px

### 风险
- 不同设备安全区表现不同。
- 真实小程序导航栏处理与浏览器不同。
- 若自定义导航方案不统一，页面顶部将出现抖动或错位。

### 处理规范
1. 全项目统一导航方案：
   - 使用系统导航
   - 或使用 `navigationStyle: custom` + 自定义导航
   二选一，不要混用。
2. 若用自定义导航，需统一读取状态栏高度并建立全局变量。
3. 所有带 safe-area 的页面共用同一套 nav 容器组件。

## 10.2 `backdrop-blur`

原型多处用到半透明毛玻璃头像框、信息面板、徽章背景。

### 风险
- 小程序端不同基础库 / 机型表现不稳定。
- 部分场景模糊成本高，可能影响滚动性能。
- 很难保证和 H5 一样细腻。

### 策略
1. 先评估是否必须保留真实 blur。
2. 若视觉允许，优先退化为：
   - 半透明纯色
   - 半透明渐变
   - 轻阴影 + 边框
3. 只在头图等少数关键区域保留 blur。

## 10.3 Sticky + 滚动吸附

看板页、聊天页、备注页都存在 sticky 或接近 sticky 的体验。

### 风险
- 多层 sticky 套叠时容易层级错乱。
- 自定义导航 + sticky + scroll-view 容器组合易出 bug。
- 开发工具表现和真机可能不同。

### 策略
- 每页只保留必要的 sticky 层。
- 能用页面自然滚动就不要强行塞进多层 `scroll-view`。
- 验收以真机为主，开发者工具仅作辅助。

## 10.4 SVG 图标资产

原型内联 SVG 很多。

### 风险
- 直接原封不动搬运会导致 WXML 臃肿。
- 图标难统一管理。
- 不利于后续主题化和复用。

### 策略
建立统一图标资产目录，按以下优先级处理：
1. 高频图标 → 组件化
2. 装饰图标 → 静态资源
3. AI 图标体系 → 单独组件封装

## 10.5 `hover` / `group-hover`

原型中虽不多，但确实存在。

### 风险
- 小程序主场景是触屏，不应依赖 hover 作为交互成立条件。
- 原型中的 hover 只能作为 Web 辅助状态，迁移时要改为：
  - 常态
  - 按压态
  - 激活态
  的显式逻辑

## 10.6 长列表与看板性能

财务、客户、助教看板都可能发展成长列表与大卡片页面。

### 风险
- 频繁 setData
- 过多阴影与渐变
- 多个 sticky / 浮层并存
- 展开收起 section 太多

### 策略
- 首屏只渲染必要内容
- 分区加载
- 列表项组件化
- 节流滚动联动
- 长列表必要时评估虚拟列表方案

---

## 11. 推荐实施步骤（项目执行手册）

## 第 0 步：冻结 H5 原型基准
### 目标
防止迁移过程中原型继续变化。

### 要做的事
- 冻结当前原型压缩包版本
- 输出页面清单与验收截图
- 明确哪些页面是 MVP、哪些是次优先级
- 固定验收机型：412px 宽设备为主，辅以 iPhone 标准宽度机型

### 风险
- 原型边迁边改，导致样式和接口字段同时漂移
- 页面名称与业务含义不一致

---

## 第 1 步：做视觉 Token 提取
### 目标
把 Tailwind/H5 样式还原成项目设计系统。

### 要做的事
- 抽颜色
- 抽字号
- 抽圆角
- 抽阴影
- 抽间距
- 抽渐变
- 抽层级
- 抽导航与安全区尺寸

### 产出
- `tokens.wxss`
- 尺寸换算表
- 视觉基线文档

### 风险
- 过早写页面，后面全局返工
- 相同样式在不同页面出现多个版本

---

## 第 2 步：做 Tailwind Class 收敛
### 目标
把散装 utility 组织成可维护的语义类。

### 要做的事
- 抽取卡片、标签、标题、数值块、筛选器、Toast、Modal 等公共样式
- 将内联 style 能抽的全部抽离
- 处理 arbitrary value 的统一口径

### 产出
- `components.wxss`
- 样式命名规范

### 风险
- 直接 page-by-page 硬写，后续无法复用
- 状态类命名混乱

---

## 第 3 步：先迁页面骨架，不做真实数据
### 目标
先得到“静态 1:1 视觉页”。

### 要做的事
- HTML 结构改写为 WXML
- 导航改为小程序导航模型
- 页面中所有文本、图片、徽章、图标、卡片、列表按静态数据渲染
- 完成 Safe Area / Sticky / 层级方案

### 产出
- 每个页面的 WXML + WXSS 静态版
- 验收截图

### 风险
- 一开始就接接口，定位问题困难
- 结构不稳定导致后面样式返工

---

## 第 4 步：迁交互层
### 目标
让静态页具备与原型一致的交互。

### 要做的事
- Tab 切换
- 展开收起
- Toast
- Modal
- 筛选器
- 长按菜单
- 评分
- 复制
- 页面跳转
- 滚动联动

### 产出
- 可演示的小程序原型版

### 风险
- 用 setData 粗暴驱动动画
- 高频滚动联动掉帧
- 多个弹层状态互相打架

---

## 第 5 步：替换 Mock 数据模型
### 目标
建立与未来接口一致的数据结构。

### 要做的事
- 每页梳理字段来源
- 区分：
  - 后端返回
  - 前端枚举
  - 前端派生展示
- 统一 mock JSON 结构
- 统一时间、金额、状态、标签、头像、空态规则

### 产出
- 数据需求 PRD
- mock schema
- 字段字典

### 风险
- 页面先写死文案，后续接口接不进去
- 同一字段不同页面命名不一致

---

## 第 6 步：真机验收与回归
### 目标
确保 1:1 还原真的成立。

### 要做的事
- 以 412px 验收机型对照 H5 原型逐页截图比对
- 再测 375 宽和 Android 常见宽度
- 回归以下场景：
  - 顶部安全区
  - 长列表滚动
  - 弹窗层级
  - 筛选器浮层
  - 长按
  - 评分
  - 字号密度
  - 底部安全区
  - 页面切换动画

### 风险
- 只看开发者工具，不看真机
- 只验静态，不验滚动与交互

---

## 12. 页面优先级建议

## P0（第一批必须先做）
1. `login`
2. `apply`
3. `reviewing`
4. `no-permission`
5. `task-list`
6. `task-detail`（含三种变体）
7. `chat`
8. `chat-history`
9. `notes`
10. `my-profile`
11. `home-settings`

理由：这是最短业务闭环。

## P1（第二批）
1. `customer-detail`
2. `coach-detail`
3. `performance`
4. `performance-records`
5. `customer-service-records`

## P2（第三批）
1. `board-finance`
2. `board-customer`
3. `board-coach`

理由：看板页视觉复杂、滚动联动重、字段也更依赖接口。

---

## 13. 验收标准（必须可落地）

## 13.1 视觉验收
- 同页截图对比，结构、颜色、圆角、阴影、间距、图标位置一致
- 关键卡片与标签误差控制在可感知差异最小范围内
- 412px 宽基准机型优先通过

## 13.2 交互验收
- 点击区域与原型一致
- 浮层开合方向、速度、遮罩、层级正确
- 长按、评分、切换、展开收起行为正确
- Toast 与弹窗文案与原型一致

## 13.3 性能验收
- 首屏不卡顿
- 长列表滚动不卡顿
- 吸顶与筛选滚动联动不闪烁
- 无明显白屏、抖动、错层

## 13.4 工程验收
- 无 Tailwind 运行时依赖
- 公共样式与公共组件已抽离
- 页面字段已按数据文档接 Mock
- 可以切换到真实接口而不重写页面结构

---

## 14. 本项目的落地建议（直接结论）

1. **可以做 1:1 迁移。**
2. **不应该把任务理解成“Tailwind 转 CSS”这么简单。** 真正的工作量在于：把 H5 DOM 交互改成小程序的数据驱动交互。
3. **你的项目比普通 H5 原型更适合迁移。**
   - 因为 Tailwind 用法并不激进；
   - 几乎没有断点响应式；
   - 页面主要是移动端单栏布局；
   - 复杂度集中在交互与数据编排，而不是页面骨架本身。
4. **最关键的成功因素只有三个：**
   - 先抽 Token 和公共组件
   - 先静态还原，再迁交互
   - 先定义数据结构，再接接口

---

## 15. 必要参考文档地址

### 微信小程序
- WXML 模板  
  https://www.tencentcloud.com/zh/document/product/1219/60345
- WXSS 样式  
  https://www.tencentcloud.com/zh/document/product/1219/60346
- 小程序宿主环境（逻辑层 / 渲染层）  
  https://www.tencentcloud.com/zh/document/product/1219/61737
- 动画（`wx.createAnimation`）  
  https://www.tencentcloud.com/zh/document/product/1219/57764
- 渲染层 / 交互动画说明  
  https://www.tencentcloud.com/zh/document/product/1219/61744
- 小程序调试工具  
  https://www.tencentcloud.com/zh/document/product/1219/61764

### Tailwind CSS
- Styling with utility classes  
  https://tailwindcss.com/docs/styling-with-utility-classes
- Functions and directives (`@apply`)  
  https://tailwindcss.com/docs/functions-and-directives
- Responsive design  
  https://tailwindcss.com/docs/responsive-design
- Hover, focus, and other states  
  https://tailwindcss.com/docs/hover-focus-and-other-states

---

## 16. 附录：建议的页面命名映射

| H5 文件 | 小程序页面目录建议 |
|---|---|
| `login.html` | `pages/login/index` |
| `apply.html` | `pages/apply/index` |
| `reviewing.html` | `pages/reviewing/index` |
| `no-permission.html` | `pages/no-permission/index` |
| `home-settings.html` | `pages/home-settings/index` |
| `my-profile.html` | `pages/my-profile/index` |
| `task-list.html` | `pages/task-list/index` |
| `task-detail.html` | `pages/task-detail/index` |
| `task-detail-priority.html` | `pages/task-detail-priority/index` |
| `task-detail-callback.html` | `pages/task-detail-callback/index` |
| `task-detail-relationship.html` | `pages/task-detail-relationship/index` |
| `notes.html` | `pages/notes/index` |
| `chat.html` | `pages/chat/index` |
| `chat-history.html` | `pages/chat-history/index` |
| `board-finance.html` | `pages/board-finance/index` |
| `board-customer.html` | `pages/board-customer/index` |
| `board-coach.html` | `pages/board-coach/index` |
| `performance.html` | `pages/performance/index` |
| `performance-records.html` | `pages/performance-records/index` |
| `customer-service-records.html` | `pages/customer-service-records/index` |
| `coach-detail.html` | `pages/coach-detail/index` |
| `customer-detail.html` | `pages/customer-detail/index` |