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

# 回调(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`。