用迁移矩阵和真实冒烟测试推进遗留 TMS 迁移

迁移一个遗留 TMS，最容易落入的陷阱是把“菜单已经出现”和“业务已经迁移”画上等号。旧系统包含订单、调度、承运商、执行、异常、回单、轨迹、竞价、报表、财务和移动端等大量入口，仅复制页面骨架无法证明流程可以工作。

这次迁移先建立功能矩阵，再按完整业务链实施。每个旧入口都必须标记为迁移、合并、替代或明确移除，并记录新路由、接口、状态机和验收场景。没有分类的页面不能被算作完成。

从页面清单转向完整业务链

迁移批次围绕业务链组织：

运输订单
→ 任务与调度
→ 承运商分配或竞价
→ 提货、在途与异常
→ 签收和 POD
→ 费用、对账与发票

每个动作都需要明确的状态迁移、权限边界和重复请求语义。客户端不能传入公司、司机或供应商身份来决定数据范围，这些信息必须从服务端认证上下文取得。

写接口使用幂等键：相同键和相同载荷返回原结果，相同键但载荷不同返回冲突。这样移动端在弱网重试时不会重复创建任务、轨迹或财务记录。

Web、PWA 与 Android 共用接口规则

管理端补齐真实业务页面和中英文资源。移动端采用 Ionic Vue 与 Capacitor，共享 PWA 和 Android 业务代码，覆盖登录、任务、执行、异常、回单、轨迹、通知和结算。

离线队列区分网络失败、业务失败和版本冲突。附件先上传，业务请求只引用文件 ID；GPS 使用批量同步和去重；401 只自动刷新一次，4xx 不伪装成离线成功。

旧私有插件、历史密钥和授权协议没有迁回。原生能力通过可配置适配层接入，缺少正式地图、推送或签名配置时明确保持关闭。

验证不是只跑编译

自动检查包括后端全量测试、开源边界、前端类型检查与生产构建、移动端测试、Capacitor 同步和 Android APK 构建。

更关键的是启动隔离端口的真实服务，执行完整冒烟流程（smoke test）：

• 创建并推进运输订单；
• 验证调度约束和承运商投标；
• 重放幂等请求；
• 上传并去重轨迹；
• 生成报表与财务资源；
• 通过 OpenAPI 重放调用；
• 检查最终数据库状态。

真实运行暴露过一个脚本 URL 插值错误。它不是服务缺陷，但如果只看单元测试就不会发现。修正后从头重跑，所有主链通过，再停止隔离服务并提交各子模块。

遗留系统迁移的完成标准不应该是代码量或页面数量，而是每个旧能力都有明确去向、核心流程能走到最终状态、失败和重试可解释，并且数据库结果能被验证。迁移矩阵用于管理范围，真实冒烟测试用于确认流程确实走通，两者缺一不可。