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.

188 lines
8.6 KiB

# 三方仓架构
## 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`(25 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
| `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` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `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` 联系人信息不打印 |