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.

9.0 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() 适配器内部映射

例:

// 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() 是可选项, 调用方指定优先,未指定由适配器用自己的默认值。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. 一次调用的链路

以查订单详情为例:

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