# 三方仓架构 ## 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()` 是可选项, 调用方指定优先,未指定由适配器用自己的默认值。`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` 联系人信息不打印 |