sqxp/docs/miniprogram-迁移到-sqxp-mobile-执行清单.md

miniprogram 迁移到 sqxp-mobile 执行清单（先跑通供应商端）

1. 目标与范围

• 目标：将 miniprogram（Vue3 小程序工程，含供应商/客户/配送员）业务代码完整融入 sqxp-mobile（uni-app 工程），并可在微信小程序正常编译、运行、联调。
• 本文策略：以 sqxp-mobile 为宿主壳工程，按模块迁移 miniprogram 业务代码。
• 实施顺序：先跑通供应商端（登录 -> 首页 -> 询价/报价 -> 配送单 -> 地址/设置），再迁移客户端、配送员端。

2. 总体迁移原则

1. 壳工程保留：保留 sqxp-mobile 的工程骨架（App.vue、main.js、manifest.json、pages.json、uni.scss）。
2. 业务代码迁移：从 miniprogram/src 按目录迁移业务代码。
3. 运行时统一：统一为 uni.* API，避免直接依赖 wx.*。
4. 增量验证：每完成一批页面立刻编译验证，不做“全部迁完再调试”。
5. 产物不迁移：不迁移 unpackage/dist/**、.sourcemap/** 等构建产物。

3. 目录级迁移映射（直接搬 / 需改造 / 重写）

3.1 可直接迁移（优先复制后微调）

• miniprogram/src/api/** -> sqxp-mobile/api/**
• miniprogram/src/stores/** -> sqxp-mobile/stores/**
• miniprogram/src/types/** -> sqxp-mobile/types/**
• miniprogram/src/config/** -> sqxp-mobile/config/**
• miniprogram/src/static/** -> sqxp-mobile/static/**
• miniprogram/src/components/** -> sqxp-mobile/components/**（若存在平台能力差异再按需改）

3.2 需要改造后迁移

• miniprogram/src/utils/request.ts
  • 改造点：请求基础地址、Token 注入、超时/错误处理、uni.request 适配。
• miniprogram/src/utils/**（工具库）
  • 改造点：wx.* 改为 uni.*，并处理 Promise 化与类型定义。
• miniprogram/src/styles/**
  • 改造点：全局样式入口挂载到 sqxp-mobile/App.vue 或 uni.scss，检查变量作用域与 rpx 兼容。
• miniprogram/src/pages.json
  • 改造点：与 sqxp-mobile/pages.json 合并，保留 uni-app 规范字段。
• miniprogram/src/manifest.json
  • 改造点：只迁移业务相关配置；宿主以 sqxp-mobile/manifest.json 为主进行合并。

3.3 需重写或重组（高风险区）

• sqxp-mobile/main.js
  • 需重组为与原业务一致的应用初始化（Pinia、全局拦截器、全局组件注册、启动逻辑）。
• sqxp-mobile/App.vue
  • 需重写应用级生命周期、全局样式注入、全局状态初始化。
• 部分页面中直接调用平台能力的逻辑（如定位/上传/电话/登录）
  • 建议新增 sqxp-mobile/platform/** 适配层，页面统一调用适配层。

4. 第一阶段：先跑通供应商端（强执行顺序）

4.1 阶段目标（可验收）

供应商端核心链路可跑通：

• 登录页：/pages/login/login
• 供应商首页：/pages/supplier/home/home
• 询价列表/详情：/pages/supplier/inquiry/inquiry、/pages/supplier/inquiry/detail/detail
• 报价列表/详情：/pages/supplier/quotation/quotation、/pages/supplier/quotation/detail/detail
• 配送单列表/详情：/pages/supplier/delivery/delivery、/pages/supplier/delivery/detail/detail
• 地址管理：/pages/supplier/address/address、/pages/supplier/address/edit
• 个人中心：/pages/supplier/profile/profile
• 账号设置：/pages/supplier/settings/avatar、/pages/supplier/settings/password

4.2 实施任务（按步骤执行）

1. 初始化 sqxp-mobile 业务目录
   • 新建：api/、stores/、types/、utils/、config/、components/、styles/、platform/
2. 迁移基础代码
   • 按第 3 节映射迁移 api/stores/types/config/static。
3. 重构网络层
   • 改造 request 封装并在 main.js 注入鉴权与错误处理。
4. 迁移供应商页面
   • 按“登录 -> 首页 -> 列表 -> 详情 -> 配置页”顺序迁移。
5. 合并路由
   • 更新 sqxp-mobile/pages.json，确保页面路径、分包、tabBar 与原业务一致。
6. 全局样式对齐
   • 合并 styles/index.scss 与 styles/variables.scss 到新工程样式入口。
7. 运行验证
   • 在 HBuilderX 编译微信小程序，先过编译，再过页面跳转与接口联调。

4.3 阶段1改造总结（已完成）

• 完成范围（基础运行层）：
  • sqxp-mobile/config/api.js
  • sqxp-mobile/utils/request.js
  • sqxp-mobile/stores/user.js
  • sqxp-mobile/styles/index.scss
  • sqxp-mobile/styles/variables.scss
  • sqxp-mobile/App.vue
  • sqxp-mobile/main.js
  • sqxp-mobile/pages.json
  • sqxp-mobile/pages/login/login.vue
  • sqxp-mobile/pages/supplier/home/home.vue
• 已达成能力：
  • 登录态持久化与冷启动恢复（TOKEN/USER_INFO）
  • 统一请求封装与 401 失效回收
  • 供应商首页登录守卫与退出登录链路
  • 全局样式入口接入（可支撑后续页面统一风格）
• 当前约束（阶段性）：
  • 为保证先跑通，sqxp-mobile 暂采用无外部依赖的轻量 store 方案（未切回 Pinia）
  • 登录暂为基础账号密码请求，未接入原工程 RSA 登录链路
  • 供应商业务页（询价/报价/配送/地址/设置）尚未迁入
• 阶段结论：
  • 阶段1“先跑通登录 + 供应商首页骨架 + 基础设施”目标已完成，可进入阶段2业务页迁移。

5. 第二阶段：客户端与配送员端迁移顺序

1. 客户端（建议优先）
   • 首页分类 + 商品详情 + 购物车 + 下单 + 订单 + 地址 + 个人中心
2. 配送员端
   • 首页 + 抢单 + 任务列表 + 任务详情 + 个人中心
3. 每完成一个角色端，执行一次角色级回归（见第 8 节）。

6. 关键改造点清单（开发时逐项打勾）

• 所有 wx.* 调用替换为 uni.* 或 platform 适配层。
• pages.json 路由完整，页面路径与代码目录一致。
• manifest.json 的微信小程序配置（appid、网络域名、权限）正确。
• Pinia 正常挂载，登录态可持久化并在重启后恢复。
• 请求层统一处理 401/403/500，页面不再散落重复错误处理。
• 全局样式变量生效，三端角色主题保持既有规范。
• 所有静态资源路径改为 uni-app 可识别路径（避免相对路径错乱）。

7. 高风险问题与规避方案

7.1 构建产物误提交/误依赖

• 风险：sqxp-mobile/unpackage/dist/** 被当作源码修改，导致版本混乱。
• 规避：
  • 迁移时只操作源码目录；
  • 将构建产物加入忽略（若未忽略需补充到 .gitignore）。

7.2 页面能编译但运行报错

• 风险：平台 API 或生命周期差异导致运行时报错。
• 规避：
  • 优先迁移“登录 + 首页”最小链路；
  • 每迁移 2~3 个页面即进行微信开发者工具运行验证。

7.3 样式错位与主题漂移

• 风险：全局变量未注入、页面局部样式覆盖冲突。
• 规避：
  • 统一从 uni.scss 注入设计变量；
  • 复用 miniprogram 主题变量并逐页对齐。

8. 验收标准（Definition of Done）

8.1 编译验收

• sqxp-mobile 可在 HBuilderX 成功编译到微信小程序。
• 微信开发者工具打开后无阻断性启动报错。

8.2 供应商端功能验收（第一里程碑）

• 登录成功并可进入供应商首页。
• 询价/报价/配送单列表可加载，详情可打开。
• 地址管理可新增/编辑。
• 头像/密码设置页可正常提交。

8.3 质量验收

• 无明显白屏、主流程无阻断。
• 关键接口异常时有统一提示，不崩溃。
• 页面首屏性能可接受（无明显卡顿）。

9. 建议的执行节奏（供排期）

• Day 1：完成目录与基础层迁移（api/stores/utils/styles）+ 登录链路跑通。
• Day 2：供应商首页、询价、报价链路跑通。
• Day 3：配送单、地址、设置页跑通 + 供应商端回归。
• Day 4+：客户端与配送员端按同模式迁移并回归。

10. 实施记录模板（每次迁移后补充）

建议在本文末尾持续追加记录，格式如下：

### [YYYY-MM-DD] 迁移记录
- 迁移范围：
- 已完成页面：
- 本次改造点：
- 遗留问题：
- 下一步计划：

[2026-04-17] 迁移记录

• 迁移范围：sqxp-mobile 基础运行层（config、utils、stores、styles、App.vue、main.js、pages.json）
• 已完成页面：/pages/login/login、/pages/supplier/home/home（阶段1可运行骨架）
• 本次改造点：完成登录态存储与恢复、统一请求封装、401 统一回收、供应商首页登录守卫、全局样式入口接入
• 遗留问题：尚未迁入 miniprogram 的完整 api/components/pages；登录仍为基础参数登录，未接入原 RSA/Vant 方案
• 下一步计划：阶段2开始按供应商端业务页顺序迁移（询价/报价/配送单/地址/设置），并替换为原业务逻辑与 UI

[2026-04-17] 阶段2进展（第1批）

• 迁移范围：供应商询价模块（列表/详情）与首页入口、路由配置
• 已完成页面：
  • sqxp-mobile/pages/supplier/inquiry/inquiry.vue
  • sqxp-mobile/pages/supplier/inquiry/detail/detail.vue
• 配套改造：
  • sqxp-mobile/pages/supplier/home/home.vue 新增询价入口
  • sqxp-mobile/pages.json 新增询价列表与详情路由
• 兼容策略：去除 Vant 依赖，保留核心业务链路（拉取询价、录入报价、提交报价、查看详情）以保证当前工程可编译运行
• 下一步计划：继续迁移供应商报价页（quotation）与配送页（delivery）

[2026-04-17] 阶段2进展（第2批）

• 迁移范围：供应商报价模块与配送模块（列表/详情）、首页入口补全、路由补全
• 已完成页面：
  • sqxp-mobile/pages/supplier/quotation/quotation.vue
  • sqxp-mobile/pages/supplier/quotation/detail/detail.vue
  • sqxp-mobile/pages/supplier/delivery/delivery.vue
  • sqxp-mobile/pages/supplier/delivery/detail/detail.vue
• 配套改造：
  • sqxp-mobile/pages/supplier/home/home.vue 新增报价与配送入口
  • sqxp-mobile/pages.json 新增 quotation/delivery 路由
  • sqxp-mobile/utils/format.js、sqxp-mobile/utils/date.js 补充基础格式化工具
• 兼容策略：去除 QuotationDetailContent、PhoneDialInline 等未迁移组件依赖，改为页面内可运行实现（保证当前工程可先编译/运行）
• 下一步计划：继续迁移供应商地址与设置页，并逐步恢复组件复用与 UI 细节一致性

[2026-04-17] 阶段2进展（第3批）

• 迁移范围：供应商地址页与设置页（头像/密码）迁移，首页入口与路由补全
• 已完成页面：
  • sqxp-mobile/pages/supplier/address/address.vue
  • sqxp-mobile/pages/supplier/address/edit.vue
  • sqxp-mobile/pages/supplier/settings/avatar.vue
  • sqxp-mobile/pages/supplier/settings/password.vue
• 配套改造：
  • sqxp-mobile/stores/user.js 新增 updateUserInfo、refreshUserInfo
  • sqxp-mobile/pages/supplier/home/home.vue 新增地址、头像、密码入口
  • sqxp-mobile/pages.json 新增 address/settings 路由
• 兼容策略：
  • 地址编辑页先采用可运行的省市区文本输入拆分方案（避免依赖大体积地区级联 JSON）
  • 电话交互统一采用 uni.makePhoneCall
• 下一步计划：回到“UI 细节与组件复用对齐”阶段，逐步替换临时实现（地址级联、头像工具函数、通用电话组件等）

[2026-04-17] 收口对齐进展（第1批）

• 对齐范围：地址级联选择、拨号与头像公共能力复用、供应商页局部视觉/交互一致性
• 已完成：
  • 新增 sqxp-mobile/components/phone-dial-inline.vue
  • 新增 sqxp-mobile/utils/phone-dial.js
  • 新增 sqxp-mobile/utils/avatar.js
  • 地址编辑页切换为 picker + multiSelector 三级联动：sqxp-mobile/pages/supplier/address/edit.vue
  • 地址列表/配送页/配送详情页接入 PhoneDialInline 复用组件
  • 头像设置页改为复用 resolveUserAvatarUrl：sqxp-mobile/pages/supplier/settings/avatar.vue
• 数据说明：
  • 已迁入地区级联 JSON：sqxp-mobile/static/data/china-region-cascader.json
  • 当前为首批可运行数据集（覆盖常用省市区），后续可按同结构扩展为完整全国数据
• 下一步计划：继续统一供应商端各页面间距、卡片与标签视觉规范，并补全全国地区数据集

[2026-04-17] 收口对齐进展（第2批）

• 对齐范围：全国地区数据补全、供应商端通用能力复用恢复、页面视觉统一强化
• 已完成：
  • sqxp-mobile/static/data/china-region-cascader.json 已替换为 miniprogram 同源完整数据（SHA1 一致）
  • 新增拨号工具与复用组件：
  • sqxp-mobile/utils/phone-dial.js
  • sqxp-mobile/components/phone-dial-inline.vue
  • 新增头像解析工具：
  • sqxp-mobile/utils/avatar.js
  • 地址编辑页恢复三级联动选择（multiSelector + china-region-cascader.json）
  • 地址列表、配送列表、配送详情已接入 PhoneDialInline 统一拨号交互
  • 头像页已接入 resolveUserAvatarUrl 统一头像 URL 解析
  • 供应商端样式收口：
  • sqxp-mobile/styles/index.scss 增加供应商 token 与通用类
  • 首页/报价/地址/设置页统一卡片圆角、阴影、边框和主按钮渐变
• 修复项：
  • 修复 login/home 页面对 userStore 的 ref 访问方式（isLoggedIn.value）
• 下一步计划：继续按 miniprogram 视觉细节逐页微调（询价/配送详情的标签层级、空态插图、间距节奏与按钮状态）

[2026-04-17] 发布闭环进展（第1批）

• 目标：先打通三端主入口路由与骨架页面，进入可联调状态
• 已完成：
  • 新增迁移占位组件：sqxp-mobile/components/migration-placeholder.vue
  • 新增客户端核心页面骨架：
  • pages/client/home/home
  • pages/client/cart/cart
  • pages/client/order/order
  • pages/client/profile/profile
  • 新增配送员核心页面骨架：
  • pages/deliverer/home/home
  • pages/deliverer/task/task
  • pages/deliverer/task/detail/detail
  • pages/deliverer/profile/profile
  • pages/deliverer/snatch/snatch
  • 补齐供应商个人中心骨架：pages/supplier/profile/profile
  • sqxp-mobile/pages.json 已补充 client/deliverer/supplier 路由并接入客户端 tabBar
• 当前结论：
  • 三端导航骨架已具备，工程可进入“逐页业务逻辑替换 + 联调验收”阶段
  • client/deliverer 业务逻辑尚未完成从 miniprogram 页面代码的等价迁移

[2026-04-17] 发布闭环进展（第2批）

• 目标：优先将 client 核心链路从骨架替换为真实业务页（home/cart/order/profile）
• 已完成：
  • 新增购物车 store：sqxp-mobile/stores/cart.js（接入 /mini/client/cart 增删改查与汇总）
  • 用户 store 增补角色计算：isClient、isDeliverer（sqxp-mobile/stores/user.js）
  • 客户端首页迁移为接口驱动真实页：pages/client/home/home.vue
  • 客户端购物车迁移为接口驱动真实页：pages/client/cart/cart.vue
  • 客户端订单列表迁移为接口驱动真实页：pages/client/order/order.vue
  • 客户端个人中心迁移为接口驱动真实页：pages/client/profile/profile.vue
• 说明：
  • 为保证当前工程可联调，移除了对未迁入重组件（如产品详情浮层、Vant 按钮等）的强依赖，保留真实接口数据流与主交互
  • 客户端“详情页/下单页/支付页/评价页”等深链页面仍待下一批迁移
• 下一步计划：
  • 继续 deliverer 核心链路真实页替换（home/task/snatch/profile）
  • 然后进入微信开发者工具联调并逐条勾选第8节验收项

[2026-04-17] 发布闭环进展（第3批）

• 目标：将 deliverer 核心链路从骨架替换为真实业务页（home/task/snatch/profile），并打通任务详情页
• 已完成：
  • sqxp-mobile/pages/deliverer/home/home.vue：工作台、统计卡片、任务筛选、任务列表、常用入口（任务/抢单/客服）
  • sqxp-mobile/pages/deliverer/task/task.vue：任务列表、状态 Tab、关键词检索、拨号、详情跳转
  • sqxp-mobile/pages/deliverer/snatch/snatch.vue：待抢任务列表、抢单操作、供应商拨号
  • sqxp-mobile/pages/deliverer/profile/profile.vue：个人中心、菜单入口、客服、退出登录
  • sqxp-mobile/pages/deliverer/task/detail/detail.vue：任务详情、取货/送达操作、收发货信息、明细展示
  • 新增客服工具：sqxp-mobile/utils/service-contact.js
• 说明：
  • 当前 deliverer 链路已完成“真实接口 + 主交互”替换，摆脱 MigrationPlaceholder
  • 受限于本地环境（无 HBuilderX/微信开发者工具 CLI 闭环），微信工具联调验收需在 IDE 内执行
• 下一步计划：
  • 在微信开发者工具执行真实账号联调（配送员登录、任务流转、抢单、拨号）
  • 完成第8节编译与质量项勾选，并输出“可发布状态报告”