Browse Source

docs: 新增 docs-warehouse/ 三方仓文档

四篇:
- 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
chenchuchuan 1 week ago
parent
commit
a4cfd6cbfe
  1. 2
      README.md
  2. 17
      docs-warehouse/README.md
  3. 186
      docs-warehouse/architecture.md
  4. 262
      docs-warehouse/callback.md
  5. 192
      docs-warehouse/notes.md
  6. 238
      docs-warehouse/yqn/README.md

2
README.md

@ -2,6 +2,8 @@
多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。 多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。
> 三方仓(warehouse-sdk-*)的架构、回调、运去哪接入汇总见 [docs-warehouse/](docs-warehouse/)。
## 定位 ## 定位
纯 SDK 库,嵌入宿主(OMS)进程运行。**不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器**。所有外部副作用通过 SPI 注入,由宿主实现。 纯 SDK 库,嵌入宿主(OMS)进程运行。**不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器**。所有外部副作用通过 SPI 注入,由宿主实现。

17
docs-warehouse/README.md

@ -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`

186
docs-warehouse/architecture.md

@ -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` 联系人信息不打印 |

262
docs-warehouse/callback.md

@ -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`。

192
docs-warehouse/notes.md

@ -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` 已覆盖) |

238
docs-warehouse/yqn/README.md

@ -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…
Cancel
Save