OMS 订单模块重构正式文档(一）---升鲜宝生鲜配送供应链管理系统

OMS 订单模块重构正式文档(一）---升鲜宝生鲜配送供应链管理系统

正式扩写版 · 文档包合订本

|----------|------------------------------------------------------|
| 文档范围 | OMS 订单模块重构全量文档（00-29） |
| 适用对象 | 产品经理 / 架构师 / 后端研发 / 测试 / 实施 |
| 重构原则 | 不改原项目结构；Service 无 Result；Controller 瘦身；DAO+XML 按职责拆分 |
| 生成日期 | 2024-04-20 |

说明：本合订本用于对升鲜宝 OMS 模块进行统一架构梳理、职责边界收口、Service/ServiceImpl/DAO/XML 拆分设计与实施计划落地。本文档强调"在不改变原项目结构前提下"的重构路径，适合作为研发排期、评审和交付说明依据。

总览摘要

OMS 模块当前已实际形成四个业务面：订货单、订货看板、发货单、收货单。重构的核心不是增加新的业务面，而是将已存在的业务面按"门面 + 细分服务 + 公共能力 + DAO/XML 职责拆分"的方式治理。

|---------|----------------------------|---------------------------------------------|---------------------|
| 业务面 | 主门面 Service | 重点内部能力 | 关键输出 |
| 订货单 | OmsOrderBillService | create/update/difference/assign/query/print | 分页、详情、差异、指派、导出、打印 |
| 订货看板 | OmsOrderBillNeedService | query/detail/assign/export/print | 需求汇总、批量指派、分维导出、标签小票 |
| 发货单 | OmsOrderBillSendOutService | query/detail/action/export | 发货保存、单条实发、反发货、缺货分析 |
| 收货单 | OmsOrderBillAffireService | query/detail/action | 收货、单条收货、反收货、分享 |

实施阶段建议

|--------|--------------------------|---------------------------------------|---------------------------|
| 阶段 | 重点工作 | 主要输出 | 验收口径 |
| 阶段一 | Controller 瘦身 | 迁移映射表、主门面接口 | Controller 只保留接参/校验/转调/包装 |
| 阶段二 | Service / ServiceImpl 拆分 | 门面 + query/detail/action/export/print | Service 无 Result，职责单一 |
| 阶段三 | DAO/XML 拆分 | 专项 Mapper 与 XML | 复杂 SQL 从万能 Mapper 中迁出 |
| 阶段四 | 公共能力统一 | 金额、规则、上下文、事件、联动 | 分页/详情/动作口径统一 |

00 OMS重构文档总目录

本文档围绕"OMS重构文档总目录"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

目标

• 给出 OMS 重构文档体系的总导航，统一文档口径、阅读顺序与交付边界。

适用对象

• 产品经理
• 架构师
• 后端研发
• 测试
• 实施与运维

建议阅读顺序

• 先阅读《01-OMS重构目标与范围》明确改造边界与不改项。
• 再阅读《02-OMS现状问题盘点》《03-OMS业务边界与模块拆分》《04-OMS最终架构设计说明》建立整体认识。
• 然后进入《08-OMS控制器重构清单》《09-OMS-Service重构清单》《10-OMS-ServiceImpl重构清单》《11-OMS-DAO与XML重构清单》推进代码实施。
• 最后阅读《25-OMS重构实施计划与阶段拆分》《26-OMS测试清单与验收标准》《28-OMS上线切换与回滚预案》完成落地。

文档产出原则

• 不改变原项目目录结构，维持 controller/service/serviceimpl/dao/xml/entity 体系。
• service 接口不返回 Result，controller 统一包装 Result。
• 分页、详情、导出、打印、动作逻辑从 controller 回收到 service。
• 复杂 SQL 继续使用 dao+xml，但按职责拆 Mapper 与 XML。

交付物清单

• 30 份 OMS 重构专题文档。
• 一份合并版 Word 文档与 PDF 文档。
• 后续可扩展为源码骨架、DDL、接口清单、测试用例与上线手册。

01 OMS重构目标与范围

本文档围绕"OMS重构目标与范围"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

重构背景

• 现有 OMS 已形成订货单、订货看板、发货单、收货单四个业务面，但 controller 普遍过重、serviceImpl 过大、dao/xml 职责混杂。
• 重构目标是提升可维护性、可测试性、联动扩展能力与后续迭代效率，而不是推翻现有项目重写。

重构目标

• 建立四个主门面：订货单、订货看板、发货单、收货单。
• 建立金额、规则、上下文、详情聚合、库存/采购/财务联动等公共能力。
• 实现 controller 瘦身，service 语义清晰，dao/xml 按职责拆分。
• 在不影响前端现有 URL 和主要调用方式的前提下完成内部重构。

明确范围

• 纳入：controller/service/serviceimpl/dao/xml 结构治理。
• 纳入：分页、详情、导出、打印、分享、差异、发货、收货、指派等 OMS 核心能力。
• 纳入：库存、采购、财务的联动扩展口设计。
• 不纳入：前端大改版、不兼容 URL 变更、跨域微服务拆分。

不变原则

• 不改变原项目源代码结构。
• 不推翻现有数据库主表与明细表体系。
• 不要求一次性替换全部 controller 和 mapper；允许分阶段迁移。
• 不在 service 接口中返回 Result。

交付目标

• 形成正式重构文档、接口清单、实现类骨架、DAO/XML 清单与实施计划。
• 形成一套研发可直接落地的重构蓝图。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

02 OMS现状问题盘点

本文档围绕"OMS现状问题盘点"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

现状问题总览

• controller 过重：大量控制器直接承接分页二次组装、详情聚合、导出分组、打印数据准备、单条动作逻辑。
• serviceImpl 过大：单个 serviceImpl 同时承接新增、修改、差异、指派、查询、导出、打印、分享等多类职责。
• dao/xml 混用严重：一个 Mapper XML 里同时堆叠基础 CRUD、复杂分页、详情聚合、导出、专项更新 SQL。

典型问题清单

• 发货/收货单条动作直接写在 controller，导致状态变更与金额计算散落。
• 客户小数位/系统默认小数位逻辑在多个 controller 重复出现。
• 看板导出采用 controller 端循环分页拉全量并分 sheet 输出，责任边界不清。
• service 方法历史上直接返回 Result，不利于内部能力复用与单元测试。

结构性风险

• 重复代码多，修一个地方容易漏另一个 controller。
• 分页查询与详情聚合口径不统一，导致展示字段和导出字段容易不一致。
• 复杂 SQL 集中在少数 XML 中，后续改动冲突概率高。
• 库存、采购、财务联动点不统一，未来扩展成本高。

重构优先级

• 第一优先：controller 瘦身与 service 无 Result 化。
• 第二优先：详情聚合、分页查询、导出打印能力收口。
• 第三优先：发货/收货/差异/指派动作链梳理。
• 第四优先：库存、采购、财务联动标准化。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

03 OMS业务边界与模块拆分

本文档围绕"OMS业务边界与模块拆分"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

模块边界

• 订货单：下单、改单、详情、差异、指派、导出、打印、分享。
• 订货看板：需求汇总、详情、按多维度导出、批量打印、批量指派。
• 发货单：发货分页、详情、批量发货、单条实发、反发货、缺货与差异分析。
• 收货单：收货分页、详情、批量收货、单条收货、反收货、分享。

公共能力边界

• 金额与小数位处理统一为公共能力。
• 上下文加载、规则校验、详情聚合、事件记录统一为公共能力。
• 库存、采购、财务同步作为 OMS 向外部域的扩展边界。

跨域关系

• OMS 与库存域：发货扣减、收货入账、差异报损退货同步。
• OMS 与采购域：看板指派采购员后生成采购申请并维护来源链。
• OMS 与财务域：订单创建、修改、支付、对账准备的扩展口。

不建议混入OMS的内容

• 非订单业务的基础资料维护。
• 纯仓储库位策略的独立规则引擎。
• 财务正式记账与总账报表。

04 OMS最终架构设计说明

本文档围绕"OMS最终架构设计说明"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

总体架构

• 采用四个主门面 + 一组公共能力 + 基础 DAO/专项 DAO 的模式。
• controller 层只依赖主门面 service；主门面内部再转调 query/detail/action/export/print 等细分服务。
• 复杂查询和聚合继续使用 dao+xml，避免在 service 中拼 SQL。

架构分层

• 入口层：OmsOrderBillController、OmsOrderBillNeedController、OmsOrderBillSendOutController、OmsOrderBillAffireController。
• 业务门面层：四个主门面 service。
• 业务能力层：create/update/query/detail/action/export/print 与公共能力 service。
• 数据访问层：基础表 Mapper + 专项 Mapper + XML。

关键设计决策

• service 接口不返回 Result，controller 统一包装。
• 详情聚合与分页展示从 controller 回收到 detail/query service。
• 动作类逻辑从 controller 回收到 action service。
• 按业务面拆 DAO/XML，而不是维持一个万能 Mapper。

演进收益

• 研发定位问题更快，职责更清晰。
• 复用能力更强，导出/打印/分享可共用聚合结果。
• 后续库存/采购/财务扩展更自然。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

05 OMS最终分层设计说明

本文档围绕"OMS最终分层设计说明"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

controller 层

• 负责入参接收、基础校验、调用主门面 service、包装 Result、输出文件流。
• 不负责 SQL 查询、金额格式化、名称回填、单条动作计算。

service 层

• 主门面 service：对 controller 提供业务入口。
• 细分 service：负责 create/update/query/detail/action/export/print 等具体职责。
• 公共能力 service：负责金额、规则、上下文、联动、事件等横向能力。

serviceimpl 层

• 承接真实业务实现，统一抛异常。
• 禁止返回 Result；对外语义应是业务对象、PageData、void 或标识值。

dao/xml 层

• 基础 DAO 承接基础 CRUD。
• 专项 DAO 承接复杂分页、详情聚合、导出、打印、动作更新 SQL。

对象分层

• Entity 只表示持久化结构。
• Request DTO 只做入参。
• Query DTO 只做筛选条件。
• Resp DTO/Excel DTO/Print DTO 只做展示输出。

06 OMS主业务流程清单

本文档围绕"OMS主业务流程清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

主流程列表

• 客户下单：校验 → 上下文加载 → 金额计算 → 主单落库 → 明细落库 → 日志 → 事件。
• 门店下单：校验 → 上下文加载 → 小数位处理 → 主单与明细保存 → 日志。
• 改单：读取旧单 → 识别明细差异 → 更新主表 → 更新/删除/新增明细 → 重算金额。
• 差异处理：校验差异状态 → 生成报损/退货单 → 同步库存 → 写日志。

履约流程

• 发货：待发货查询 → 批量发货或单条实发 → 更新明细与主表发货汇总 → 写日志。
• 反发货：校验状态 → 回退发货状态 → 反向更新库存/汇总。
• 收货：待收货查询 → 批量收货或单条收货 → 更新明细与主表收货汇总 → 写日志。
• 反收货：校验状态 → 回退收货状态 → 反向更新库存/汇总。

辅助流程

• 指派供应商：筛选看板需求 → 按商品规格单位更新归属。
• 指派采购员：筛选看板需求 → 生成采购申请 → 维护来源单号与来源明细。
• 导出/打印：查询数据 → DTO 组装 → 输出文件或打印数据。
• 分享：查询头信息 → 聚合详情 → 返回轻量化展示对象。

07 OMS模块功能清单

本文档围绕"OMS模块功能清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

订货单功能

• 订单分页、详情、分享、打印、导出。
• 新增客户订单、新增门店订单、改单。
• 差异报损/差异退货、批量差异处理。
• 指派供应商、指派采购员。

订货看板功能

• 需求分页与详情。
• 按线路、采购员、客户、供应商、仓库、分类查看需求。
• 批量指派、批量导出、批量打印。

发货单功能

• 发货分页、详情、发货分享。
• 发货保存、暂存、反发货、单条实发。
• 按商品/客户发货分析、发货差异、缺货管理。

收货单功能

• 收货分页、详情、收货分享。
• 收货、反收货、批量收货、收货暂存、单条收货。
• 收货明细新增/修改/删除。

08 OMS控制器重构清单

本文档围绕"OMS控制器重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

控制器治理目标

• 四个 controller 全部瘦身，统一只保留接参、校验、转调、包装 Result 四类职责。
• 把分页二次组装、详情聚合、导出分组、打印准备、单条动作逻辑移出 controller。

控制器拆分重点

• OmsOrderBillController：page/get/orderbillInfo/export/print/share 迁到 query/detail/export/print service。
• OmsOrderBillNeedController：看板导出和打印迁到 export/print service，指派迁到 assign service。
• OmsOrderBillSendOutController：sendOutOne 与详情聚合迁到 action/detail service。
• OmsOrderBillAffireController：affireOne 与详情聚合迁到 action/detail service。

统一规范

• controller 方法返回 Result。
• service 接口不返回 Result。
• 异常统一在全局异常处理中转换。
• 文件导出接口仅保留 response 输出。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

09 OMS-Service重构清单

本文档围绕"OMS-Service重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

主门面 Service

• OmsOrderBillService、OmsOrderBillNeedService、OmsOrderBillSendOutService、OmsOrderBillAffireService。

订货单内部 Service

• OmsOrderCreateService、OmsOrderUpdateService、OmsOrderDifferenceService、OmsOrderAssignService、OmsOrderQueryService、OmsOrderPrintService。

看板内部 Service

• OmsOrderBillNeedQueryService、OmsOrderBillNeedDetailService、OmsOrderBillNeedAssignService、OmsOrderBillNeedExportService、OmsOrderBillNeedPrintService。

发货单内部 Service

• OmsOrderBillSendOutQueryService、OmsOrderBillSendOutDetailService、OmsOrderBillSendOutActionService、OmsOrderBillSendOutExportService。

收货单内部 Service

• OmsOrderBillAffireQueryService、OmsOrderBillAffireDetailService、OmsOrderBillAffireActionService。

公共能力 Service

• OmsOrderAmountService、OmsOrderRuleService、OmsOrderContextService、OmsOrderDetailMergeService、OmsOrderInventorySyncService、OmsOrderPurchaseSyncService、OmsOrderFinanceSyncService、OmsOrderEventService。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

10 OMS-ServiceImpl重构清单

本文档围绕"OMS-ServiceImpl重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

实现类原则

• 主门面只负责转调，不承载大段业务逻辑。
• query/detail/action/export/print 实现类各自收口明确职责。
• 公共能力实现类应对四个业务面可复用。

关键实现类

• OmsOrderCreateServiceImpl：统一订单新增。
• OmsOrderDifferenceServiceImpl：统一差异报损/退货。
• OmsOrderBillSendOutActionServiceImpl：统一发货动作。
• OmsOrderBillAffireActionServiceImpl：统一收货动作。
• OmsOrderAmountServiceImpl：统一金额与小数位。

实施建议

• 优先落地门面和 action 类。
• 再落地 query/detail 类。
• 最后补公共能力和联动类。

11 OMS-DAO与XML重构清单

本文档围绕"OMS-DAO与XML重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

拆分原则

• 基础表 CRUD 继续保留在基础 Mapper。
• 复杂分页、详情聚合、导出、打印、动作更新 SQL 迁到专项 Mapper。

订货单专项

• OmsOrderQueryDao、OmsOrderDetailDao、OmsOrderAssignDao、OmsOrderPrintDao、OmsOrderExportDao。

看板专项

• OmsOrderBillNeedQueryDao、OmsOrderBillNeedDetailDao、OmsOrderBillNeedAssignDao、OmsOrderBillNeedExportDao、OmsOrderBillNeedPrintDao。

发货与收货专项

• 发货：Query/Detail/Action/Export 四类 Mapper。
• 收货：Query/Detail/Action 三类 Mapper。

XML 规范

• 一个 XML 只做一种职责。
• namespace 与 Mapper 全限定名一致。
• 复杂动态 SQL 统一在 XML 中维护，不在 service 中拼接。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

12 OMS实体与DTO整理清单

本文档围绕"OMS实体与DTO整理清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

对象分类

• Entity：主表、明细表、日志表、附件表、差异表、退货表等持久化对象。
• Request DTO：新增、修改、发货、收货、差异、指派等入参对象。
• Query DTO：分页、详情、导出、打印、差异、看板筛选对象。
• Resp DTO：列表展示、详情展示、分享展示、导出展示、打印展示对象。

整理原则

• Entity 不承载展示字段。
• Resp DTO 承接名称回填、小数位格式化结果、状态描述、派生字段。
• 导出 DTO 与打印 DTO 独立维护，避免污染详情 DTO。

重点整理对象

• RespOrderBillDTO、RespOmsOrderBillDTO、RespGoodsNeedSumDTO、RespOrderBillGoodsSendDTO、RespOrderBillShopSendDTO、RespStockShortageManagementDTO 等。

13 OMS查询模型重构清单

本文档围绕"OMS查询模型重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

统一查询模型

• OmsOrderBillPageQuery 统一承接订货/发货/收货分页参数。
• GoodsSkuNeedSumQuery 与 GoodsSkuNeedSumExcelQuery 承接看板查询和导出。
• OmsOrderBillInfoQuery 承接详情与上一单/下一单导航。
• OrderIdListDTO / OrderIdDTO 承接批量打印、批量导出、分享查询。

重构目标

• 减少 controller 中 Map<String,Object> 手工解析。
• 减少重复的默认参数补齐逻辑。
• 明确每个查询对象的责任边界。

白名单策略

• 排序字段、模糊查询字段、可选过滤字段形成明确白名单。
• 逐步减少直接透传 SQL_FILTER 的方式，改为 XML 动态条件。

14 OMS详情聚合重构清单

本文档围绕"OMS详情聚合重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

聚合对象范围

• 主单头信息、明细列表、日志列表、附件列表。
• 客户/供应商/仓库/用户名称回填。
• 商品/SKU/单位/图片/周转物补充信息。
• 上一单/下一单状态。

复用策略

• 订货详情、发货详情、收货详情共用统一的聚合思路，但各自拥有独立 detail service 和 detail dao。
• 分享页尽量复用详情聚合结果，避免重复 SQL。

治理目标

• 彻底把详情聚合从 controller 挪到 detail service。
• 彻底减少 get(...) 与 xxxInfo(...) 接口之间的重复代码。

15 OMS动作链路重构清单

本文档围绕"OMS动作链路重构清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

动作链统一范围

• 新增订单、改单、差异报损、差异退货、指派供应商、指派采购员。
• 发货、反发货、单条实发。
• 收货、反收货、单条收货。
• 明细新增、明细修改、明细删除。

动作链设计原则

• 校验 → 查当前状态 → 业务处理 → 更新主表/明细 → 写日志 → 写事件。
• 单条动作和批量动作都应收口到 action service，不应写在 controller。
• 涉及金额汇总与状态变更时，统一在 action service 中处理。

重点优先级

• 先迁移 sendOutOne 与 affireOne。
• 再迁移批量发货、批量收货、反发货、反收货。
• 最后统一差异与指派动作链。

16 OMS金额与小数位统一方案

本文档围绕"OMS金额与小数位统一方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

统一规则来源

• 优先读取客户小数位配置。
• 客户未配置时回退系统默认 GLOBAL_DECIMAL_PLACES_SET。

统一处理对象

• 数量、单价、金额、折扣、配送费、发货金额、收货金额。
• 主单列表、详情页、导出、打印全部使用同一处理规则。

实现策略

• 把 getMallShopPlacesSet(...) 从 controller 移到 OmsOrderAmountService。
• 所有金额 setScale 与显示格式化统一从 amount service 调用。
• 写入金额与展示金额分离，避免 controller 随意格式化。

17 OMS库存联动改造方案

本文档围绕"OMS库存联动改造方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

联动点

• 差异报损后库存扣减。
• 差异退货后库存回写或逆向处理。
• 发货确认后库存扣减。
• 收货确认后库存入账。

改造目标

• 库存联动统一从 OMS 动作 service 触发到 OmsOrderInventorySyncService。
• 库存更新、库存流水、来源单号关联统一收口。

注意事项

• 动作需具备幂等控制。
• 反发货、反收货需设计逆向补偿链。
• 联动失败时需有日志和告警机制。

18 OMS采购联动改造方案

本文档围绕"OMS采购联动改造方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

触发点

• 看板指派采购员后生成采购申请。
• 采购申请需记录来源订单、来源明细、来源数量。

设计原则

• 采购申请生成逻辑收口到 OmsOrderPurchaseSyncService。
• 采购申请编码、来源单号、来源明细需可追溯。
• 同一批需求重复指派时要有防重策略。

实施建议

• 先固化采购申请 DTO 和 Mapper。
• 再实现采购申请主表/明细生成逻辑。

19 OMS财务联动改造方案

本文档围绕"OMS财务联动改造方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

联动目标

• 订单创建、修改、支付、履约完成时预留财务触发点。
• 为应收、对账、账单、发票等后续模块预留扩展口。

实现建议

• 由 OmsOrderFinanceSyncService 统一承接 OMS 对财务域的通知。
• 前期可以只记录事件与日志，后期再接真实财务模块。

约束

• 不在 OMS 内直接实现财务总账逻辑。
• OMS 只负责触发业务事件与准备业务数据。

20 OMS导出与打印重构方案

本文档围绕"OMS导出与打印重构方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

导出重构目标

• 控制器只负责 response 输出，不再负责分页循环取数和分组组装。
• 订货单、看板、发货单导出分别进入专项 export service。
• 看板按线路/采购员/客户/供应商/仓库/分类导出全部统一进入 export service。

打印重构目标

• 打印 DTO 统一管理，controller 只返回打印数据。
• 订货打印与看板打印分别使用独立 print service。

注意事项

• 导出 DTO 与详情 DTO 分离。
• 打印数据准备需要统一口径，避免详情页和打印页字段不一致。

21 OMS分享页重构方案

本文档围绕"OMS分享页重构方案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

分享页类型

• 订货分享头信息与详情。
• 发货分享头信息与详情。
• 收货分享头信息与详情。

重构原则

• 尽量复用 detail service 的聚合能力。
• 分享头信息返回轻量 DTO，分享详情返回完整详情 DTO。

目的

• 减少 shareXXX controller 与详情 controller 的重复逻辑。
• 统一分享页展示口径。

22 OMS异常码与状态流转清单

本文档围绕"OMS异常码与状态流转清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

异常码建议

• OMS 订单不存在、订单状态不允许、差异状态不允许、发货状态不允许、收货状态不允许、明细不存在、参数不能为空等异常统一归类。
• 对关键动作建议配置独立业务错误码，便于前端和日志识别。

状态流转建议

• 订单状态：新建 → 审核 → 发货中/已发货 → 收货中/已收货 → 完成。
• 差异状态：未处理 → 已报损/已退货。
• 发货状态：未发货 → 部分发货 → 已发货。
• 收货状态：未收货 → 部分收货 → 已收货。

治理目标

• 动作 service 必须按状态机执行，不允许 controller 直接越过状态校验。
• 所有状态变更必须有日志和事件记录。

23 OMS数据库表与字段梳理清单

本文档围绕"OMS数据库表与字段梳理清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

核心表清单

• oms_order_bill、oms_order_bill_info、oms_order_bill_log、oms_order_bill_image。
• oms_order_more_less、oms_order_more_less_info、oms_order_more_less_log。
• oms_returnorder、oms_returnorder_info、oms_returnorder_log。

梳理重点

• 主表字段：订单编码、客户、仓库、状态、金额、发货汇总、收货汇总、创建信息。
• 明细字段：商品、规格、单位、数量、单价、金额、发货信息、收货信息、差异状态。
• 日志字段：订单编码、操作人、说明、时间。
• 附件字段：订单编码、文件路径、上传信息。

优化建议

• 把展示性字段放到 resp，不在表结构中重复存储。
• 对高频分页字段、单号字段、状态字段、时间字段建立合适索引。
• 专项聚合字段建议由 SQL 汇总或动作服务重算。

24 OMS接口兼容与前端影响评估

本文档围绕"OMS接口兼容与前端影响评估"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

兼容原则

• 尽量不改 URL，不改前端主要调用路径。
• controller 返回 Result 的方式保持不变。
• 入参 DTO 尽量保持兼容，必要扩展使用可选字段。

可能影响点

• 如果详情或分页字段口径统一后，部分展示字段名和默认值需要前端联调确认。
• 导出/打印接口如果调整为更稳定的 query DTO，需要评估前端参数传递方式。

建议策略

• 先做内部重构，不改外部契约。
• 如需改契约，应新增版本或兼容旧字段。

25 OMS重构实施计划与阶段拆分

本文档围绕"OMS重构实施计划与阶段拆分"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

阶段一：控制器瘦身

• 将分页、详情、单条动作迁移到 service。
• 统一 service 接口无 Result。

阶段二：Service/ServiceImpl 拆分

• 建立主门面与 query/detail/action/export/print 细分服务。
• 主门面只做转调和事务边界。

阶段三：DAO/XML 拆分

• 把复杂 SQL 从基础 DAO 中拆到专项 DAO/XML。
• 分页、详情、导出、动作更新按职责分开。

阶段四：公共能力统一

• 金额与小数位、上下文加载、规则校验、详情聚合统一。
• 差异合并与状态机统一。

阶段五：联动扩展

• 库存、采购、财务、事件服务完善。

阶段验收

• 每阶段都输出代码清单、测试记录、影响评估、回滚点。

落实建议：该主题应与相邻文档联读，先形成评审结论，再进入接口、实现类与 SQL 的具体落地。

26 OMS测试清单与验收标准

本文档围绕"OMS测试清单与验收标准"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

功能测试

• 订货单：新增、改单、详情、差异、指派、导出、打印、分享。
• 看板：分页、详情、批量指派、批量导出、打印。
• 发货单：分页、详情、批量发货、单条实发、反发货、缺货管理。
• 收货单：分页、详情、批量收货、单条收货、反收货。

规则测试

• 金额与小数位处理一致性。
• 状态流转合法性。
• 上一单/下一单导航正确性。
• 异常码与提示信息正确性。

回归测试

• 导出数据与页面展示口径一致。
• 打印数据与详情数据一致。
• 分享页与详情页一致。

验收标准

• controller 只保留收参、校验、转调、包装。
• service 接口无 Result。
• 关键 SQL 已拆到专项 Mapper/XML。
• 主流程、动作链、导出打印全部通过回归测试。

27 OMS重构风险清单

本文档围绕"OMS重构风险清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

代码层风险

• controller 瘦身导致遗漏回填字段或格式化逻辑。
• Mapper 拆分后旧 SQL 调用点未全部迁移。
• 详情聚合调整后前端依赖字段发生变化。

业务层风险

• 发货/收货动作迁移后状态流转不一致。
• 差异报损/退货与库存联动不一致。
• 看板导出口径与页面口径不一致。

组织层风险

• 文档先行但代码执行节奏不一致。
• 多人并行改造造成冲突。

规避措施

• 按阶段推进、每阶段小范围验证。
• 建立迁移映射表和改动清单。
• 关键流程先写自动化或集成测试。

28 OMS上线切换与回滚预案

本文档围绕"OMS上线切换与回滚预案"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

上线前准备

• 完成接口回归、导出回归、打印回归、分享页回归。
• 完成关键 SQL 性能检查与索引检查。
• 完成异常日志和监控点确认。

上线步骤

• 先灰度发布内部重构版本。
• 重点观察分页、详情、发货、收货、导出接口。
• 确认无异常后全量切换。

回滚预案

• 保留旧版本分支与可回滚包。
• 若关键动作链异常，优先回滚 action service 或旧 controller 逻辑。
• 导出/打印异常可独立回退 export/print 模块。

上线后观察

• 订单状态变更日志。
• 发货/收货成功率。
• 导出失败率。
• SQL 慢查询。

29 OMS重构最终交付清单

本文档围绕"OMS重构最终交付清单"展开，目的是形成可执行、可评审、可交付的重构说明。以下内容基于升鲜宝现有 OMS 代码现状、模块边界与后续演进方向进行整理。

文档交付

• 30 份 OMS 重构文档。
• 合并版 Word 与 PDF。

代码交付

• 最终版 service 接口清单。
• 最终版 serviceimpl 骨架。
• 最终版 DAO/XML 清单与 Mapper 骨架。
• controller → service 迁移映射表。

测试交付

• 测试清单与验收报告。
• 关键流程联调记录。

上线交付

• 上线步骤说明。
• 回滚预案。
• 后续优化建议。