From c107d47229575b60498690eda3150f5d8b7a2dde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=AF=E8=88=AA?= <280645618@qq.com> Date: Sat, 14 Feb 2026 17:37:45 +0800 Subject: [PATCH 1/2] docs: add shipment callback onboarding playbook --- docs/新人入门指南.md | 50 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/新人入门指南.md b/docs/新人入门指南.md index fe89ece5..bb5463bc 100644 --- a/docs/新人入门指南.md +++ b/docs/新人入门指南.md @@ -282,3 +282,53 @@ npm run dev 5. **养成“数据 + 日志”双证据习惯**：排障时同时看 DB 和服务日志。 欢迎加入项目，建议你从“登录链路 + 一个平台订单拉取链路”开始，两天内就能建立有效认知并进入开发节奏。 + +--- + +## 13. 发货回传链路阅读地图（培训模板） + +> 适用场景：给新同学做一次 30 分钟“订单履约闭环”培训，目标是明确“发货数据如何从中台回推到店铺平台”。 + +### 13.1 链路目标 + +- 看懂发货处理与平台状态回传的边界： + - `erp-api` 负责履约处理（待发货、分配、物流录入） + - `oms-api` 负责平台适配与回推 +- 形成统一排障思路：先看订单状态，再看物流数据，再看平台接口调用日志 + +### 13.2 推荐阅读顺序 + +1. 先回顾 README 的“处理订单（发货）”流程图，建立业务语义。 +2. 在 `erp-api` 查找“发货确认/物流录入/发货记录”相关 controller 与 service。 +3. 在 `oms-api` 对应平台目录（如 `pdd`、`jd`、`tao`）查找“发货回传”接口封装。 +4. 在 `service`/`mapper` 中追踪订单状态字段、物流单号、回传结果记录。 + +### 13.3 断点与日志建议 + +- 断点 1：发货确认接口入口（确认请求参数是否包含订单号、物流公司、物流单号） +- 断点 2：发货服务层状态变更（确认状态机是否从“待发货”进入“已发货/已分配”） +- 断点 3：平台 API 调用前（确认签名参数、token、店铺配置） +- 断点 4：平台 API 返回后（记录成功/失败码与错误信息） + +日志字段建议统一包含：`orderId`、`shopId`、`platform`、`waybillNo`、`carrierCode`、`resultCode`、`resultMsg`。 + +### 13.4 常见故障排查清单 + +1. **平台回传失败但本地已发货** + - 检查店铺 token 是否失效 + - 检查快递公司编码与平台枚举是否一致 + - 检查接口限流/重试策略 +2. **平台显示已发货但系统仍待发货** + - 检查事务提交与状态更新顺序 + - 检查异步回调是否覆盖状态 +3. **同一订单重复回传** + - 检查幂等键（订单号 + 发货单号） + - 检查重试任务是否缺少去重条件 + +### 13.5 培训演示脚本（可直接照着讲） + +1. 选取一笔“待发货”订单，展示当前状态。 +2. 手动执行发货并录入物流单号。 +3. 演示后端日志中的发货调用链。 +4. 回到系统查询订单状态、发货记录、平台回传结果。 +5. 总结：发货链路是“状态变更 + 物流信息 + 平台回执”三段式。 From 8174318a502e6fb88e80e6e4edf451012c94f8d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=90=AF=E8=88=AA?= <280645618@qq.com> Date: Sat, 14 Feb 2026 17:53:59 +0800 Subject: [PATCH 2/2] docs: refine shipment callback onboarding with concrete code paths --- docs/新人入门指南.md | 84 +++++++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 33 deletions(-) diff --git a/docs/新人入门指南.md b/docs/新人入门指南.md index bb5463bc..6594dbd5 100644 --- a/docs/新人入门指南.md +++ b/docs/新人入门指南.md @@ -289,46 +289,64 @@ npm run dev > 适用场景：给新同学做一次 30 分钟“订单履约闭环”培训，目标是明确“发货数据如何从中台回推到店铺平台”。 -### 13.1 链路目标 +### 13.1 先讲清版本边界（非常重要） -- 看懂发货处理与平台状态回传的边界： - - `erp-api` 负责履约处理（待发货、分配、物流录入） - - `oms-api` 负责平台适配与回推 -- 形成统一排障思路：先看订单状态，再看物流数据，再看平台接口调用日志 +开源版里“电子面单发货”接口默认返回“开源版本不支持电子面单功能”，培训时请先说明这个边界，避免新人误判为 Bug： -### 13.2 推荐阅读顺序 +- `oms-api` 的 `pdd/jd/tao/wei/dou` `*WaybillController` 下 `push_ship_send` 等接口为占位能力。 +- 例如：`PddWaybillController#pushShipSend`、`JdWaybillController#pushShipSend` 直接返回错误提示。 -1. 先回顾 README 的“处理订单（发货）”流程图，建立业务语义。 -2. 在 `erp-api` 查找“发货确认/物流录入/发货记录”相关 controller 与 service。 -3. 在 `oms-api` 对应平台目录（如 `pdd`、`jd`、`tao`）查找“发货回传”接口封装。 -4. 在 `service`/`mapper` 中追踪订单状态字段、物流单号、回传结果记录。 +> 因此，新人应先掌握“手工发货 + 供应商发货确认 + 发货记录落库”主链路，再理解平台回传扩展点。 -### 13.3 断点与日志建议 +### 13.2 开源版可跑通的发货主链路（建议演示） -- 断点 1：发货确认接口入口（确认请求参数是否包含订单号、物流公司、物流单号） -- 断点 2：发货服务层状态变更（确认状态机是否从“待发货”进入“已发货/已分配”） -- 断点 3：平台 API 调用前（确认签名参数、token、店铺配置） -- 断点 4：平台 API 返回后（记录成功/失败码与错误信息） +建议按这 3 个接口讲： -日志字段建议统一包含：`orderId`、`shopId`、`platform`、`waybillNo`、`carrierCode`、`resultCode`、`resultMsg`。 +1. `erp-api /shipping/handShip`：手工添加发货记录（`ShipmentController#orderHandShip`） +2. `erp-api /ship/supplier_ship_confirm`：供应商发货确认并录入物流（`OrderShipController#SupplierShipConfirm`） +3. `erp-api /ship/generate_stock_out_entry`：从备货单生成出库单（`OrderShipController#generateStockOutEntry`） -### 13.4 常见故障排查清单 +配套查询接口： -1. **平台回传失败但本地已发货** - - 检查店铺 token 是否失效 - - 检查快递公司编码与平台枚举是否一致 - - 检查接口限流/重试策略 -2. **平台显示已发货但系统仍待发货** - - 检查事务提交与状态更新顺序 - - 检查异步回调是否覆盖状态 -3. **同一订单重复回传** - - 检查幂等键（订单号 + 发货单号） - - 检查重试任务是否缺少去重条件 +- `/ship/stock_up_list_by_warehouse` +- `/ship/stock_up_list_by_supplier` +- `/shipping/list` -### 13.5 培训演示脚本（可直接照着讲） +### 13.3 推荐阅读顺序（带真实代码位置） -1. 选取一笔“待发货”订单，展示当前状态。 -2. 手动执行发货并录入物流单号。 -3. 演示后端日志中的发货调用链。 -4. 回到系统查询订单状态、发货记录、平台回传结果。 -5. 总结：发货链路是“状态变更 + 物流信息 + 平台回执”三段式。 +1. 读 README 的“处理订单（发货）”流程图，先建立业务语义。 +2. 看 `api/erp-api/.../ShipmentController.java`，理解手工发货参数校验与入库入口。 +3. 看 `api/erp-api/.../OrderShipController.java`，理解供应商发货确认与备货/出库流程。 +4. 看 `service/src/main/java/cn/qihangerp/module/service/OOrderService.java`、`OOrderShipListService.java`，理解服务层职责。 +5. 看 `mapper/src/main/resources/mapper/OOrderMapper.xml`、`OOrderShipListMapper.xml`、`OShipmentItemMapper.xml`，定位状态字段与发货数据落点。 +6. 最后看 `api/oms-api/.../TaoShipController.java` 与各 `*WaybillController`，理解“开源版占位、商业版扩展”的边界。 + +### 13.4 断点与日志建议（按顺序打） + +- 断点 1：`ShipmentController#orderHandShip` 参数校验后，确认 `shipType/shopId/orderNum` 等核心字段。 +- 断点 2：`OrderShipController#SupplierShipConfirm` 调用 `supplierShipOrderManualLogistics` 前，确认 `logisticsCompany/logisticsCode`。 +- 断点 3：`OrderShipController#generateStockOutEntry`，确认备货单到出库单生成条件。 +- 断点 4：`*WaybillController#pushShipSend`，让新人看到开源版限制返回，避免错误排障方向。 + +日志字段建议统一包含：`orderId`、`shopId`、`platform`、`logisticsCompany`、`logisticsCode`、`resultCode`、`resultMsg`。 + +### 13.5 常见故障排查清单（开源版视角） + +1. **接口返回“开源版本不支持电子面单功能”** + - 先确认是否误调用了 `*WaybillController` 的电子面单接口。 + - 改走手工发货或供应商发货确认链路。 +2. **供应商发货确认失败** + - 检查 `id/logisticsCompany/logisticsCode` 是否为空。 + - 检查备货单状态是否允许当前操作。 +3. **生成出库单失败** + - 检查备货单 ID 是否存在且状态正确。 + - 回查备货明细是否完整（SKU、数量、仓位信息）。 + +### 13.6 30 分钟培训演示脚本（可直接照着讲） + +1. 选取一笔“待发货”订单，打开备货列表页面并记录订单号。 +2. 调用 `/ship/supplier_ship_confirm` 完成供应商发货确认。 +3. 调用 `/ship/generate_stock_out_entry` 生成出库单。 +4. 调用 `/shipping/list` 查询发货记录，确认物流单号已落库。 +5. 额外演示一次 `/pdd/ewaybill/push_ship_send` 返回“开源版不支持”，强调版本边界。 +6. 总结：开源版发货链路重点是“状态变更 + 物流落库 + 出库单生成”，平台回传能力在商业版扩展。