diff --git a/README.md b/README.md index 2d32212..4af3732 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ 多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。 +> 三方仓(warehouse-sdk-*)的架构、回调、运去哪接入汇总见 [docs-warehouse/](docs-warehouse/)。 + ## 定位 纯 SDK 库,嵌入宿主(OMS)进程运行。**不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器**。所有外部副作用通过 SPI 注入,由宿主实现。 diff --git a/docs-warehouse/README.md b/docs-warehouse/README.md new file mode 100644 index 0000000..45d2d5f --- /dev/null +++ b/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` diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md new file mode 100644 index 0000000..417af99 --- /dev/null +++ b/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` 联系人信息不打印 | diff --git a/docs-warehouse/callback.md b/docs-warehouse/callback.md new file mode 100644 index 0000000..30b9aab --- /dev/null +++ b/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 + ▼ +┌──────────────────────────────────────┐ +│ 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`。 diff --git a/docs-warehouse/notes.md b/docs-warehouse/notes.md new file mode 100644 index 0000000..4066536 --- /dev/null +++ b/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 +/** + * 单位待核实:文档未标单位,这里按 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` 已覆盖) | diff --git a/docs-warehouse/yqn/README.md b/docs-warehouse/yqn/README.md new file mode 100644 index 0000000..d784d05 --- /dev/null +++ b/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= \ + -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= \ + -Dyqn.probe.providerWarehouseId=RF_NY_US \ + -Dtest=YqnFullFlowProbeTest test +``` + +可选参数:`-Dyqn.probe.saleOrderNo` / `-Dyqn.probe.returnOrderNo` / `-Dyqn.probe.newSku`。 + +## 11. 未接入 + +| 项 | 原因 | +|---|---| +| 库存调整 | 运去哪无此接口 | +| 换货 / 无头件 / BOL | 仓方无对应接口 | +| 退货查询列表 | 只有按单号查,无列表接口 | +| 出库列表 / 时间窗查询 | 只有按单号查 |