# 回调(Webhook) ## 1. 定位 三方仓的回调是**仓方主动推送到商户配置的地址**。SDK 的职责只有两件事: 1. **验签** 2. **解析成统一出参** SDK **不监听端口、不做去重存储、不落库**——这些是宿主的工作。 ## 2. 完整链路 ``` ┌─────────┐ ① 推送到 OMS 配置的地址 │ 三方仓 │ POST /user/callback/yqn └────┬────┘ Header: X-AppKey / X-Timestamp / X-Signature │ Body: 原始 JSON ▼ ┌──────────────────────────────────────┐ │ OMS HTTP 入口 │ │ @PostMapping("/user/callback/yqn") │ │ String rawBody ← 必须拿原文 │ └────┬─────────────────────────────────┘ │ ② sdk.webhook(provider, secret, headers, rawBody, nowMillis) ▼ ┌──────────────────────────────────────┐ │ WarehouseSdk.webhook │ │ 1. 按 provider 找适配器(不需仓账户) │ │ 2. 检查 WEBHOOK 能力位 │ │ 3. adapter.verify(...) 验签失败直接抛│ │ 4. adapter.parse(...) 验签通过才解析│ └────┬─────────────────────────────────┘ │ ③ List ▼ ┌──────────────────────────────────────┐ │ OMS 业务:按 eventType 分派落库 │ └──────────────────────────────────────┘ ``` ### 为什么需要单独的 `sdk.webhook(...)` 普通调用是 `sdk.warehouses(warehouseCode, conn).xxx()`,**要先知道仓编码**。 但回调进来时: - 只有 **provider**(由 OMS 的路由决定,如 `/user/callback/yqn`) - **没有 warehouseCode**——仓编码在报文里,甚至报文可能不带 - **不需要完整的 WarehouseConnection**——验签只要 `appSecret` 所以入口只按 provider 分派,不查 `WarehouseRepository`。 ## 3. 出参模型 ```java WarehouseCallback ├── sourceProvider // 哪家仓 ├── eventType // 统一枚举,按它分派 ├── rawEventType // 仓方原值,排查用 ├── eventId // 仓方给的事件 id(可能为 null) ├── rawStatus // 仓方状态原值(需与 rawEventType 一起解释) ├── providerWarehouseCode // 仓方仓编码 ├── providerOrderNo // 仓方单据号 ├── requestNo // 我们下发的来源单号 ├── occurredAt // 变更时间 ├── rawBody // 原始报文(排查与回溯) │ ├── outbound → 面单 / 出库载荷 ├── returns → 退货载荷 ├── inbound → 入库载荷 └── inventory → 库存变动载荷 ``` ### 事件类型 | `WarehouseEventType` | 含义 | 载荷 | |---|---|---| | `LABEL_PURCHASED` | 面单购买成功 | `outbound` | | `ORDER_STATUS_CHANGED` | 业务单据状态变更 | 无(看 `rawStatus` + `rawEventType`) | | `RETURN_INBOUND_COMPLETED` | 退货入库完成 | `returns` | | `INVENTORY_CHANGED` | 库存变动(增量流水) | `inventory` | | `UNKNOWN` | 无法识别 | — | ### 各载荷 **`OutboundPayload`(面单)** ```java trackingNumber / carrier / shippingMethodCode / deliverOrderNo ``` **`ReturnPayload`** ```java lines[] → lineId / providerSku / quantity / disposition / batchNo / batchParams ``` **`InventoryPayload`** ```java sku / inventoryType / overWarehouse / sourceNo / planNo / orderNo providerOperationType // 仓方单据类型码 inbound // Boolean:true 入库 / false 出库 / null 未知 quantity // 恒为正,方向看 inbound ``` **`InboundPayload`** ```java receivedQuantity / cartonQuantity ``` ## 4. 验签 ### 运去哪算法 ``` data = appKey + "|" + timestamp + "|" + rawBody signature = Base64(HmacSHA256(appSecret, data)) ``` 请求头:`X-AppKey` / `X-Timestamp` / `X-Signature`。 实现在 `WebhookSignatures`(core 通用)+ `YqnLabelCallbackParser.verify`(yqn)。 ### 三个细节 **① 恒定时间比较** ```java // 不用 String.equals:提前返回会把「匹配了几位」泄漏成时间差 WebhookSignatures.constantTimeEquals(expected, actual) ``` **② 时间戳窗口 5 分钟** ```java WebhookSignatures.requireFreshTimestamp(timestampMillis, nowMillis, tolerance) ``` **③ 头名大小写不敏感** 不同网关会改写大小写,`WebhookSignatures.header()` 逐个忽略大小写比对。 ## 5. 报文分派 运去哪**不按路径区分回调**——四种报文打同一个地址。适配器按报文特征分派: ``` 含 processMode → 退货入库完成(API 142) 含 opType → 库存变动(API 150) 含 orderNoType → 业务单据变动(API 154) 否则 → 面单购买成功(API 149) ``` **风险**:如果报文的值里恰好出现同名字面量,会误分派。目前接受这个风险,因为字段名都很独特。 ## 6. 宿主要做什么 ```java @RestController public class WarehouseCallbackController { private final WarehouseSdk sdk; private final SecretProvider secrets; // 按 provider 取 appKey/appSecret private final WarehouseWebhookDedupStore dedup; private final UnmatchedCallbackStore unmatched; @PostMapping("/user/callback/yqn") public ResponseEntity> yqn( @RequestBody String rawBody, // ← 必须 String @RequestHeader Map headers) { // ← 原始头 List callbacks; try { callbacks = sdk.webhook( WarehouseProvider.YQN, secrets.forProvider(WarehouseProvider.YQN), headers, rawBody, System.currentTimeMillis()); } catch (WarehouseWebhookVerificationException e) { // 验签失败:返回 4xx,不重试 return ResponseEntity.badRequest().body(reply(400, "signature invalid")); } for (WarehouseCallback cb : callbacks) { // 去重:仓方可能重推 String key = cb.eventId() != null ? cb.eventId() : cb.fingerprint(); if (!dedup.claim(cb.sourceProvider().name(), key)) { continue; // 重复事件,直接丢 } try { dispatch(cb); } catch (Exception e) { dedup.release(cb.sourceProvider().name(), key); // 失败放回,允许重投 throw e; } } return ResponseEntity.ok(reply(200, "success")); } private void dispatch(WarehouseCallback cb) { switch (cb.eventType()) { case LABEL_PURCHASED: orderService.bindTracking(cb.requestNo(), cb.outbound()); break; case ORDER_STATUS_CHANGED: // rawEventType = "ORDER_STATUS:<单据类型>",rawStatus = 状态码 // 状态码含义随单据类型变化,必须成对解释 orderService.advanceStatus(cb.providerOrderNo(), cb.rawEventType(), cb.rawStatus()); break; case RETURN_INBOUND_COMPLETED: returnService.applyResult(cb.providerOrderNo(), cb.returns()); break; case INVENTORY_CHANGED: // 增量流水,不是快照;inbound 可能为 null(方向未知) inventoryService.applyDelta(cb.inventory()); break; default: unmatched.save(cb.sourceProvider().name(), null, cb.rawBody(), "unknown event"); } } } ``` ## 7. 四个必须注意的点 ### ① 必须用 `@RequestBody String` 如果先反序列化成对象、再转回 JSON,字段顺序或空白会变化,**签名就对不上了**。 ### ② 验签失败要返回非成功 `WarehouseWebhookVerificationException` 抛出后不要吞掉。仓方需要知道被拒。 ### ③ 响应的 `code` 值要跟仓方确认 运去哪文档写「`code: 200` 成功」,但示例里给的是 `1`。**如果返回 200 而仓方认为失败,会无限重推**。 ### ④ `inbound()` 是三态 ```java Boolean inbound = cb.inventory().inbound(); if (inbound == null) { /* 方向未知,留档人工处理 */ } ``` 不能写成 `if (!inbound)` —— `Boolean` 为 null 时拆箱会 NPE。 ## 8. 去重指纹 仓方没给 `eventId` 时用 `fingerprint()`: ``` sourceProvider | eventType | providerOrderNo | requestNo | rawStatus | occurredAt ``` 参与计算的字段都是**同一事件重复推送时不变**的。载荷内容不参与——里面可能有随推送变化的字段。 ## 9. 未实现的仓 `XincangAdapter` 目前**没有实现 `WarehouseWebhookCapable`**,调用会抛 `WarehouseUnsupportedCapabilityException`。