docs: add shipment callback onboarding playbook

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. 总结：发货链路是“状态变更 + 物流信息 + 平台回执”三段式。