Browse Source
四篇:
- README.md 索引
- architecture.md 分层、枚举分层、能力矩阵、幂等、SPI、设计约定
- callback.md 回调链路、出参模型、验签、宿主要做什么、四个注意点
- notes.md 通用注意事项(写操作/状态/时区/单位/字段口径/测试)
- yqn/README.md 运去哪接入汇总:19 个接口、业务流程、真机联调结论、
平台限制、字段口径、两套码表、单位、探针用法
运去哪这篇记录了真机验证的结果,包括 4 处文档与实际不符
(库存/物流产品的参数名、仓库目录的成功码、运费试算无 code 字段)。
Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
6 changed files with 897 additions and 0 deletions
@ -0,0 +1,17 @@
@@ -0,0 +1,17 @@
|
||||
# 三方仓接入文档 |
||||
|
||||
本目录是 `warehouse-sdk-*` 三方仓模块的说明文档汇总。 |
||||
|
||||
| 文档 | 内容 | |
||||
|---|---| |
||||
| [architecture.md](architecture.md) | 三方仓架构:分层、模块依赖、门面/能力/适配器/SPI | |
||||
| [callback.md](callback.md) | 回调(Webhook)链路:验签、分派、出参模型、宿主怎么接 | |
||||
| [yqn/README.md](yqn/README.md) | 运去哪:接口汇总、联调结论、平台限制 | |
||||
| [notes.md](notes.md) | 通用注意事项:写操作、幂等、时区、单位、字段口径 | |
||||
|
||||
## 快速定位 |
||||
|
||||
- 想知道**能力有哪些** → `architecture.md` 的「能力矩阵」 |
||||
- 想知道**回调怎么接** → `callback.md` 的「宿主要做什么」 |
||||
- 想知道**运去哪对接了什么** → `yqn/README.md` 的「接口清单」 |
||||
- 想知道**踩过什么坑** → `notes.md` |
||||
@ -0,0 +1,186 @@
@@ -0,0 +1,186 @@
|
||||
# 三方仓架构 |
||||
|
||||
## 1. 定位 |
||||
|
||||
`common-ecommerce` 是纯 SDK 库,嵌入宿主(OMS)进程运行: |
||||
|
||||
- **不访问数据库 / Redis / MQ** |
||||
- **不私起线程或定时器** |
||||
- **不监听端口**(回调由宿主暴露 HTTP 入口) |
||||
|
||||
所有外部副作用通过 SPI 注入。 |
||||
|
||||
## 2. 分层 |
||||
|
||||
``` |
||||
┌──────────────────────────────────────────────────────────┐ |
||||
│ 宿主 OMS │ |
||||
│ 业务代码 · MySQL/Redisson 实现的 SPI · HTTP 回调入口 │ |
||||
└───────────────────────┬──────────────────────────────────┘ |
||||
│ 只依赖门面 + 模型 |
||||
┌───────────────────────▼──────────────────────────────────┐ |
||||
│ warehouse-sdk-core │ |
||||
│ ┌────────────┐ ┌──────────────┐ ┌──────────────────┐ │ |
||||
│ │ sdk 门面 │ │ capability │ │ model │ │ |
||||
│ │ WarehouseSdk│─▶│ OutboundCapable│─▶│ OutboundOrder 等 │ │ |
||||
│ │ ...Operations│ │ InboundCapable │ │ (跨仓统一模型) │ │ |
||||
│ └────────────┘ │ ... │ └──────────────────┘ │ |
||||
│ └──────────────┘ │ |
||||
│ ┌────────────┐ ┌──────────────┐ ┌──────────────────┐ │ |
||||
│ │ enums │ │ spi │ │ error │ │ |
||||
│ │ 底层枚举 │ │ Repository │ │ WarehouseException│ │ |
||||
│ │ │ │ Sink │ │ 及子类 │ │ |
||||
│ └────────────┘ └──────────────┘ └──────────────────┘ │ |
||||
└───────────────────────┬──────────────────────────────────┘ |
||||
│ 实现 capability |
||||
┌───────────────────────▼──────────────────────────────────┐ |
||||
│ warehouse-sdk-yqn / -xincang(各仓适配器) │ |
||||
│ adapter(能力实现 + 映射)· dto(按接口拆分)· enums(平台枚举)│ |
||||
│ webhook(回调验签与解析)· http(请求构造 / 限流 / 信封) │ |
||||
└───────────────────────┬──────────────────────────────────┘ |
||||
▼ |
||||
三方仓 API |
||||
``` |
||||
|
||||
依赖方向严格单向:**宿主 → core ← 适配器**。适配器之间互不依赖。 |
||||
|
||||
## 3. 枚举分层 |
||||
|
||||
两层,各管一段: |
||||
|
||||
| 层 | 位置 | 内容 | 谁用 | |
||||
|---|---|---|---| |
||||
| **底层枚举** | `warehouse-sdk-core/enums` | 业务语义 + SDK 自编 `code` + 中文名 | 宿主做 `if/switch/SQL` | |
||||
| **平台枚举** | `warehouse-sdk-yqn/enums` 等 | 仓方原始码 + `toCore()` | 适配器内部映射 | |
||||
|
||||
例: |
||||
|
||||
```java |
||||
// core:不认识任何仓的码 |
||||
public enum OutboundStatus { |
||||
SUBMITTED(20, "已下发", 1), |
||||
SHIPPED(70, "已交运", 6), |
||||
UNKNOWN(0, "未知", -1); |
||||
} |
||||
|
||||
// yqn:带仓方原值 |
||||
public enum YqnOutboundStatus { |
||||
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED), |
||||
SHIPPED("shipped", OutboundStatus.SHIPPED), |
||||
UNKNOWN(null, OutboundStatus.UNKNOWN); |
||||
} |
||||
``` |
||||
|
||||
**规则**: |
||||
|
||||
- 底层枚举的 `code` 由 SDK 分配,**永不复用、永不重排** |
||||
- 底层枚举**只追加不合并**——合并了就分不出「待审核」和「审核中」了 |
||||
- 认不出的归 `UNKNOWN`,**不猜** |
||||
- 仓方原值同时保留在模型的 `rawStatus` / `rawType` 字段里 |
||||
|
||||
## 4. 能力矩阵 |
||||
|
||||
`WarehouseCapability`(19 个): |
||||
|
||||
| 能力 | 说明 | 运去哪 | 信仓 | |
||||
|---|---|:---:|:---:| |
||||
| `PRODUCT` | 商品建档 / 更新 | ✅ | ✅ | |
||||
| `OUTBOUND` | 出库创建 / 查询 / 取消 | ✅ | ✅ | |
||||
| `PLATFORM_LABEL_DELIVERY` | 平台面单下发 | ✅ | — | |
||||
| `FEE_SETTLEMENT` | 结算明细 | ✅ | — | |
||||
| `FEE_ESTIMATE` | 运费试算 | ✅ | — | |
||||
| `INVENTORY_QUERY` | 库存查询 | ✅ | ✅ | |
||||
| `INBOUND` | 入库创建 / 查询 | ✅ | — | |
||||
| `BOX_LABEL` | 入库箱标(异步) | ✅ | — | |
||||
| `SKU_LABEL` | SKU 标(异步) | ✅ | — | |
||||
| `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ | |
||||
| `WAREHOUSE_DIRECTORY` | 仓库目录 | ✅ | — | |
||||
| `WEBHOOK` | 状态回调 | ✅ | — | |
||||
| `TRANSFER` | 仓间调拨 | ✅ | ✅ | |
||||
| `RETURN` | 退货发起 / 查询 | ✅ | — | |
||||
| `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — | |
||||
| `TRACKING` | 物流轨迹 | ✅ | — | |
||||
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — | |
||||
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — | |
||||
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — | |
||||
|
||||
**能力是事实表,不是推荐**:调用未声明的能力抛 `WarehouseUnsupportedCapabilityException`,不静默降级。 |
||||
|
||||
## 5. 模块依赖 |
||||
|
||||
``` |
||||
sdk-common |
||||
↑ |
||||
├── warehouse-sdk-core ──┬── warehouse-sdk-yqn |
||||
│ └── warehouse-sdk-xincang |
||||
├── warehouse-sdk-testkit ──▶ warehouse-sdk-core |
||||
└── sdk-testkit |
||||
``` |
||||
|
||||
## 6. 一次调用的链路 |
||||
|
||||
以查订单详情为例: |
||||
|
||||
```java |
||||
sdk.warehouses("YQN-RF_NY_US", conn) // ① 从 WarehouseRepository 取账户,定 provider |
||||
.outbound() |
||||
.get(OutboundRef.ofRequestNo("OB-1")); // ② |
||||
``` |
||||
|
||||
``` |
||||
① WarehouseSdk.requireAccount(warehouseCode) |
||||
→ WarehouseRepository.findByWarehouseCode() |
||||
→ 按 account.provider() 选适配器 |
||||
② WarehouseOutbounds.get() |
||||
→ 能力检查 supports(OUTBOUND) |
||||
→ CallSupport.observe(审计 + 计时) |
||||
→ YqnAdapter.get(ctx, ref) |
||||
③ YqnAdapter |
||||
→ 校验 / 构造请求(YqnOutboundMapper) |
||||
→ YqnRequestFactory 注入 x-api-key + requestId |
||||
→ YqnRateLimiter 限流 |
||||
→ HttpTransport 发送 |
||||
→ YqnEnvelope 校验信封 |
||||
④ 响应 → YqnOutboundMapper.toOrder() |
||||
→ 平台枚举 toCore() |
||||
→ 返回 OutboundOrder(含 rawStatus / sourceProvider) |
||||
``` |
||||
|
||||
## 7. 写操作的幂等 |
||||
|
||||
所有写操作在门面层强制经 `IdempotencyGuard`,调用方无法绕过。 |
||||
|
||||
| 操作 | 幂等键 | |
||||
|---|---| |
||||
| 出库创建 | `warehouseCode + outboundRequestNo + create` | |
||||
| 出库取消 | `warehouseCode + outboundRequestNo + cancel` | |
||||
| 入库创建 | `warehouseCode + inboundRequestNo + create` | |
||||
| 调拨创建 | `warehouseCode + transferRequestNo + create` | |
||||
| 调拨审核 | `warehouseCode + transferRequestNo + approve` | |
||||
| 退货创建 | `warehouseCode + returnRequestNo + create` | |
||||
| 退货条目处理 | `warehouseCode + providerReturnNo + lineId + process` | |
||||
| 销毁创建 | `warehouseCode + destructionNo + create` | |
||||
|
||||
**注意**:销毁按明细行做键(不是整单)——一张退货单的多行可以分别上架 / 销毁。 |
||||
|
||||
## 8. 宿主必须实现的 SPI |
||||
|
||||
| SPI | 用途 | 必需 | |
||||
|---|---|:---:| |
||||
| `WarehouseRepository` | 按仓编码取接入账户 | ✅ | |
||||
| `WarehouseAccount` | 仓编码 / provider / 凭据引用 / 时区 | ✅ | |
||||
| `IdempotencyStore` | 写操作幂等(与渠道域共用) | 写操作必需 | |
||||
| `WarehouseSink` | 落库(出库 / 入库 / 库存 / 退货 / 销毁 / 账单) | 按需 | |
||||
| `WarehouseWebhookDedupStore` | 回调去重 | 回调必需 | |
||||
| `UnmatchedCallbackStore` | 匹配不到单据的回调留档 | 回调建议 | |
||||
|
||||
## 9. 关键设计约定 |
||||
|
||||
| 约定 | 说明 | |
||||
|---|---| |
||||
| **rawStatus 必须落库** | 与 `sourceProvider` 成对保存;它是映射调整后唯一能重跑的依据 | |
||||
| **不静默降级** | 能力缺失 / 字段不支持都显式抛异常 | |
||||
| **不读系统时钟** | 时间由 `Clock` 注入;回调的 `nowMillis` 由宿主传 | |
||||
| **不猜** | 认不出的状态归 `UNKNOWN`,不猜成相近值 | |
||||
| **单位写进字段名** | `weightGrams` / `lengthCm` / `totalVolumeCbm`,避免靠注释约定 | |
||||
| **PII 不落日志** | `ShipTo` / `WarehouseInfo` 联系人信息不打印 | |
||||
@ -0,0 +1,262 @@
@@ -0,0 +1,262 @@
|
||||
# 回调(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`。 |
||||
@ -0,0 +1,192 @@
@@ -0,0 +1,192 @@
|
||||
# 通用注意事项 |
||||
|
||||
跨仓通用的约定与踩过的坑。运去哪专属的见 [yqn/README.md](yqn/README.md)。 |
||||
|
||||
## 1. 写操作 |
||||
|
||||
### 所有写操作强制幂等 |
||||
|
||||
门面层拦截,调用方无法绕过。未注入 `IdempotencyStore` 时直接抛异常,不提供「无幂等」的降级路径。 |
||||
|
||||
**原因**:出库重复下发 = 重复发货;调拨重复下发 = 搬两次货;销毁重复下发 = 报废两次。 |
||||
|
||||
### 销毁 / 退货按明细行做键 |
||||
|
||||
```java |
||||
// 退货条目处理:一张单的多行可以分别上架 / 销毁 |
||||
warehouseCode + providerReturnNo + lineId + process |
||||
``` |
||||
|
||||
按整单做键会把「第二行上架」误判成重复。 |
||||
|
||||
### 联调时不要随便跑写接口 |
||||
|
||||
写接口会真实创建单据。没有 Testing 环境时,只跑查询类探针。运去哪的 PR 环境可以走单,但创建的单据要能识别(探针用 `PROBE-<时间戳>` 前缀)。 |
||||
|
||||
## 2. 状态与原始值 |
||||
|
||||
### rawStatus 必须落库 |
||||
|
||||
```java |
||||
// 模型的固定搭配 |
||||
OutboundStatus status; // 归一化,给代码判断 |
||||
String rawStatus; // 仓方原话,给展示和排查 |
||||
WarehouseProvider sourceProvider; // 解释 rawStatus 的前提 |
||||
``` |
||||
|
||||
**rawStatus 必须与 sourceProvider 成对保存**——同一个数字在不同仓含义不同。 |
||||
它是映射调整后**唯一能重跑、修正历史数据**的依据;只存枚举则改映射等于污染存量。 |
||||
|
||||
### 认不出的状态归 UNKNOWN,不猜 |
||||
|
||||
反例(已修): |
||||
|
||||
```java |
||||
// 之前:contains("SHIP") 把 UNSHIPPED 判成 SHIPPED |
||||
// 后果:未发货被判已交运,取消被锁 |
||||
``` |
||||
|
||||
正确做法:按完整值精确匹配,未收录归 `UNKNOWN`,原值留在 `rawStatus`。 |
||||
|
||||
### 底层枚举只追加,不合并 |
||||
|
||||
合并了就分不出「待审核」和「审核中」。加新仓时只加值,不改已有值的语义。 |
||||
|
||||
## 3. 时区 |
||||
|
||||
### 仓方给的时间不带时区 |
||||
|
||||
`yyyy-MM-dd HH:mm:ss` 需要知道它属于哪个地方。由调用方经 `WarehouseConnection` 传: |
||||
|
||||
```java |
||||
WarehouseConnection.of(baseUrl, secret, ZoneId.of("America/New_York")) |
||||
``` |
||||
|
||||
**未指定时按 UTC 解释,不猜成北京时间。** 美国仓猜错会整体平移 13–16 小时。 |
||||
|
||||
### SDK 不读系统时钟 |
||||
|
||||
- 普通调用:`WarehouseContext.clock()` |
||||
- 回调时间戳校验:`nowMillis` 由宿主传入 |
||||
|
||||
## 4. 单位 |
||||
|
||||
**单位写进字段名**,不靠注释约定: |
||||
|
||||
```java |
||||
double weightGrams; // 不是 weight |
||||
double lengthCm; // 不是 length |
||||
Double totalVolumeCbm; |
||||
Double totalWeightKg; |
||||
``` |
||||
|
||||
### 换算在适配器里做 |
||||
|
||||
仓方给的单位不同(oz / inch / lb / in³),**适配器统一换算后落模型**,宿主不用各仓处理。 |
||||
|
||||
例:运去哪轨迹的 `parcel.weight`(oz)→ `TrackingInfo.parcelWeightGrams()`(g)。 |
||||
|
||||
### 单位未核实时要标注 |
||||
|
||||
```java |
||||
/** |
||||
* <b>单位待核实</b>:文档未标单位,这里按 kg 原样透传; |
||||
* 若确认是 lb,数值会偏大约 2.2 倍。 |
||||
*/ |
||||
``` |
||||
|
||||
## 5. 字段口径 |
||||
|
||||
### 同一个名字在不同接口含义可能不同 |
||||
|
||||
| 字段 | 含义 | |
||||
|---|---| |
||||
| `OutboundOrder.providerOrderId` | **仓侧单号** | |
||||
| `OutboundQuery.outboundRequestNo` | **我们下发的来源单号**(原名 `providerOrderId` 有误导,已改) | |
||||
| `FeeQuery.saleOrderNo` | 运去哪要**数字单号**(`providerOrderId`),不是来源单号 | |
||||
| `ReturnProcessCommand.lineId` | 来自**退货查询接口**,不是回调 | |
||||
|
||||
### 传出去了不等于查得回来 |
||||
|
||||
下单发的字段,查详情时不一定返回。例: |
||||
|
||||
- 运去哪订单详情不回传 `orderRef`(平台单号)和 `requestedAt` |
||||
- 宿主需要这些值时自行保存映射 |
||||
|
||||
## 6. 能力与降级 |
||||
|
||||
### 能力缺失显式抛异常 |
||||
|
||||
```java |
||||
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING); |
||||
``` |
||||
|
||||
不静默返回空集合 / 空列表——调用方分不清「不支持」和「没数据」。 |
||||
|
||||
### 不静默降级 |
||||
|
||||
例:平台面单要求仓声明 `PLATFORM_LABEL_DELIVERY`,缺失时拒绝,**不自动退回仓自有面单**——面单归属影响标发方式。 |
||||
|
||||
### 能力位要与实现一致 |
||||
|
||||
反例(已修):声明了 `SPLIT` 但接口没有拆单字段。调用方看能力位会以为能用。 |
||||
|
||||
## 7. 校验的位置 |
||||
|
||||
### 跨仓共有的约束放模型构造期 |
||||
|
||||
```java |
||||
if (b.inventoryType != 0 && b.inventoryType != 1) { |
||||
throw new IllegalArgumentException("inventoryType must be 0 or 1"); |
||||
} |
||||
``` |
||||
|
||||
### 仓方协议特有的约束放适配器 |
||||
|
||||
```java |
||||
// 尺寸与每页数量联动(运去哪箱标) |
||||
if (perPage == 1 && !size.singlePerPage()) { throw ... } |
||||
``` |
||||
|
||||
**原因**:`TransferCommand` 这类模型承载多家仓字段的并集,在模型里加强制校验会让另一家仓用不了。 |
||||
|
||||
## 8. 回调 |
||||
|
||||
见 [callback.md](callback.md)。三个要点: |
||||
|
||||
1. **`@RequestBody String`** —— 必须拿原文,反序列化会破坏签名 |
||||
2. **验签失败返回 4xx** —— 不要吞 |
||||
3. **`Boolean inbound()` 是三态** —— 不能 `if (!inbound)` |
||||
|
||||
## 9. 测试 |
||||
|
||||
### 契约测试用 `RecordingTransport` |
||||
|
||||
```java |
||||
RecordingTransport.create().route(PATH, req -> Responses.ok("...")) |
||||
``` |
||||
|
||||
验证「按文档构造的报文能正确映射」,不打真实接口。 |
||||
|
||||
### 真机探针默认跳过 |
||||
|
||||
```java |
||||
@EnabledIfSystemProperty(named = "yqn.probe", matches = "true") |
||||
``` |
||||
|
||||
**真机验证不能省**——运去哪有 4 处文档与实际不符(参数名、成功码、字段缺失),只有真跑才能发现。 |
||||
|
||||
## 10. PII |
||||
|
||||
`ShipTo` / `WarehouseInfo` 含联系人、电话、邮箱: |
||||
|
||||
- 不打印完整报文(探针只打字段摘要) |
||||
- 落库与日志按宿主安全策略处理 |
||||
- 异常信息里 `safeRelay()` 只保留前 300 字节 |
||||
|
||||
## 11. 已发现但未修的问题 |
||||
|
||||
| 项 | 说明 | |
||||
|---|---| |
||||
| `InboundCommand` 请求侧部分字段 | 已补,但运去哪对 `lineCode` 有「项目必须存在」的约束 | |
||||
| 出库 `declaredTotal` | 运去哪无落点,不影响(行级 `skuAmount` 已覆盖) | |
||||
@ -0,0 +1,238 @@
@@ -0,0 +1,238 @@
|
||||
# 运去哪(YQN)接入汇总 |
||||
|
||||
## 1. 基本信息 |
||||
|
||||
| 项 | 值 | |
||||
|---|---| |
||||
| 适配器 ID | `yqn` | |
||||
| PR 环境 | `https://pr-hwc-open-api.yqn.com` | |
||||
| 轨迹接口 | `https://pr-ship-api.yqn.com`(**不同主机**) | |
||||
| 鉴权 | 组织级固定 token,请求头 `x-api-key` | |
||||
| 限流 | 保守默认 2 req/s/仓(仓方未公开) | |
||||
| ERP 后台 | `https://pr-erp.yqn.com` | |
||||
|
||||
## 2. 接口清单(19 个已对接) |
||||
|
||||
| # | 接口 | 路径 | 能力位 | |
||||
|---|---|---|---| |
||||
| 1 | 商品创建 / 编辑 | `POST /v1/product/save` | `PRODUCT` | |
||||
| 2 | 创建销售订单 | `POST /v1/saleOrder/create` | `OUTBOUND` | |
||||
| 3 | 订单详情 | `POST /v1/saleOrder/findOne` | `OUTBOUND` | |
||||
| 4 | 取消销售订单 | `POST /v1/saleOrder/cancel` | `OUTBOUND` | |
||||
| 5 | 库存查询 | `GET /v2/inventory/get_inventory_by_page` | `INVENTORY_QUERY` | |
||||
| 6 | 创建调拨单 | `POST /v2/transferOutboundPlan/create` | `TRANSFER` | |
||||
| 7 | 创建入库计划 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | |
||||
| 8 | 查询入库计划 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` | |
||||
| 9 | 打印箱标 | `POST /v1/inbound/generateBoxLabel` | `BOX_LABEL` | |
||||
| 10 | 打印 SKU 标 | `POST /v1/inbound/generateItemLabel` | `SKU_LABEL` | |
||||
| 11 | 创建销售退货 | `POST /v3/saleReturn/createSaleReturnPlan` | `RETURN` | |
||||
| 12 | 退货计划查询 | `POST /v3/saleReturn/getInboundPlanInfo` | `RETURN` | |
||||
| 13 | 退货条目处理 | `POST /v3/saleReturn/addProcessMode` | `RETURN_DISPOSITION` | |
||||
| 14 | 创建销毁计划 | `POST /v1/destroyPlan/createDestroyPlan` | `DESTRUCTION` | |
||||
| 15 | 物流轨迹 | `GET ship-api/api/v2/orderShipment/track/{trackingNo}` | `TRACKING` | |
||||
| 16 | 结算明细 | `POST /v1/warehouse/operation/costs/detail` | `FEE_SETTLEMENT` | |
||||
| 17 | 运费试算 | `POST /v1/saleOrder/calculate` | `FEE_ESTIMATE` | |
||||
| 18 | 物流产品清单 | `GET /v2/sysCarrierGroup/getCarrierGroupList` | `LOGISTICS_PRODUCT` | |
||||
| 19 | 仓库目录 | `GET /v1/warehouse/findAll` | `WAREHOUSE_DIRECTORY` | |
||||
|
||||
### 回调(4 个) |
||||
|
||||
| 回调 | 触发时机 | 载荷 | |
||||
|---|---|---| |
||||
| API 149 面单购买成功 | 面单出单后 | 运单号 / 承运商 / 发货方式 | |
||||
| API 154 业务单据变动 | 入库 / 调拨 / 出库 / 退货认领状态变更 | 状态码(含义随单据类型) | |
||||
| API 142 退货入库完成 | 退货上架 / 销毁后 | 处理方式 + 上架数量 + 批次 | |
||||
| API 150 库存变动 | 库存增减时 | 增量流水 | |
||||
|
||||
## 3. 业务流程 |
||||
|
||||
### 出库 |
||||
|
||||
``` |
||||
① 查物流产品(校验渠道可用) GET /v2/sysCarrierGroup/getCarrierGroupList |
||||
② 运费试算(可选) POST /v1/saleOrder/calculate |
||||
③ 下发出库单 POST /v1/saleOrder/create |
||||
└─ 平台面单时带 attachInfoItems(面单文件) |
||||
④ 查详情 / 拆单包裹 POST /v1/saleOrder/findOne |
||||
⑤ 取消(未发货时) POST /v1/saleOrder/cancel |
||||
⑥ 面单回调 API 149 |
||||
⑦ 状态变更回调 API 154 |
||||
⑧ 物流轨迹 GET ship-api/api/v2/orderShipment/track/{no} |
||||
``` |
||||
|
||||
### 入库 |
||||
|
||||
``` |
||||
① 创建入库计划 POST /v1/inbound/createInboundPlan |
||||
② 查询入库计划 POST /v1/inbound/getInboundPlanInfo |
||||
③ 打印箱标 / SKU 标 POST /v1/inbound/generateBoxLabel |
||||
POST /v1/inbound/generateItemLabel |
||||
④ 状态回调 API 154 |
||||
``` |
||||
|
||||
### 退货 |
||||
|
||||
``` |
||||
① 创建退货预约 POST /v3/saleReturn/createSaleReturnPlan |
||||
② 仓收货检验、上架 / 销毁 |
||||
③ 退货入库回调 API 142(结果来源) |
||||
④ 查退货计划(拿明细行 id) POST /v3/saleReturn/getInboundPlanInfo |
||||
⑤ 按行设置处理方式 POST /v3/saleReturn/addProcessMode |
||||
``` |
||||
|
||||
> ④ 是必需的:API 77(退货条目处理)要传仓侧明细行 `id`, |
||||
> 只能从 ④ 的 `saleReturnOrderItems[].id` 拿。 |
||||
|
||||
### 调拨 / 库存 / 费用 |
||||
|
||||
``` |
||||
创建调拨单 POST /v2/transferOutboundPlan/create |
||||
库存查询 GET /v2/inventory/get_inventory_by_page |
||||
库存变动回调 API 150 |
||||
结算明细 POST /v1/warehouse/operation/costs/detail |
||||
``` |
||||
|
||||
## 4. 真机联调结论(PR 环境 2026-11-11) |
||||
|
||||
用 RF_NY_US 仓、DM00001 SKU、WLC-FEDEX 发货方式跑全链路。 |
||||
|
||||
### 通过的 |
||||
|
||||
| 接口 | 实测 | |
||||
|---|---| |
||||
| 创建销售订单 | ✅ 返回 `providerOrderId=200171697` | |
||||
| 订单详情 | ✅ `rawStatus=unshipped` → `SUBMITTED` | |
||||
| 取消订单 | ✅ 「取消订单成功」 | |
||||
| 库存查询 | ✅ 2 条(可售 164 / 不可售 0) | |
||||
| 运费试算 | ✅ 返回 1 个仓 1 个渠道 | |
||||
| 创建入库计划 | ✅ `IP8826111100005` | |
||||
| 查询入库计划 | ✅ planned=1 packed=1 boxes=1 | |
||||
| 创建调拨单 | ✅ `UAT-TF2611110002` | |
||||
| 创建退货 | ✅ 提交成功 | |
||||
| 结算明细 | ✅ 接口通(新单无费用,返回 0 条) | |
||||
| 仓库目录 | ✅ 1 个仓 | |
||||
| 物流产品 | ✅ 100 个 | |
||||
|
||||
### 文档与实际不符(已按实际修正) |
||||
|
||||
| 接口 | 文档写的 | 实际 | |
||||
|---|---|---| |
||||
| 库存查询 | 参数名 `query.warehouseCodes` | **`warehouseCodes`**(扁平) | |
||||
| 物流产品 | 参数名 `query.warehouseCode` | **`warehouseCode`**(扁平) | |
||||
| 仓库目录 | 成功 `status: 1` | **`status: 200`** | |
||||
| 运费试算 | 有 `code` 字段 | **没有 `code`**,只有 `status: 200` | |
||||
|
||||
### 仓方环境问题(非 SDK 问题) |
||||
|
||||
| 接口 | 现象 | |
||||
|---|---| |
||||
| 打印箱标 / SKU 标 | 仓方内部 `Read timed out`(`HWC-OMS-ORDERCENTER` 超时) | |
||||
|
||||
### 业务约束(非 SDK 问题) |
||||
|
||||
| 接口 | 现象 | 原因 | |
||||
|---|---|---| |
||||
| 创建入库计划 | 传 `lineCode` 报「项目名称不存在」 | 仓方项目名要真实存在 | |
||||
| 创建销毁 | 「DM00001 库存不足」 | 需不可售库存,测试仓为 0 | |
||||
| 商品建档 | 「当前状态不能编辑商品」 | 测试 SKU 已存在且不可编辑 | |
||||
|
||||
## 5. 平台限制(已知且无法解决) |
||||
|
||||
| 接口 | 字段 | 情况 | |
||||
|---|---|---| |
||||
| 订单详情 `findOne` | `orderRef`(平台单号) | **不回传**,恒 null,宿主自行保存映射 | |
||||
| 订单详情 `findOne` | `requestedAt`(下单时间) | **不回传**,恒 null | |
||||
| 退货计划查询 | `createdAt` | **无创建时间** | |
||||
| 结算明细 | `documentNo`(单据号) | **不返回**,对账靠 `saleOrderNo + settledAt + feeName` | |
||||
| 结算明细 | `providerSku` | **不返回**,费用只到订单 / 仓粒度 | |
||||
| 退货条目处理 | `lineId` | 需先查 API 83 才能拿到 | |
||||
|
||||
## 6. 字段口径(容易传错的) |
||||
|
||||
| 字段 | 要传什么 | |
||||
|---|---| |
||||
| 结算明细 `saleOrderNo` | **数字单号**(创建返回的 `providerOrderId`,如 `200171697`),**不是**来源单号 | |
||||
| 退货条目处理 `lineId` | 来自 **退货计划查询**(API 83)的 `saleReturnOrderItems[].id`,不是回调里的 | |
||||
| 订单详情查询键 | **来源单号**(`outboundRequestNo`),不是 `providerOrderId` | |
||||
| 入库查询键 | 入库单号或来源单号(`orderNo` 两者均可) | |
||||
| 商品海关申报 | 币种**必须 USD**,非 USD 直接拒绝 | |
||||
|
||||
## 7. 枚举映射(两套码表,别混) |
||||
|
||||
### 退货的处理方式 |
||||
|
||||
| API 81 预约(`returnDealMethod`) | API 77 检验后(`goodsReturnType`) | API 142 回调(`processMode`) | |
||||
|---|---|---| |
||||
| 0 客户自提 | 0 客户自提 | 2 销毁 | |
||||
| 1 拍照确认 | 2 销毁 | 3 不良品上架 | |
||||
| 2 销毁 | 3 上架(良品) | 4 换标上架 | |
||||
| 5 仓库确认 | 4 换标上架 | 5 良品上架 | |
||||
|
||||
**三套码值不能互换。** |
||||
|
||||
### 单据状态 |
||||
|
||||
API 154 回调的 `orderNoStatus` 含义**随 `orderNoType` 变化**: |
||||
|
||||
| orderNoType | 5 的含义 | 80 的含义 | |
||||
|---|---|---| |
||||
| 1 入库计划单 | 审核通过 | — | |
||||
| 2/3 调拨 | 待审核 | 已完成 | |
||||
| 4 销售出库 | 已发货 | — | |
||||
| 5 退货认领 | 待处理 | — | |
||||
|
||||
## 8. 单位 |
||||
|
||||
| 字段 | 单位 | 说明 | |
||||
|---|---|---| |
||||
| 库存 / 商品尺寸 | cm、g | 运去哪原值 | |
||||
| 调拨 `totalWeight` | **kg** | 真机确认(1 件 500g → 1000.0) | |
||||
| 调拨 `totalVolume` | m³ | 推测同口径 | |
||||
| 入库 `totalWeight` | kg | 文档明确 | |
||||
| 入库 `totalVolume` | CBM | 文档明确 | |
||||
| 轨迹 `parcel.weight` | oz → **已换算成 g** | 适配器内换算 | |
||||
| 轨迹 `parcel.length` | inch → **已换算成 cm** | 适配器内换算 | |
||||
|
||||
## 9. 时区 |
||||
|
||||
仓方给的 `yyyy-MM-dd HH:mm:ss` **不带时区**,由调用方经 `WarehouseConnection` 传入: |
||||
|
||||
```java |
||||
WarehouseConnection.of( |
||||
YqnConstants.PR_BASE_URL, |
||||
ChannelSecret.builder().appSecret(token).build(), |
||||
ZoneId.of("America/New_York")); // ← 按仓所在地传 |
||||
``` |
||||
|
||||
**未指定时按 UTC 解释,不猜成北京时间。** |
||||
|
||||
## 10. 联调探针 |
||||
|
||||
两个探针,默认跳过: |
||||
|
||||
```bash |
||||
# 只读(7 个查询接口) |
||||
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \ |
||||
-Dyqn.probe=true \ |
||||
-Dyqn.probe.token=<x-api-key> \ |
||||
-Dyqn.probe.providerWarehouseId=RF_NY_US \ |
||||
-Dtest=YqnReadOnlyProbeTest test |
||||
|
||||
# 全链路(15 步,会真实创建单据,仅限 PR) |
||||
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \ |
||||
-Dyqn.probe.all=true \ |
||||
-Dyqn.probe.token=<x-api-key> \ |
||||
-Dyqn.probe.providerWarehouseId=RF_NY_US \ |
||||
-Dtest=YqnFullFlowProbeTest test |
||||
``` |
||||
|
||||
可选参数:`-Dyqn.probe.saleOrderNo` / `-Dyqn.probe.returnOrderNo` / `-Dyqn.probe.newSku`。 |
||||
|
||||
## 11. 未接入 |
||||
|
||||
| 项 | 原因 | |
||||
|---|---| |
||||
| 库存调整 | 运去哪无此接口 | |
||||
| 换货 / 无头件 / BOL | 仓方无对应接口 | |
||||
| 退货查询列表 | 只有按单号查,无列表接口 | |
||||
| 出库列表 / 时间窗查询 | 只有按单号查 | |
||||
Loading…
Reference in new issue