Merge pull request #10 from zeasin/codex/explain-codebase-structure-to-newcomers-230tgb

docs: add shipment callback onboarding playbook

docs/新人入门指南.md

@@ -282,3 +282,71 @@ npm run dev
 5. **养成“数据 + 日志”双证据习惯**：排障时同时看 DB 和服务日志。
 
 欢迎加入项目，建议你从“登录链路 + 一个平台订单拉取链路”开始，两天内就能建立有效认知并进入开发节奏。
+
+---
+
+## 13. 发货回传链路阅读地图（培训模板）
+
+> 适用场景：给新同学做一次 30 分钟“订单履约闭环”培训，目标是明确“发货数据如何从中台回推到店铺平台”。
+
+### 13.1 先讲清版本边界（非常重要）
+
+开源版里“电子面单发货”接口默认返回“开源版本不支持电子面单功能”，培训时请先说明这个边界，避免新人误判为 Bug：
+
+- `oms-api` 的 `pdd/jd/tao/wei/dou` `*WaybillController` 下 `push_ship_send` 等接口为占位能力。
+- 例如：`PddWaybillController#pushShipSend`、`JdWaybillController#pushShipSend` 直接返回错误提示。
+
+> 因此，新人应先掌握“手工发货 + 供应商发货确认 + 发货记录落库”主链路，再理解平台回传扩展点。
+
+### 13.2 开源版可跑通的发货主链路（建议演示）
+
+建议按这 3 个接口讲：
+
+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`）
+
+配套查询接口：
+
+- `/ship/stock_up_list_by_warehouse`
+- `/ship/stock_up_list_by_supplier`
+- `/shipping/list`
+
+### 13.3 推荐阅读顺序（带真实代码位置）
+
+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. 总结：开源版发货链路重点是“状态变更 + 物流落库 + 出库单生成”，平台回传能力在商业版扩展。