docs: refine shipment callback onboarding with concrete code paths

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. 总结：开源版发货链路重点是“状态变更 + 物流落库 + 出库单生成”，平台回传能力在商业版扩展。