You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
263 lines
9.1 KiB
263 lines
9.1 KiB
|
1 week ago
|
# 回调(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<WarehouseCallback>
|
||
|
|
▼
|
||
|
|
┌──────────────────────────────────────┐
|
||
|
|
│ 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<Map<String, Object>> yqn(
|
||
|
|
@RequestBody String rawBody, // ← 必须 String
|
||
|
|
@RequestHeader Map<String, String> headers) { // ← 原始头
|
||
|
|
|
||
|
|
List<WarehouseCallback> 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`。
|