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.

195 lines
9.1 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. 能力矩阵
**查询排序**:`OutboundQuery.sortField()` / `sortDirection()` 是<b>可选项</b>,
调用方指定优先,未指定由适配器用自己的默认值。`sortField` 是仓方字段名(core 不做白名单),
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
`WarehouseCapability`(27 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
| `PRODUCT` | 商品建档 / 更新 | ✅ | ✅ |
| `OUTBOUND` | 出库创建 / 查询 / 取消 | ✅ | ✅ |
| `PLATFORM_LABEL_DELIVERY` | 平台面单下发 | ✅ | — |
| `FEE_SETTLEMENT` | 结算明细 | ✅ | — |
| `FEE_ESTIMATE` | 运费试算 | ✅ | — |
| `INVENTORY_QUERY` | 库存查询 | ✅ | ✅ |
| `INBOUND` | 入库创建 / 查询 | ✅ | — |
| `BOX_LABEL` | 入库箱标(异步) | ✅ | — |
| `SKU_LABEL` | SKU 标(异步) | ✅ | — |
| `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ |
| `DIRECTORY` | 仓库 / 承运商目录 | ✅ | — |
| `WEBHOOK` | 状态回调 | ✅ | — |
| `TRANSFER` | 仓间调拨 | ✅ | ✅ |
| `RETURN` | 退货发起 / 查询 | ✅ | — |
| `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — |
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
feat(hengjian): 对接运费测算与地址属性识别 两个接口都在 /v2/api/shipping 下,真机均确认可用(无 token 时的 参数校验响应与 404 对照组可区分)。 运费测算 /v2/api/shipping/calculate - 真机确认必填项是包裹四项 + 两个单位 + 收货方五项;文档标必填的 shipper* 系列实际可不传 - 单位 cm/g 与统一模型一致,不换算 - 包裹尺寸在恒健是 INTEGER,厘米值四舍五入(截断会让报价偏低) - totalRate 取 conversionTotalRate(折算价 / 客户实付), 不取 originalTotalRate(承运商牌价) - 恒健不按仓返回,统一结果只有一个实例,仓编码用账户仓填充 地址属性 /v2/api/shipping/addressClassification - 新增能力位 ADDRESS_CLASSIFICATION + AddressClassificationCapable + core 枚举 AddressType(BUSINESS/RESIDENTIAL/MIXED/UNKNOWN) - 真机确认 street1/zip/city/state/country 五项必填,本地先挡 - 认不出归 UNKNOWN 不猜;MIXED 在 residential() 里按住宅计 - 文档域名写的是 open-api.thebizark.com(别家),真机确认本仓域名可用 顺带修 core 缺陷:FeeEstimateQuery.logisticsServiceCode 原为构造期必填, 而恒健允许不传(由仓报全部渠道)。改为选填,并新增 hasLogisticsServiceCode(); 运去哪要求必填,改为在它的 mapper 里校验,不影响既有行为。 验证:mvn test 全量通过,恒健 180 个用例(+14)通过。 Co-Authored-By: Claude Code <noreply@anthropic.com>
5 days ago
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
| `CASE_MARK_PRINT` | 箱唛打印(同步 PDF) | — | — |
| `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` 联系人信息不打印 |