# 客户小程序：剩余迁移思路与执行计划（`miniprogram` → `sqxp-wx`）

**前提**：以 `miniprogram` 为唯一标准；**不新增**源端没有的功能与入口；**不删减**源端已有的交互、校验、分页、空态与样式结构（除非源端本身已废弃且可举证）。

**配套文档**：差异登记表见 `docs/sqxp-wx-client-vs-miniprogram-diff.md`。

---

## 1. 总体策略（推荐）

采用 **「源页整体替换 + 工程适配层」**，而不是在现有简化页上零散打补丁：

1. **以源文件为蓝本**：将 `miniprogram/src/pages/client/<页>.vue` 的 template + script + style **整体迁为** `sqxp-wx` 对应路径文件。  
2. **做一层薄适配**（每页或统一 mixin/工具）：  
   - 请求：`sqxp-wx` 统一使用 `request` + `parseResponseJson(res)`，替换源中仍写 `res.data` 且未解析的用法。  
   - TypeScript → JavaScript：去掉类型注解，保留运行时校验与分支。  
   - **Vant**：源有 `van-*` 处，在 `sqxp-wx` 用 **uni 原生组件 + 样式** 做出 **同等布局与交互**（不引入新业务能力）。  
3. **每页验收通过后再下一页**，避免并行大改难以回归。

---

## 2. 基础设施先行（减少重复劳动）

按顺序完成，可在「首页大改」前并行：

| 序号 | 工作项 | 说明 |
|:----:|--------|------|
| A1 | 迁入 `static/data/china-region-cascader.json` | 与源路径一致或约定 `@/static/data/...`，供 `address/edit` 多列省市区与源一致。 |
| A2 | 迁入 `api/reviewApi.js`（由 `reviewApi.ts` 转写） | 与源 **同 URL、同方法、同参数**；评价相关页只调此模块，避免复制粘贴分叉。 |
| A3 | 迁入 `utils/avatar.js`、`utils/service-contact.js` | 与 `profile` 头像、联系客服行为一致。 |
| A4 | 扩展 `config/api.js` | 导出与源 `API_URL` 中 **客户页已使用** 的常量（如 `CLIENT_DASHBOARD`），保持路径字符串与源一致。 |
| A5 | `phone-dial-inline` 视觉对齐 | 在**不引入 Vant** 的前提下，按源 scss 调整字号、间距、点击区，使与源截图一致。 |

---

## 3. 页面迁移优先级建议（依赖关系 + 风险）

**原则**：被多页依赖的基础体验优先；**首页**体量最大，单独作为一大里程碑。

| 阶段 | 建议顺序 | 理由 |
|:----:|----------|------|
| P0 | `address/edit` → `address/address` → `address/select` | 下单、购物车、确认订单均依赖地址；且源与目标差异最大之一在 **省市区组件**。 |
| P1 | `home/home` | 客户主入口；源含分类侧栏、多接口组合，完成后其它页的「从首页进」路径才与源一致。 |
| P2 | `cart/cart` | 与首页、确认订单、商品浮层强耦合；需与源的 **分页列表、地址展示、浮层关闭刷新** 一致。 |
| P3 | `order/create/create` | 依赖购物车与地址；源使用 Vant 按钮与布局，需整体替换适配。 |
| P4 | `order/order` → `order/pay/pay` → `order/detail/detail` | 列表 → 支付 → 详情链路；`detail` 已与源较接近，可做 **终态 diff 扫尾**。 |
| P5 | `product/view` → `product/detail` | 商品详情与兼容跳转页与源对齐。 |
| P6 | `review/list` → `review/create` | 依赖 `reviewApi` 与商品信息参数，适合在 A2 完成后整体替换。 |
| P7 | `profile/profile` | 依赖 A3、A4；并**按源菜单删除目标多出的入口**（如 profile 内「我的发票」若源无则移除）。 |
| P8 | `invoice/invoice`、`settlement/settlement`、`refund/refund` | 在 P7 菜单与源一致后，再保证各页 **内部** 与源一致；避免菜单与源矛盾。 |

---

## 4. 单页标准作业程序（SOP）

对每一页执行：

1. **冻结基准**：记录当前 `miniprogram` 该页 commit 或文件哈希，迁移中源若变更需 conscious merge。  
2. **结构对齐**：`<template>` 层级、关键 `class`、条件渲染块与 `v-for` 与源 **同序**（便于 diff 样式）。  
3. **逻辑对齐**：`onLoad` / `onShow` / `onMounted`、分页参数、错误处理、二次确认弹窗与源一致；仅替换 `request` 使用方式。  
4. **样式对齐**：优先复制源 **`lang="scss"`** 至目标（需在 `sqxp-wx` 构建链支持 scss；若暂不支持，则逐块转为等价 plain CSS，**禁止**随意合并为单行导致层级丢失）。  
5. **对照验收**：  
   - 功能：用例表逐条打勾；  
   - 样式：同分辨率截图或设计走查（以源截图为准）。  
6. **合并约束**：该页 PR **仅包含该页 + 必要公共模块**，避免一次 PR 改多页难以审查。

---

## 5. Vant 与无 Vant 的等价策略（不增加功能）

| 源（示例） | 目标方向 |
|------------|----------|
| `van-button` | `button` + 与源相同的 `class` 尺寸、圆角、`disabled` 样式 |
| `van-icon` | `text`/小图标字体/本地 png（**语义与点击区域**与源一致） |
| 其它 `van-*` | 逐项查源文档用法，用 uni 内置或 `view` 模拟，**禁止**借机加字段或加步骤 |

---

## 6. 与「不添加功能」相关的收敛动作（计划内）

在完全对齐阶段应执行（具体以源为准）：

1. **个人中心菜单**：与源 `profile` 的菜单项、顺序、**联系客服** 行一致；移除源 `profile` 中不存在的菜单入口。  
2. **订单详情**：保持与源一致（若源无订单内评价入口，则目标不得加）。  
3. **全局检索**：对 `sqxp-wx` 执行 `grep` 查找仅目标存在的 `navigateTo`/`菜单` 文案，与源交叉比对，删除「迁移过程临时加」的入口。

---

## 7. 风险与缓解

| 风险 | 缓解 |
|------|------|
| `sqxp-wx` 根工程含大量 hello-uniapp 示例页 | 与客户迁移无关；**不要**误改示例路由；客户页 PR 保持范围清晰。 |
| 请求返回结构平台差异 | 坚持 `parseResponseJson`；对分页字段 `list/total/totalPages` 与源页保持同一解析分支。 |
| 双人并行改同一页 | 按上表阶段 + 单页 SOP 串行或严格文件级分工。 |

---

## 8. 完成定义（Definition of Done）

满足以下可视为「客户小程序迁移完毕」：

1. `docs/sqxp-wx-client-vs-miniprogram-diff.md` 中 **所有「重大/较大差异」行**均已关闭（或经产品书面签字接受差异——当前任务未授权接受差异）。  
2. 客户 17 页 + `components/client/*` + `phone-dial-inline` + 本节 A1–A5 所列公共模块，均完成 **源侧对照验收**。  
3. **无**源端不存在的菜单、按钮、接口调用；**无**源端不存在的文案承诺。  

---

## 9. 建议排期（可按人力拆分，单位：人日量级仅为粗估）

| 阶段 | 内容 | 粗估（人日） |
|------|------|-------------|
| P0 基础设施 | A1–A5 | 1–2 |
| P1 首页 | `home` 整体替换 + 联调 | 3–6 |
| P2–P3 购物车与确认订单 | `cart` + `create` | 2–4 |
| P4 订单链路 | `order` + `pay` + `detail` 扫尾 | 1–3 |
| P5–P6 商品与评价 | `view` + `detail` + `review` | 2–4 |
| P7–P8 个人中心与发票/结算/退款 | 含菜单收敛 | 1–2 |
| 回归与修缺陷 | 全链路真机 | 2–3 |

**合计粗估**：约 **12–24 人日**（随熟悉度与源变更浮动）。

---

## 10. 文档维护

每完成一页：在 `docs/sqxp-wx-client-vs-miniprogram-diff.md` 对应行更新状态（可后续加「状态」列：未开始/进行中/已对齐），避免文档与代码再次脱节。