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.
8.9 KiB
8.9 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(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. 一次调用的链路
以查订单详情为例:
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 联系人信息不打印 |