下游下发与回执
单据下发 WMS / ERP / OMS / TMS 的接口清单、下发内容、回执状态、失败重试与幂等键约定（重复下发拦截），并用时间线展示"一次下发的全过程"，回写日志与异常处理一屏可查。
今日下发单据
21张
涉及 4 个外部系统
下发成功率
95.2%
21 张中 20 张成功
幂等拦截重复
3次
重复下发已被拦截，无脏数据
失败待重试
1张
主数据校验失败，重试无效需人工
平均下发耗时
318ms
P99 = 1.2s
回执回写及时率
99.1%
异步回执 5 分钟内到齐
一次下发的全过程（RP20251021-003 · 幂等键贯穿）
E3 + X13 幂等与写入边界STEP 1
审批通过
09:05
STEP 2
生成幂等键
09:05
STEP 3
下发 WMS
09:06
STEP 4
ERP 建单
09:06
STEP 5
拣货出库
15:20
STEP 6
回填运单
18:40
STEP 7
轨迹回执
持续
09:05:12 · 审批通过
二级审批通过，单据进入"已审批"，生成幂等键 RP20251021-003__v2__202510210812（业务单号 + 数据版本 + 提单时间戳）
09:06:02 · 下发 WMS（成功）
POST /wms/inbound/order → 200 OK，218ms，WMS 返回出库单号 OB-20251021-0119
09:06:02 · 下发 ERP（成功）
POST /erp/sales-order → 200 OK，ERP 单号 SO-20251021-0342；行级幂等键含 lineNo
09:06:03 · 重复下发拦截
调度器补跑再次触发同幂等键 → 服务端返回 409 DUPLICATE 并回放首次结果，未新建订单
15:20:40 · WMS 拣货完成回执
3 个包裹 47 件全部拣齐，扫码复核差异 0；单据状态推进为"已发货"
18:40:11 · 回填运单号
POST /oms/transfer → 运单 SF7781002 绑定 3 个包裹
18:41:02 · OMS 首次回填失败
502 BAD_GATEWAY（网关超时 30s），进入重试队列，退避 30s/60s/120s
18:42:34 · 重试第 3 次成功
200 OK，612ms；幂等键未变，OMS 侧未产生重复运单绑定
持续 · 轨迹回执
TMS 每 2h 推送轨迹，预计 2025-10-24 12:00 到店；到店后等待门店扫码签收
- 业务单号
- RP20251021-003
- 数据版本
- v2（人工改量后版本）
- 提单时间戳
- 2025-10-21 08:12
- 幂等键
- RP20251021-003__v2__202510210812
- 键的生成方
- 本系统（下游只校验不生成）
- 有效期
- 决策日 + 7 天（同键复用窗口）
- 重复处理
- 返回首次结果，不做二次写入
- 写入边界
- 本系统只写自己的单据表；库存以 WMS 为准回写
幂等键为什么必须由上游生成
若由下游按"门店 + SKC + 日期"自行判重，同一决策日多版本改量会被误判为重复而丢弃；若不加版本号，人工改量后的重发会被拦。因此幂等键 = 业务单号 + 数据版本 + 提单时间戳，且必须由本系统生成。
成功 同步 2xx重试中 指数退避失败 需人工介入
下发接口清单（WMS / ERP / OMS / TMS / 门店端 / 数仓）
幂等键约定：全局唯一、由上游生成、写入边界清晰| 目标系统 | 接口 / 方式 | 下发内容 | 触发时机 | 幂等键 | 回执方式 | SLA | 今日状态 |
|---|---|---|---|---|---|---|---|
| WMS | POST /wms/inbound/order（REST · JSON） | 补货单/调拨单主信息 + 明细（SKC×尺码）+ 包裹号 + 期望到货时间 | 审批通过后自动 | bizNo + version + submittedAt哈希 | 同步 accepted / 异步出库回执 | ≤ 30s | 正常 |
| ERP | POST /erp/sales-order（REST · JSON） | 销售订单（内部调拨视同销售）+ 客户（门店）信息 + 数量 + 价格 | 审批通过后自动 | bizNo + lineNo（行级 upsert） | 同步返回 ERP 单号 SO-xxx | ≤ 60s | 正常 |
| OMS | POST /oms/transfer（REST · JSON） | 调拨单（含跨区）+ 逻辑仓映射 + 承运商 + 运单号回填 | 发货后回填运单 | bizNo + 承运商 + 运单号 | 异步回调 + 轮询兜底 | ≤ 5min | 告警 |
| TMS | POST /tms/shipment（REST · JSON） | 运单创建：起止门店、件数、体积重量、时效承诺 | WMS 拣货完成后 | shipmentNo 全局唯一 | 异步轨迹推送（每 2h） | ≤ 5min | 正常 |
| 门店小程序 / 企微 | MsgPush（服务端推送） | 到货提醒、待办、异常反馈入口 | 发货 / 到店节点 | taskId（同任务不重复推送） | 已读回执 + 处理回执 | ≤ 10s | 正常 |
| BI / 数仓 | Kafka topic: ar.decision.final | 决策最终数据（含模型值/人工值双轨）+ 单据与回执状态 | 单据状态每次变更 | decisionRowId + version | 消费位点确认 | ≤ 1min | 正常 |
回写日志与异常处理
共 96 条 · 展示 8 条；拦截重复与失败项均可见| 时间 | 单号 | 目标 | 动作 | 幂等键 | HTTP / 业务码 | 耗时 | 结果 | 返回 / 错误信息 |
|---|---|---|---|---|---|---|---|---|
| 2025-10-21 09:06:02 | RP20251021-003 | WMS | 下发入库单 | RP20251021-003__v2__202510210812 | 200 / OK | 218ms | 成功 | WMS 受理，出库单号 OB-20251021-0119 |
| 2025-10-21 09:06:02 | RP20251021-003 | ERP | 下发销售订单 | RP20251021-003__v2__L001 | 200 / OK | 1,240ms | 成功 | ERP 单号 SO-20251021-0342 |
| 2025-10-21 09:06:03 | RP20251021-003 | ERP | 重复下发拦截 | RP20251021-003__v2__L001 | 409 / DUPLICATE | 12ms | 拦截重复 | 同幂等键已存在，返回首次结果，未新建订单 |
| 2025-10-21 18:40:11 | RP20251021-003 | OMS | 回填运单号 | RP20251021-003__SF__SF7781002 | 200 / OK | 486ms | 成功 | 运单 SF7781002 已绑定 3 个包裹 |
| 2025-10-21 18:41:02 | RP20251021-005 | OMS | 回填运单号 | RP20251021-005__SF__— | 502 / BAD_GATEWAY | 30,000ms | 失败 | OMS 网关超时（重试 1/3） |
| 2025-10-21 18:41:33 | RP20251021-005 | OMS | 回填运单号（重试 2/3） | RP20251021-005__SF__— | 504 / TIMEOUT | 30,000ms | 失败 | OMS 连接池耗尽（重试 2/3），退避 60s |
| 2025-10-21 18:42:34 | RP20251021-005 | OMS | 回填运单号（重试 3/3） | RP20251021-005__SF__— | 200 / OK | 612ms | 成功 | 第 3 次重试成功；单据状态由"已审批"推进为"已下发" |
| 2025-10-20 09:12:44 | RP20251020-011 | WMS | 下发入库单 | RP20251020-011__v1__202510200900 | 422 / VALIDATION_FAILED | 154ms | 失败 | SKC 主数据在 WMS 侧已停用，单据停留"已审批"并告警 |
共 8 行每页
失败重试策略
分清"可重试"与"不可重试"是回执可靠性的关键| 失败类型 | 示例错误码 | 重试策略 | 上限 | 超限后 |
|---|---|---|---|---|
| 网络 / 网关超时 | 502 / 504 | 指数退避 30s→60s→120s | 3 次 | 转人工重试，单据停留"已审批"，不置"已下发" |
| 下游限流 | 429 TOO_MANY | 按 Retry-After 头等待 | 5 次 | 降速到 5 TPS 后继续，不丢弃 |
| 主数据校验失败 | 422 VALIDATION | 不重试 | 0 次 | 生成数据异常工单（主数据类），修好后手动重发 |
| 重复下发 | 409 DUPLICATE | 不重试，回放首次结果 | — | 视为成功，记录拦截日志供审计 |
| 鉴权失败 | 401 / 403 | 刷新令牌后重试 1 次 | 1 次 | 立即告警到集成负责人，暂停该通道后续下发 |
| 部分成功（行级） | 207 MULTI_STATUS | 仅对失败行重发 | 3 次 | 失败行挂起并回写单据备注，成功行不重复写 |
下发通道健康度
回执回写规则
回执只回写状态与数量，不回写单据主数据；库存变动以 WMS 出库/入库回执为准，经库存台账（D3/D4）落账后再参与下一轮决策计算。
异常处理待办
| 级别 | 系统 | 异常内容 | 建议动作 |
|---|---|---|---|
| 严重 | WMS | RP20251020-011 下发 422：SKC 25SS-1245 在 WMS 侧主数据已停用，单据卡在"已审批" | 同步商品主数据后手动重发 |
| 警告 | OMS | 18:41 OMS 网关连续两次超时（连接池耗尽），重试后恢复 | 调整连接池与超时阈值至 60s |
| 警告 | ERP | 3 次 409 DUPLICATE 拦截记录，源自调度器补跑 | 无需处理，保留审计日志 |
| 提示 | 门店端 | 1 家门店消息推送未送达（店员未关注企微） | 短信兜底 + 电话通知店长 |
!设计说明：E3X13 下发与回执是闭环里最容易被忽略的一段。三个必须做实的点：① 幂等键由上游生成且含数据版本，否则人工改量后重发会被拦；② 失败单据不得置为"已下发"，状态必须停留并告警；③ 可重试与不可重试错误码要分开，主数据类错误重试一万次也不会成功。
关联跳转traceId 贯穿：单据号 → 幂等键 → 下游单号，可在链路追踪页一键串起来