|
|
|
|
# 三方仓架构
|
|
|
|
|
|
|
|
|
|
## 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. 能力矩阵
|
|
|
|
|
|
|
|
|
|
**查询排序**:`OutboundQuery.sortField()` / `sortDirection()` 是<b>可选项</b>,
|
|
|
|
|
调用方指定优先,未指定由适配器用自己的默认值。`sortField` 是仓方字段名(core 不做白名单),
|
|
|
|
|
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
|
|
|
|
|
调用方不应假定排序一定生效。
|
|
|
|
|
|
|
|
|
|
`WarehouseCapability`(26 个):
|
|
|
|
|
|
|
|
|
|
| 能力 | 说明 | 运去哪 | 信仓 |
|
|
|
|
|
|---|---|:---:|:---:|
|
|
|
|
|
| `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` | 物流轨迹 | ✅ | — |
|
|
|
|
|
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
|
|
|
|
|
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
|
|
|
|
|
| `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` 联系人信息不打印 |
|