mtsd/docs/sqxp-wx-client-migration-remaining-plan.md

客户小程序：剩余迁移思路与执行计划（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 对应行更新状态（可后续加「状态」列：未开始/进行中/已对齐），避免文档与代码再次脱节。