docs: 新增三方仓 SDK 操作手册
按「1. SDK 怎么创建、2. 入参怎么传出参怎么取、3. 各能力怎么调用」三段组织:
一、创建
- 依赖坐标、JDK 1.8
- 宿主必须实现的 SPI:WarehouseRepository / WarehouseAccount /
IdempotencyStore / CallObserver / TokenStore
- 构建门面(含 4 个仓工厂的构造参数、build 失败条件、单例要求)
- 连接信息与各仓凭据字段
- 取仓视图、查能力位
二、入参/出参
- 通用约定:cm/g/Instant/Money,以及 SKU 口径(建档下发的那串)
- Page<T> 翻页模板(游标已屏蔽各仓页码起点差异)
- OutboundCommand / OutboundLine / ShipTo 逐字段说明 + 必填/选填
- InventoryQuery / InboundCommand / ReturnCommand / ReturnQuery /
FeeQuery / FeeEstimateQuery / WarehouseProduct / ProductQuery
- 出参速查表(18 个模型的关键 getter)
三、能力调用
- 视图结构 + 23 行能力矩阵(四个仓逐项打勾)
- 商品 / 出库 / 库存 / 入库 / 退货 / 费用 / 基础资料 / 单据打印 /
调拨销毁异动 的调用示例
四、异常层级(ChannelException -> WarehouseException)、取值、重试判定、幂等键表
五、常见坑速查(SKU 口径、易达云反向布尔、地址州名、面单 URL、-1 语义等)
写的过程中核对并修正了几处:
- OutboundQuery.status 收的是仓侧原始字符串,不是统一枚举
- 能力矩阵按各适配器 EnumSet.of 实际声明提取,不是按接口实现推断
- 补上此前漏掉的 recommend / classifyAddress
- 箱唛两接口语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标)
Co-Authored-By: Claude <noreply@anthropic.com>
|