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.

1113 lines
56 KiB

# common-ecommerce
多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。
> 三方仓(warehouse-sdk-*)的架构、回调、运去哪接入汇总见 [docs-warehouse/](docs-warehouse/)。
## 定位
纯 SDK 库,嵌入宿主(OMS)进程运行。**不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器**。所有外部副作用通过 SPI 注入,由宿主实现。
```
① 统一入口 ChannelSdk / 各能力视图(SalesOrders / Products / Outbounds / AfterSales / Settlements)
② 能力接口 ProductCapable / SalesOrderCapable / ShippingLabelCapable / AfterSaleCapable / ...
③ 平台适配 lingxing(聚合:amazon-sc / walmart / tiktok / temu / ebay / shein / target …)
④ 基础设施 HttpTransport / TokenManager / LingxingRateLimiter / SyncEngine / Idempotency
⑤ 宿主 SPI AccountRepository / TokenStore / SyncCursorStore / Sink / Clock / LockProvider / ...
```
## 架构图
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
**分层与依赖**:业务只依赖两个门面(`ChannelSdk` / `WarehouseSdk`)与各自的模型;
平台与仓方协议全部关在适配器里;`sdk-common` 被所有模块共享,但不反向依赖任何领域模块。
```mermaid
graph TD
subgraph HOST["宿主进程(OMS)"]
BIZ["业务代码"]
IMPL["宿主 SPI 实现<br/>MySQL · Redis/Redisson · KMS"]
end
subgraph SDK["common-ecommerce"]
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
FACADE["channel-sdk-core · 渠道门面<br/>ChannelSdk · SalesOrders / Products / AfterSales …"]
CAP["channel-sdk-core · 渠道能力接口<br/>PlatformAdapter · SalesOrderCapable · ProductCapable …"]
CMODEL["channel-sdk-core · 渠道模型<br/>SalesOrder · ProductListing · AccountKey"]
ENGINE["channel-sdk-core · 同步管道<br/>SyncEngine"]
WFACADE["warehouse-sdk-core · 仓库门面<br/>WarehouseSdk · outbound / inventory / inbound / returns"]
WCAP["warehouse-sdk-core · 仓库能力接口<br/>WarehouseAdapter · OutboundCapable · InventoryCapable …"]
WMODEL["warehouse-sdk-core · 仓库模型<br/>OutboundOrder · WarehouseReturn · InventorySnapshot"]
SHARED["sdk-common · 跨域共享层<br/>异常 · 幂等 · 审计 · SPI · HTTP 传输 · Money/Page"]
LX["lingxing · 领星聚合适配器"]
YQN["warehouse-sdk-yqn · 运去哪适配器"]
XC["warehouse-sdk-xincang · 信仓适配器"]
end
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
EXT["领星开放平台 / 电商平台 / 三方仓"]
BIZ --> FACADE
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
BIZ --> WFACADE
FACADE --> CAP
FACADE --> CMODEL
FACADE --> ENGINE
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
WFACADE --> WCAP
WFACADE --> WMODEL
CAP --> CMODEL
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
FACADE --> SHARED
WFACADE --> SHARED
ENGINE --> SHARED
LX -. 实现能力接口 .-> CAP
LX --> CMODEL
LX --> SHARED
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
YQN -. 实现能力接口 .-> WCAP
YQN --> WMODEL
YQN --> SHARED
XC -. 实现能力接口 .-> WCAP
XC --> WMODEL
XC --> SHARED
IMPL -. 实现 SPI .-> SHARED
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
YQN --> EXT
XC --> EXT
```
**模块依赖**(与各模块 `pom.xml` 一致,箭头指向被依赖方):
```mermaid
graph BT
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
common["sdk-common"]
chcore["channel-sdk-core"]
whcore["warehouse-sdk-core"]
chkit["sdk-testkit"]
whkit["warehouse-sdk-testkit"]
lingxing["lingxing"]
yqn["warehouse-sdk-yqn"]
xc["warehouse-sdk-xincang"]
hj["warehouse-sdk-hengjian"]
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
chcore --> common
whcore --> common
chkit --> common
chkit --> chcore
whkit --> common
whkit --> whcore
whkit --> chkit
lingxing --> common
lingxing --> chcore
yqn --> common
yqn --> whcore
xc --> common
xc --> whcore
hj --> common
hj --> whcore
```
**一次商品查询的调用链**(订单、售后、出库等能力走同一条骨架):
```mermaid
sequenceDiagram
participant Host as 宿主业务
participant SDK as ChannelSdk
participant Repo as ChannelAccountRepository
participant Ad as LingxingAdapter
participant Sub as 子平台 Source
participant Call as LingxingCall
participant HTTP as HttpTransport
Host->>SDK: products(key, connection).pull(query)
SDK->>Repo: findByKey(AccountKey)
Repo-->>SDK: ChannelAccount
SDK->>SDK: 能力检查 supports(account, PRODUCT)
SDK->>Ad: newContext(account, connection)
Ad->>Ad: tokenManager 取 token(缓存 / 续期 / 防击穿)
Ad->>Sub: 按 account.platform 分派 Source
Sub->>Call: signed(api, body, operation)
Call->>Call: 限流 + 签名 + 公共参数
Call->>HTTP: POST
HTTP-->>Call: 原始响应
Call-->>Sub: 校验信封 code / msg
Sub-->>Ad: 统一模型 Page<ProductListing>
Ad-->>SDK: Page
SDK-->>Host: Page
```
## 模块
| 模块 | 职责 |
|:---|:---|
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
| `sdk-common` | **跨域共享层**:异常体系、SPI 契约、幂等、审计、水位线、通用值对象,以及 HTTP 传输 / 签名 / 令牌管理 / JSON 编解码。不依赖任何领域模块 |
| `channel-sdk-core` | 渠道域:领域模型、能力接口、`ChannelSdk` 门面、同步管道。依赖 `sdk-common` |
| `warehouse-sdk-core` | 仓库域(3PL):仓库模型、能力接口、`WarehouseSdk` 门面、仓域 SPI。依赖 `sdk-common`,**不依赖 `channel-sdk-core`** |
| `sdk-testkit` | 渠道域测试替身:InMemory SPI、FakeDirectAdapter |
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单 / 订单详情与列表) |
依赖方向:
```
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
channel-sdk-core ──┐
sdk-testkit ───────┼──→ sdk-common
warehouse-sdk-core ┘
lingxing ───────────→ channel-sdk-core, sdk-common
warehouse-sdk-yqn ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-xincang ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-hengjian ──→ warehouse-sdk-core, sdk-common
```
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
**渠道域与仓库域平级、互不依赖**,只在 `sdk-common` 上共享 SPI 契约与管道基础设施。
出库回传运单后由 OMS 调渠道域标发,仓库域不调用渠道域。
`http` 已合并进 `sdk-common`(Spec W0 §11)。
**Lombok 使用范围**:仅 `lingxing` 模块的 `dto/*`,`scope=provided`,不进宿主运行时。
`channel` 的领域模型是**不可变 + Builder**,不使用 Lombok——省下的行数有限,
而 `channel` 要尽量少依赖编译期工具。
## 构建
```bash
mvn clean test
```
要求 JDK 1.8、Maven 3.6+。
> 第一次接触这个库,先读 [`GUIDE.md`](GUIDE.md):分层心智模型、三条流水线逐段讲、
> 接入一个新平台的 8 个步骤与 5 层测试。本文档是速查,GUIDE 是教程。
---
## 一、包结构
按当前代码实际目录生成(`src/main/java`,测试包与主代码同构)。模块名在注释里标出。
```
common.ecommerce
│
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
├── shared 跨域共享层(sdk-common)
│ ├── model Platform / ChannelProvider / Capability / FulfillmentMode
│ ├── error ChannelException + Auth / RateLimit / Transient / Validation /
│ │ PlatformBusiness / IdempotencyConflict / CrossProviderConflict
│ ├── spi AccessToken / ChannelSecret / TokenStore / LockProvider /
│ │ IdempotencyStore(+Claim/Record/Status) / SyncCursorStore /
│ │ SecretProvider(已废弃)
│ ├── idempotency IdempotencyGuard / WriteScope / WriteResult / WriteAudit
│ ├── audit CallObserver / CallRecord / CallOutcome / CallSupport /
│ │ ResultSummary / Slf4jCallObserver
│ ├── sync SyncSpec / SyncResult
│ ├── support Money / PlatformTime / Page / CanonicalKeys
│ └── testkit 测试替身(testkit 模块):
│ FakeDirectAdapter / InMemory*(Accounts·Token·Cursor·Sink·
│ Lock·Idempotency) / RecordingTransport / Responses /
│ JsonFixture / MutableClock / TestData
│
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
├── channel 渠道域(channel-sdk-core)
│ ├── model
│ │ ├── account AccountKey / ChannelAccount
│ │ ├── order SalesOrder / OrderLine / SalesOrderQuery / SalesOrderRef
│ │ ├── product ProductListing / ProductQuery / ProductRef /
│ │ │ ProductSearchField / ProductStatus / ProductSyncStrategy
│ │ ├── fulfillment DeclaredItem / LabelQuery / OrderEditRequest / OrderEditResult /
│ │ │ OutboundOrder / OutboundOrderLine / OutboundOrderQuery /
│ │ │ OutboundPackage / OutboundResult / ShipmentReviewResult /
│ │ │ ShippingLabel
│ │ ├── aftersale AfterSale / AfterSaleQuery / AfterSaleType
│ │ └── settlement SettlementQuery / SettlementTransaction
│ ├── capability PlatformAdapter / AggregatorCapable / CapabilityReport /
│ │ AdapterCapabilityReport /
│ │ SalesOrderCapable / ProductCapable / SettlementCapable /
│ │ AfterSaleCapable / OutboundCapable / OutboundOrderCapable /
│ │ ShippingLabelCapable / ShipmentReviewCapable / OrderEditCapable /
│ │ 门面视图:SalesOrders / Products / Settlements / AfterSales / Outbounds
│ ├── sdk ChannelSdk / ChannelContext / ChannelConnection /
│ │ AdapterFactory / ProviderResolver / CallSupport
│ ├── spi ChannelAccountRepository / Sink
│ └── sync SyncEngine
│
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
├── http HTTP 与令牌(sdk-common)
│ HttpTransport / OkHttpTransport / HttpRequest / HttpResponse /
│ JsonCodec / JacksonJsonCodec / TokenManager / Responses
│
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
├── lingxing 领星聚合适配器(lingxing)
├── LingxingApi 接口定义(路径 + 限流参数)
├── LingxingConstants 端点、分页/时间窗限制、platform_code → Platform
├── adapter LingxingAdapter / LingxingAdapterFactory
├── auth LingxingTokenClient
├── http LingxingSigner / LingxingRequestFactory / LingxingRateLimiter /
│ LingxingEnvelope
├── mapper LingxingOrderMapper
├── dto 订单报文:LingxingOrderDto / OrderItem / OrderTag / LogisticsInfo /
│ PlatformInfo / SubProduct / TransactionInfo
└── platform
├── LingxingSubPlatform / LingxingSubPlatforms / LingxingSubPlatformDefaults
├── LingxingCall 每次调用的公共设施(token/限流/签名/信封)
├── Lingxing{Order,Product,Shop,Settlement,AfterSale,Outbound}Source
├── Lingxing{OutboundOrder,Label,ShipmentReview,OrderEdit}Source ERP 级,全平台共用
│
├── multiplatform/ 多平台统一接口(大多数子平台共用)
│ ├── order MultiPlatformOrderSource / LingxingOrderFilters
│ ├── product LingxingProductSearchMapper / LingxingProductSearchBody
│ ├── shop MultiPlatformShopSource
│ ├── outbound MultiPlatformOutboundSource / OutboundOkDto / OutboundFailDto
│ └── dto MultiPlatformShopDto
│
├── amazon/
│ ├── dto FbmOrderDto / FbmOrderItemDto
│ ├── order AmazonOrderSource / AmazonFbmOrderSource
│ ├── sc/ AmazonScSubPlatform
│ │ ├── product AmazonScProductSource
│ │ ├── shop AmazonScShopSource
│ │ └── dto AmazonOrder(Dto|Item|DetailDto|DetailItemDto) /
│ │ AmazonScListingDto / AmazonScShopDto /
│ │ AmazonSettlementTransactionDto / FbmOrderDetailDto
│ ├── vc/ AmazonVcSubPlatform
│ │ ├── order VcOrderSource
│ │ ├── product AmazonVcProductSource
│ │ ├── shop VcShopSource
│ │ └── dto VcOrderDto / VcOrderItemDto / VcOrderDfDetailDto /
│ │ VcOrderPoDetailDto / VcOrderDetailItemDto /
│ │ AmazonVcListingDto / VcShopDto
│ └── settlement AmazonSettlementSource
│
├── wms/ ERP 级实现(不区分平台)
│ ├── WmsOutboundOrderSource / WmsLabelSource /
│ │ ShipmentReviewSource / OrderEditSource
│ └── dto WmsOutboundOrder(Dto|ItemDto) / WmsLogisticsLabelDto /
│ WmsSurfaceFileDto / ShipmentReview(Data|Success|Failure)Dto /
│ OrderEditErrorDto
│
├── aftersale/ LingxingAfterSaleListSource / LingxingAfterSaleMapper
│ └── dto AfterSaleDto / AfterSaleItemDto / AmountDetailDto
│
├── aliexpress/ AliexpressSubPlatform
│ ├── product AliexpressProductSource
│ └── dto AliexpressListingDto / Warehouse / SupplyPrice
├── ebay/ EbaySubPlatform
│ ├── product EbayProductSource
│ └── dto EbayListingDto / EbayAutoRestockDto
├── shein/ SheinSubPlatform
│ ├── product SheinProductSource
│ └── dto SheinListingDto / Site / Warehouse / SupplyPrice
├── target/ TargetSubPlatform
│ ├── product TargetProductSource
│ └── dto TargetListingDto / TargetLocationDto
├── temu/ TemuSubPlatform
│ ├── product TemuProductSource
│ └── dto TemuListingDto / Warehouse / SupplyPrice / PromotionalPrice
├── tiktok/ TiktokSubPlatform
│ ├── product TiktokProductSource
│ └── dto TiktokListingDto / TiktokWarehouseDto
├── walmart/ WalmartSubPlatform
│ ├── order WalmartOrderSource
│ ├── product WalmartProductSource
│ └── dto WalmartListingDto
│
└── 仅订单 + 店铺(多平台通用接口):
aeph/ · bestbuy/ · custom/ · echo/ · losdlius/ · michaels/ · mirakl/ · wayfair/
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│
├── warehouse 仓库域(warehouse-sdk-core)
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ ├── enums (底层枚举,带 SDK 自编 code + 中文名)
│ │ WarehouseProvider / WarehouseCapability / OutboundStatus /
│ │ InboundStatus / TransferStatus / TransferType / LabelMode /
│ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType /
│ │ ReturnDealMethod / ReturnProcessDisposition / ReturnStatus / AttachmentType / WarehouseEventType /
│ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine /
│ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec /
│ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult /
│ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine /
│ │ InboundCommand / InboundLine / InboundCarton / InboundBatch /
feat(yqn): 批量补齐「仓方有、模型没有」的字段 按「仓方给了就加,并标注来源字段」补齐四类: 1. 创建入库计划(API 97)请求侧 11 个字段,之前完全没下发: lineCode / shipmentId / referenceId / attachInfoItems / transportType / deliveryType / goodsSize / tmsNos / carrier / socFlag / palletFlag。 其中 attachInfoItems 意味着之前入库单无法随单传附件(面单/装箱单/BOL)。 tmsNos 运去哪是逗号分割的字符串,出参用 List 承接。 2. 查询入库计划(API 101)响应侧 10 个字段: lineName / shipmentId / referenceId / shipmentNo / goodsType / actualShipDate / cartonTotalWeight / cartonTotalVolume / 四种柜型数量与柜号。 柜型新增 InboundOrder.ContainerInfo(GP20/GP40/HQ40/HQ45 + 数量 + 柜号 + 仓方原值),只对给了值的柜型产对象。 3. 商品(API 115)11 个字段: expirationControl / expirationDate / packedQty / packedLength/Width/Height/ Weight / isInsuranceFlag / isInsuranceRate / snMgmtMode / lotControl。 顺带修海关币种:之前把申报额无脑贴成 USD,非美元会被静默算错; 现在非 USD 直接拒绝,由调用方换算。 4. 物流轨迹(API 189): parcel 实重实尺(oz/inch 统一换算成 g/cm 后落模型,宿主不用各仓换算) + carrierDetail 的承诺送达日期 / 始发地 / 目的地。 另把 WarehouseReturn.Attachment 合并为通用 WarehouseAttachment, 与出库/入库附件统一。 新增 YqnExtraFieldsTest(9 个)。全量 486 个测试通过。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ │ InboundReceipt / InboundOrderBatch / InboundOrderBox / WarehouseAttachment / SerialNumber /
│ │ ReturnCommand / ReturnProcessCommand /
│ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/
│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult /
feat(warehouse): 回调链路 —— 按 provider 的 SDK 入口 + HMAC 验签 + 统一出参 回调是仓方主动推送,SDK 不监听端口:OMS 暴露 HTTP(如 /user/callback/yqn), 取到 headers 与原始 body 后交给 SDK,SDK 只做「验签 + 解析」。 三处新增: 1. 入口 WarehouseSdk.webhook(provider, secret, headers, rawBody, nowMillis) 原来只能 warehouses(warehouseCode, conn).parseWebhook(...),但回调进来时 只有 provider、没有 warehouseCode。新入口按 provider 分派,不查账户。 2. 出参 WarehouseCallback 原 WarehouseEvent 只有 5 个字段,装不下退货的明细行 id / 处理方式, 也装不下入库实收量。改为「公共头 + 按业务分型载荷」:outbound / returns / inbound 三个可空字段,按 eventType 取用;rawBody 原样保留供回溯。 提供指纹方法供宿主去重(报文无事件 id 时使用)。 3. 验签能力 WebhookSignatures HMAC-SHA256 + Base64、恒定时间比较(避免时间差泄漏签名前缀)、 时间戳窗口校验、大小写不敏感的取头。 运去哪面单回调(API 149)实现: signature = Base64(HmacSHA256(appSecret, appKey|timestamp|rawBody)) 头:X-AppKey / X-Timestamp / X-Signature 时间戳单位文档未写明,按位数兼容秒与毫秒(<=10 位按秒),联调后收紧。 新增 YqnLabelCallbackParserTest(10 个):验签通过 / 篡改 body / 错误密钥 / 缺头 / 时间窗过期 / 头名大小写 / X-AppKey 回退 / 载荷解析 / 指纹 / 时间戳单位。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ │ TrackEvent / TrackingInfo / WarehouseCallback / DestructionCommand / DestructionOrder /
│ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel /
│ │ LogisticsProduct / WarehouseInfo
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ ├── capability OutboundCapable / InventoryCapable / InboundCapable /
│ │ WarehouseReturnCapable / WarehouseFeeCapable /
│ │ WarehouseFeeEstimateCapable / TransferCapable /
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable /
│ │ WarehouseProduct / WarehouseProductCapable / LogisticsProductCapable /
│ │ WarehouseDirectoryCapable
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired /
│ │ DuplicateOrder / WebhookVerification
│ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore /
│ │ UnmatchedCallbackStore
│ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds /
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext /
feat(warehouse): 回调链路 —— 按 provider 的 SDK 入口 + HMAC 验签 + 统一出参 回调是仓方主动推送,SDK 不监听端口:OMS 暴露 HTTP(如 /user/callback/yqn), 取到 headers 与原始 body 后交给 SDK,SDK 只做「验签 + 解析」。 三处新增: 1. 入口 WarehouseSdk.webhook(provider, secret, headers, rawBody, nowMillis) 原来只能 warehouses(warehouseCode, conn).parseWebhook(...),但回调进来时 只有 provider、没有 warehouseCode。新入口按 provider 分派,不查账户。 2. 出参 WarehouseCallback 原 WarehouseEvent 只有 5 个字段,装不下退货的明细行 id / 处理方式, 也装不下入库实收量。改为「公共头 + 按业务分型载荷」:outbound / returns / inbound 三个可空字段,按 eventType 取用;rawBody 原样保留供回溯。 提供指纹方法供宿主去重(报文无事件 id 时使用)。 3. 验签能力 WebhookSignatures HMAC-SHA256 + Base64、恒定时间比较(避免时间差泄漏签名前缀)、 时间戳窗口校验、大小写不敏感的取头。 运去哪面单回调(API 149)实现: signature = Base64(HmacSHA256(appSecret, appKey|timestamp|rawBody)) 头:X-AppKey / X-Timestamp / X-Signature 时间戳单位文档未写明,按位数兼容秒与毫秒(<=10 位按秒),联调后收紧。 新增 YqnLabelCallbackParserTest(10 个):验签通过 / 篡改 body / 错误密钥 / 缺头 / 时间窗过期 / 头名大小写 / X-AppKey 回退 / 载荷解析 / 指纹 / 时间戳单位。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ WarehouseConnection(主基址 + 可选辅助基址)/ WarehouseWriteScope /
│ WebhookSignatures(HMAC / 恒定时间比较 / 时间窗)
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
│
├── yqn 运去哪三方仓(warehouse-sdk-yqn)
feat(yqn): 补齐另外三个回调:单据变动 / 退货入库完成 / 库存变动 四个回调共用同一套验签(appKey|timestamp|rawBody 的 HMAC-SHA256), 但报文结构不同。运去哪不按路径区分回调,因此在适配器里按报文特征分派: 含 processMode → 退货入库完成(142);含 opType → 库存变动(150); 含 orderNoType → 业务单据变动(154);否则按面单购买成功(149)。 出参改造: - 新增 WarehouseEventType 底层枚举(LABEL_PURCHASED / ORDER_STATUS_CHANGED / RETURN_INBOUND_COMPLETED / INVENTORY_CHANGED / UNKNOWN),调用方按它分派; eventType 从 String 改为枚举,仓方原值另存 rawEventType - 新增 InventoryPayload:库存推送是增量流水,quantity 恒为正、方向由 inbound 布尔表达,避免调用方按符号猜测;providerOperationType 保留仓方 单据类型码(100 销售出库等) 两处容易出错的地方已在实现里注明: - API 154 的 orderNoStatus 含义随 orderNoType 变化(入库计划 / 调拨 / 销售出库 / 退货认领四套码表),所以 rawEventType 里带上类型,不单独解释状态 - API 142 的 processMode 与 API 81 的预约处理方式码值集合不同,映射到 ReturnProcessDisposition 时只用 142 的码表(2 销毁 / 3 不良品上架 / 4 换标上架 / 5 良品上架);3 与 5 都归 RESTOCK,因为底层枚举没有区分良品与否 API 142 的回调里 items 没有明细行 id,所以 lineId 仍为 null——API 77 (退货条目处理)的操作键依然拿不到,这条链路还没闭环。 新增 YqnCallbackParsersTest(9 个)。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ ├── webhook 回调验签与解析:YqnLabelCallbackParser(API 149)/
│ │ YqnOrderCallbackParser(API 154 + 142)/ YqnInventoryCallbackParser(API 150)
│ ├── dto (按接口拆分,一个接口一个文件)
│ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos /
│ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos /
│ │ YqnCreateInboundDtos / YqnInboundPlanDtos / YqnTransferDtos /
│ │ YqnCreateSaleReturnDtos / YqnSaleReturnPlanDtos / YqnReturnProcessDtos /
│ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos /
│ │ YqnBoxLabelDtos / YqnSkuLabelDtos /
feat(warehouse): 回调链路 —— 按 provider 的 SDK 入口 + HMAC 验签 + 统一出参 回调是仓方主动推送,SDK 不监听端口:OMS 暴露 HTTP(如 /user/callback/yqn), 取到 headers 与原始 body 后交给 SDK,SDK 只做「验签 + 解析」。 三处新增: 1. 入口 WarehouseSdk.webhook(provider, secret, headers, rawBody, nowMillis) 原来只能 warehouses(warehouseCode, conn).parseWebhook(...),但回调进来时 只有 provider、没有 warehouseCode。新入口按 provider 分派,不查账户。 2. 出参 WarehouseCallback 原 WarehouseEvent 只有 5 个字段,装不下退货的明细行 id / 处理方式, 也装不下入库实收量。改为「公共头 + 按业务分型载荷」:outbound / returns / inbound 三个可空字段,按 eventType 取用;rawBody 原样保留供回溯。 提供指纹方法供宿主去重(报文无事件 id 时使用)。 3. 验签能力 WebhookSignatures HMAC-SHA256 + Base64、恒定时间比较(避免时间差泄漏签名前缀)、 时间戳窗口校验、大小写不敏感的取头。 运去哪面单回调(API 149)实现: signature = Base64(HmacSHA256(appSecret, appKey|timestamp|rawBody)) 头:X-AppKey / X-Timestamp / X-Signature 时间戳单位文档未写明,按位数兼容秒与毫秒(<=10 位按秒),联调后收紧。 新增 YqnLabelCallbackParserTest(10 个):验签通过 / 篡改 body / 错误密钥 / 缺头 / 时间窗过期 / 头名大小写 / X-AppKey 回退 / 载荷解析 / 指纹 / 时间戳单位。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ │ YqnLogisticsProductDtos / YqnWarehouseDtos /
feat(yqn): 补齐另外三个回调:单据变动 / 退货入库完成 / 库存变动 四个回调共用同一套验签(appKey|timestamp|rawBody 的 HMAC-SHA256), 但报文结构不同。运去哪不按路径区分回调,因此在适配器里按报文特征分派: 含 processMode → 退货入库完成(142);含 opType → 库存变动(150); 含 orderNoType → 业务单据变动(154);否则按面单购买成功(149)。 出参改造: - 新增 WarehouseEventType 底层枚举(LABEL_PURCHASED / ORDER_STATUS_CHANGED / RETURN_INBOUND_COMPLETED / INVENTORY_CHANGED / UNKNOWN),调用方按它分派; eventType 从 String 改为枚举,仓方原值另存 rawEventType - 新增 InventoryPayload:库存推送是增量流水,quantity 恒为正、方向由 inbound 布尔表达,避免调用方按符号猜测;providerOperationType 保留仓方 单据类型码(100 销售出库等) 两处容易出错的地方已在实现里注明: - API 154 的 orderNoStatus 含义随 orderNoType 变化(入库计划 / 调拨 / 销售出库 / 退货认领四套码表),所以 rawEventType 里带上类型,不单独解释状态 - API 142 的 processMode 与 API 81 的预约处理方式码值集合不同,映射到 ReturnProcessDisposition 时只用 142 的码表(2 销毁 / 3 不良品上架 / 4 换标上架 / 5 良品上架);3 与 5 都归 RESTOCK,因为底层枚举没有区分良品与否 API 142 的回调里 items 没有明细行 id,所以 lineId 仍为 null——API 77 (退货条目处理)的操作键依然拿不到,这条链路还没闭环。 新增 YqnCallbackParsersTest(9 个)。 Co-Authored-By: Claude <noreply@anthropic.com>
1 week ago
│ │ YqnLabelCallbackDtos / YqnOrderStatusCallbackDtos /
│ │ YqnReturnInboundCallbackDtos / YqnInventoryCallbackDtos
│ ├── YqnConstants 端点、路径、固定 token 请求头名、限流
│ ├── adapter YqnAdapter(P1 出库) / YqnAdapterFactory / YqnOutboundMapper
│ ├── dto YqnDtos(字段级契约待打样核对)
│ └── http YqnRequestFactory / YqnEnvelope / YqnRateLimiter
│
└── xincang 信仓三方仓(warehouse-sdk-xincang)
├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh)
├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper /
│ XincangOrderMapper / XincangOrderDetailMapper /
│ XincangTransferMapper / XincangTransferDetailMapper /
│ XincangChannelRecommendMapper / XincangInventoryMapper /
│ XincangForecastMapper
├── dto 一个接口一个文件:XincangLoginDtos / XincangProductSaveDtos /
│ XincangProductListDtos / XincangOrderCreateDtos /
│ XincangOrderDetailDtos / XincangUploadDtos /
│ XincangTransferCreateDtos / XincangTransferDetailDtos /
│ XincangChannelRecommendDtos / XincangStockListDtos /
│ XincangStockAgeListDtos / XincangForecastCreateDtos /
│ XincangForecastImproveDtos / XincangForecastDetailDtos /
│ XincangWarehouseDtos / XincangLogisticsDtos
├── enums XincangOrderStatus / XincangTransferState /
│ XincangForecastStatus / XincangOrderType
└── http XincangRequestFactory / XincangMultipart / XincangEnvelope / XincangRateLimiter
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单 / 详情 / 列表 / 包裹)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper / HengjianOrderMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
└── webhook (package-info:文档无回调页,未实现)
```
包名统一前缀 `common.ecommerce.`,下表省略前缀。
### `shared` —— 跨域共享层
| 子包 | 内容 |
|:---|:---|
| `shared.model` | **枚举**:`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` |
| `shared.error` | 异常体系(见下方「`shared.error`」) |
| `shared.spi` | 宿主扩展点与载体:`AccessToken` / `ChannelSecret` / `TokenStore` / `LockProvider` / `IdempotencyStore` / `SyncCursorStore` |
| `shared.idempotency` | `WriteScope` / `WriteResult` / `WriteAudit` / `IdempotencyGuard` |
| `shared.audit` | `CallObserver` / `CallRecord` / `CallOutcome` |
| `shared.sync` | `SyncSpec` / `SyncResult` |
| `shared.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` |
### `channel.model` —— 领域模型
所有对象**不可变**,用 Builder 构造,无 setter。Java 8 不引入 record/sealed。
子包分工:
| 子包 | 内容 |
|:---|:---|
| `channel.model.account` | `AccountKey` / `ChannelAccount` |
| `channel.model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` |
| `channel.model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSearchField` / `ProductStatus` / `ProductSyncStrategy` |
| `channel.model.fulfillment` | `OutboundOrder` / `OutboundOrderLine` / `OutboundOrderQuery` / `OutboundPackage` / `OutboundResult` / `ShippingLabel` / `LabelQuery` / `OrderEditRequest` / `OrderEditResult` / `ShipmentReviewResult` / `DeclaredItem` |
| `channel.model.aftersale` | `AfterSale` / `AfterSaleQuery` / `AfterSaleType` |
| `channel.model.settlement` | `SettlementQuery` / `SettlementTransaction` |
| 类 | 包袱 | 职责 |
|:---|:---|:---|
| `Platform` | 枚举(shared) | 业务平台。**不含 provider**,直连与聚合器映射到同一值 |
| `ChannelProvider` | 枚举(shared) | 接入通道:DIRECT / LINGXING / TEAPPLIX / CUSTOM |
| `Capability` | 枚举(shared) | 能力枚举,适配器声明、门面校验 |
| `FulfillmentMode` | 枚举(shared) | A/C/D 三种履约模式(B 平台仓只读,不在枚举内) |
| `ProductSyncStrategy` | 枚举 | 增量 / 全量 diff / 报告(放在 `model.product`) |
| `AccountKey` | 标识 | `provider + platform + omsStoreId`,所有调用的隔离维度 |
| `ChannelAccount` | 配置 | 渠道账户配置。只存 `credentialRef`,**不存密钥** |
| `CanonicalKeys` | 工具(shared) | 三级标识与指纹计算,见下方「标识体系」 |
| `PlatformTime` | 值对象(shared) | 三轴时间:UTC 真值 + 市场当地 + 北京时间 |
| `Money` | 值对象(shared) | `BigDecimal + Currency`,跨币种运算直接拒绝 |
| `SalesOrder` / `OrderLine` | 实体 | 3P 销售订单 |
| `ProductListing` | 实体 | 商品 / Listing |
| `SalesOrderQuery` / `ProductQuery` | 查询 | 查询条件(时间窗 + 分页游标) |
| `SalesOrderRef` / `ProductRef` | 引用 | 详情入参。**不能用裸 String**,否则订单+商品接口签名冲突 |
| `Page<T>` | 载体(shared) | 分页载体,`nextCursor == null` 表示结束 |
### `channel.capability` —— 能力接口
适配器实现哪些接口就声明哪些能力;未实现的方法抛 `UnsupportedCapabilityException`,不静默返回空。
| 接口 | 关键方法 |
|:---|:---|
| `PlatformAdapter` | 基座:`adapterId()` / `provider()` / `platforms()` / `capabilities()` / `supports(account, cap)` |
| `AggregatorCapable` | 聚合器扩展:`listSubChannels(account)`,按子平台细化能力 |
| `SalesOrderCapable` | `pull(ctx, query)` / `get(ctx, SalesOrderRef)` |
| `ProductCapable` | `syncStrategy()` / `pull(ctx, query)` / `get(ctx, ProductRef)` |
| `SettlementCapable` / `OutboundCapable` / `OutboundOrderCapable` / `ShippingLabelCapable` / `ShipmentReviewCapable` / `OrderEditCapable` / `AfterSaleCapable` | 账单 / 快速出库 / 出库单 / 面单 / 审核发货 / 订单编辑 / 售后 |
| `CapabilityReport` / `AdapterCapabilityReport` | 能力报告:`supports()` / `supported()` / `unsupported()` |
| `SalesOrders` / `Products` / `Outbounds` / `Settlements` / `AfterSales` | 门面持有的视图,调用前做能力检查 |
### `shared.error` —— 异常体系
全部继承 `ChannelException`,带 `platform / provider / omsStoreId / operation / requestId / platformCode / retryable / rawResponse`。
| 异常 | 触发 | 可否重试 |
|:---|:---|:---:|
| `AuthException` | 401/403、token 失效 | 刷新后 1 次 |
| `RateLimitException` | 429,携带 `retryAfterMillis()` | 是 |
| `TransientException` | 5xx / 网络 / 超时 | 是 |
| `ValidationException` | 4xx 参数或映射错误 | 否 |
| `PlatformBusinessException` | 平台业务错误码 | 视码 |
| `ChannelException.UnsupportedCapabilityException` | 能力缺失 | 否 |
| `IdempotencyConflictException` | 重复写 | 否,返回已完成结果 |
| `CrossProviderConflictException` | 已由另一 provider 完成 | 否,人工确认 |
**注意** `UnsupportedCapabilityException` 是 `ChannelException` 的静态内部类,用 `ChannelException.UnsupportedCapabilityException` 引用。
**详情参数是包装类型**:`SalesOrderCapable.get` 收 `SalesOrderRef`、`ProductCapable.get` 收 `ProductRef`,不是裸 `String`。同一适配器同时实现两种能力时,裸 `String` 会擦除成相同签名而无法同时实现。
**同名类** `Responses` 有两个:`http.Responses`(状态码 → 异常)与 `testkit.Responses`(快捷构造响应)。测试里注意 import 哪个。
### `channel.sdk` —— 门面与上下文
| 类 | 职责 |
|:---|:---|
| `ChannelContext` | 单次调用上下文:`account` + `connection` + `requestId` + `clock`。**由 SDK 创建,适配器不得自造** |
| `AdapterFactory` | 适配器工厂:`adapterId()` / `provider()` / `platforms()` / `create(AdapterConfig)` |
| `ProviderResolver` | 按 `AccountKey` 解析适配器,不自动选路 |
| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders` / `products` / `settlements` / `afterSales` / `outbounds` / `writes()`;`build()` 校验必需项 |
| `ChannelConnection` | 一次调用的连接信息(端点 + 凭据)。**由调用方每次传入,SDK 不保存** |
| `CallSupport` | 门面调用的统一包装:能力检查 + 审计回调 |
### `shared.idempotency` —— 写操作幂等
| 类 | 职责 |
|:---|:---|
| `WriteScope` | 一次写操作的维度:`provider + platform + omsStoreId + externalStoreId + action + businessRef` |
| `WriteResult` | 执行结果:`EXECUTED` / `ALREADY_COMPLETED`(回放,不算失败) |
| `IdempotencyGuard` | 双锁守卫:业务键(跨 provider)+ provider 请求键(单 provider 内重试) |
| `WriteAudit` | 写操作审计留痕 |
### `channel.sync` + `shared.sync` —— 增量同步
| 类 | 职责 |
|:---|:---|
| `SyncSpec`(shared) | 同步维度:`provider + accountKey + stream + overlap` |
| `SyncResult`(shared) | 单次结果:页数、条目数、水位线是否推进 |
| `SyncEngine`(channel) | 分页循环 + 落库 + 水位线推进 |
### `shared.spi` + `channel.spi` —— 宿主扩展点
**SDK 只定义,宿主实现。SDK 内部不碰 JDBC / Redis / MQ。**
| SPI | 作用 | 典型实现 |
|:---|:---|:---|
| `ChannelAccountRepository`(channel) | 读渠道账户 | MySQL |
| `SecretProvider` | **已不再使用**:凭据改由调用方经 `ChannelConnection` 传入 | — |
| `ChannelSecret` | 凭据载体(appKey/appSecret/clientId/… + endpointBaseUrl),`fingerprint()` 供日志 |
| `TokenStore` | access/refresh token 读写 | MySQL / Redis(加密) |
| `AccessToken` | 令牌载体,`needsRefresh(now, earlySec)` 判断提前续期 |
| `SyncCursorStore` | 水位线读写 | MySQL |
| `IdempotencyStore` | 幂等键抢占与结果记录;`claim` 必须原子 | MySQL / Redis |
| `IdempotencyClaim` / `IdempotencyRecord` / `IdempotencyStatus` | 抢占结果、记录、四态(IN_PROGRESS / SUCCEEDED / FAILED_RETRYABLE / FAILED_FINAL) | — |
| `Sink`(channel) | 领域对象落库(当前 `upsertSalesOrders` / `upsertProducts`) | MyBatis |
| `LockProvider` | token 刷新防击穿、账户级互斥 | Redisson / DB |
### `http` —— 出入网层
| 类 | 职责 |
|:---|:---|
| `HttpTransport` | 传输接口,默认 `OkHttpTransport`(连接 5s / 读 30s) |
| `HttpRequest` / `HttpResponse` | 统一请求响应,保留原始 header/body 供留痕 |
| `JsonCodec` | JSON 抽象,`JacksonJsonCodec` 提供点路径取值 `nodeAt("data.list")` |
| `TokenManager` | 令牌模板:账户隔离、提前续期、`LockProvider` 防击穿、日志只打指纹 |
| `Responses` | 状态码 → 异常映射(`throwIfNotSuccess`) |
### `testkit` —— 测试口子
| 类 | 职责 |
|:---|:---|
| `FakeDirectAdapter` | 直连假适配器:游标分页、能力并集即账户能力、记录写调用 |
| `InMemoryAccounts` | 内存版账户仓库 + 密钥提供者 |
| `InMemoryTokenStore` / `InMemoryCursorStore` / `InMemorySink` / `InMemoryLockProvider` / `InMemoryIdempotencyStore` | 全套内存 SPI |
| `MutableClock` | 可推进时钟,验证 TTL / 续期 / 水位线边界 |
| `TestData` | 同步测试的快捷构造 |
### `lingxing` —— 领星适配器
一个聚合器适配器覆盖多个业务平台:`AccountKey.platform` 决定分派到哪个子平台实现,
子平台再按需组合订单 / 商品 / 店铺 / 结算 / 售后 / 出库各路 Source。
```mermaid
graph TD
A["LingxingAdapter<br/>聚合器门面 · 能力按子平台细化"]
R["LingxingSubPlatforms<br/>子平台注册表(按适配器实例)"]
C["LingxingCall<br/>token / 限流 / 签名 / 信封校验"]
subgraph P["子平台(LingxingSubPlatform)"]
ASC["Amazon SC"] --- AVC["Amazon VC"] --- WM["Walmart"] --- TK["TikTok"]
TM["Temu"] --- SH["SHEIN"] --- EB["eBay"] --- AE["AliExpress"]
WF["Wayfair"] --- MK["Mirakl"] --- TG["Target"] --- BB["BestBuy"]
AP["AEPH"] --- MC["Michaels"] --- EC["Echo"] --- LD["Losdlius"] --- CU["Custom"]
end
subgraph S["能力 Source"]
OS["OrderSource / FbmOrderSource"]
PS["ProductSource"]
SS["ShopSource"]
TS["SettlementSource"]
AS["AfterSaleSource"]
OB["OutboundSource"]
end
WMS["ERP 级 Source(全平台共用)<br/>WmsOutboundOrder · WmsLabel · ShipmentReview · OrderEdit"]
A --> R
R --> P
P --> OS
P --> PS
P --> SS
P --> TS
P --> AS
P --> OB
A --> WMS
OS --> C
PS --> C
SS --> C
TS --> C
AS --> C
OB --> C
C --> H["HttpTransport"]
```
| 类 | 职责 |
|:---|:---|
| `LingxingAdapter` | 聚合器适配器:实现订单 / 商品 / 账单 / 出库 / 售后 / 面单 / 审核发货 / 订单编辑等能力,按子平台细化 `supports()` |
| `LingxingSubPlatform` / `LingxingSubPlatforms` / `LingxingSubPlatformDefaults` | 子平台能力分派接口、注册表、默认装配 |
| `LingxingCall` | 一次调用所需的公共设施:取 token、限流、签名、信封校验 |
| `platform/{子平台}/**/` | 各子平台的 Source、DTO、Mapper(如 `aliexpress/product/AliexpressProductSource`) |
| `platform/multiplatform/product/LingxingProductSearchMapper` | 统一搜索维度 `PLATFORM_SKU` / `LOCAL_SKU` → 各子平台 `searchField` 编码 |
| `platform/wms/` | ERP 级、不区分平台的接口:出库单、面单、审核发货、订单编辑 |
| `LingxingConstants` / `LingxingApi` | 端点、限流与分页限制(31 天 / length≤500 等)、`platform_code → Platform` 映射 |
| `LingxingSigner` / `LingxingRequestFactory` | 公共参数 ASCII 升序 + appSecret 前后包裹 + MD5;请求组装 |
| `LingxingRateLimiter` / `LingxingEnvelope` | 按接口令牌桶限流;领星信封 `code/msg/data` 校验 |
| `auth/LingxingTokenClient` | 换取 / 续约 access_token |
| `mapper/LingxingOrderMapper`、`dto/*` | 领星报文 → 统一模型;领星原始报文结构(Lombok) |
| `LingxingAdapterFactory` | 工厂注册 |
---
## 二、标识体系(务必先读)
provider **不得进入业务主键**,否则直连与聚合器切换会把同一订单变成两条。
| 标识 | 组成 | 用途 |
|:---|:---|:---|
| `omsStoreId` | OMS 渠道店铺 ID | 业务归属 |
| `canonicalKey` | `platform + omsStoreId + 平台实体 ID` | upsert、去重、状态流转 |
| `sourceKey` | `provider + platform + externalStoreId + 平台实体 ID` | 原始报文、水位线、审计 |
```java
CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
// → "WALMART_SC:oms-wm-001:PO-123" 直连与领星算出来完全一样
```
写操作要两把锁:
```java
// 业务幂等键:不带 provider,直连/领星共用,同一业务动作只能成功一次
CanonicalKeys.businessIdempotencyKey(Platform.WALMART_SC, "oms-wm-001", "PO-1:pkg-1", "shipping");
// provider 请求键:带 provider,单 provider 内重试去重
CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "wm-seller-01", "shipping", "PO-1:pkg-1");
```
两把锁不要手写串联,用 `IdempotencyGuard` 执行(见 3.5)。
---
## 三、调用方式
### 状态说明
`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders` / `products` / `settlements` /
`afterSales` / `outbounds` / `writes()` 均已挂接,`build()` 做必需项校验(缺 `accountRepository`、
缺适配器都会抛异常)。领星适配器当前声明订单、商品、账单、标发、退货、出库单、面单、审核发货、
订单编辑能力,能力再按子平台细化(见 3.4)。
两条调用路径都可以用:**门面**(3.3)适合业务层;**适配器 + SyncEngine**(3.1 / 3.2)
适合需要自己控制时间窗、翻页与落库的场景。
### 3.1 单次查询(不推进水位线)
适合人工排查、补偿。宿主自己决定拉哪个时间窗。
```java
// 1) 宿主实现 SPI
ChannelAccountRepository accountRepo = ...; // MySQL
TokenStore tokenStore = ...; // 加密存储
LockProvider lockProvider = ...; // Redisson / DB
// 2) 创建适配器(也可经 LingxingAdapterFactory.create)
LingxingAdapter adapter = new LingxingAdapter(
new OkHttpTransport("common-ecommerce/1.0.0 (lingxing)"),
new JacksonJsonCodec(),
tokenStore, lockProvider,
Clock.systemUTC());
// 3) 取账户 + 连接 → 组装调用上下文
ChannelAccount account = accountRepo
.findByKey("LINGXING", "WALMART_SC", "oms-wm-001")
.orElseThrow(() -> new IllegalStateException("account not configured"));
ChannelConnection connection = ChannelConnection.of(ChannelProvider.LINGXING,
LingxingConstants.PRODUCTION_BASE_URL, secret); // 凭据由调用方每次传入
ChannelContext ctx = ChannelContext.of(account, connection, UUID.randomUUID().toString(), Clock.systemUTC());
// 4) 调用
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z")) // 必填,UTC
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z")) // 可选,缺省取 now
.pageSize(100) // 平台上限内自动截断
.build());
for (SalesOrder order : page.items()) {
// order.channelOrderId() 是平台单号,可直接算 canonicalKey
}
```
翻页:拿 `page.nextCursor()` 填回 `query.toBuilder().cursor(...)`(`SalesOrderQuery` 提供 `toBuilder()`),`nextCursor == null` 表示结束。
### 3.2 增量同步(推进水位线)
适配器负责「怎么拉一页」,`SyncEngine` 负责「翻页 + 落库 + 水位线」。整批成功才推进,失败不推进。
```java
// 宿主实现这两个 SPI(测试时用 InMemoryCursorStore / InMemorySink)
SyncCursorStore cursorStore = ...;
Sink sink = ...;
SyncSpec spec = SyncSpec.of(
ChannelProvider.LINGXING,
"oms-wm-001",
SyncSpec.STREAM_SALES_ORDERS,
Duration.ofMinutes(10)); // 重叠窗口,防边界丢单
Instant to = Instant.now();
SyncResult result = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to,
(from, cursor) -> adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(from)
.updatedBefore(to)
.cursor(cursor)
.build()));
result.pages(); // 拉了几页
result.items(); // 落了几个实体
result.watermarkAdvanced(); // true == 水位线已推进到 to
```
要点:
- **起点计算**:`from = lastWatermark - overlap`,由 `SyncSpec.from(watermark)` 完成。
- **必须先有水位线**:`cursorStore.get(...)` 返回 null 时 `SyncEngine` 抛 `IllegalStateException`,提醒先做全量建底(首次全量用创建时间回溯,成功后调 `advance`)。
- **水位线维度**:`provider + accountKey + stream`,直连与领星各存各的,不能复用。
- **调度归宿主**:SDK 不持有线程和定时器,由 OMS 调度器触发 `syncSalesOrders`。
### 3.3 门面调用
```java
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo) // 必需
.clock(Clock.systemUTC()) // 可选,默认 UTC
.idempotencyStore(idempotencyStore) // 写操作用;不注入则 writes() 失败
.register(new LingxingAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
.build(); // 缺必需项立刻抛异常
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
// 能力矩阵只读,不触发真实 API
CapabilityReport caps = sdk.capabilities(key);
if (!caps.supports(Capability.SALES_ORDER)) { ... }
// 路由完全由调用方决定,SDK 不推荐、不自动兜底
Page<SalesOrder> page = sdk.salesOrders(key, connection).pull(query);
```
`build()` 会在以下情况**立即失败**,不返回不可用的空对象:
| 缺失 | 异常信息 |
|:---|:---|
| `accountRepository` | `ChannelSdk requires an accountRepository` |
| 没有任何适配器 / 工厂 | `ChannelSdk requires at least one adapter or adapter factory` |
| 同一 `provider + platform` 注册两次 | `duplicate adapter for ...` |
调用时:
- 账户未配置 → `IllegalStateException: channel account not configured`
- provider 无对应适配器 → `IllegalStateException: no adapter registered for ...`
- 适配器不支持该能力 → `ChannelException.UnsupportedCapabilityException`
测试中可绕过工厂直接注册适配器实例:`.register(adapter)`。
### 3.4 能力检查
聚合器必须按子平台判断,不能只用 `capabilities()`:
```java
// 领星上 eBay 的账户:只有订单,没有账单/售后
AccountKey ebay = AccountKey.of(ChannelProvider.LINGXING, Platform.EBAY, "oms-ebay-001");
adapter.supports(ebayAccount, Capability.BILLING); // false
```
缺失能力时抛 `ChannelException.UnsupportedCapabilityException`,由调用方走 3PL / 人工兜底,**SDK 不会自动换 provider**。
### 3.5 写操作幂等(双锁)
所有写操作(标发、发货确认、退款、退货审批……)都经 `IdempotencyGuard` 执行。
业务键不带 provider,与 provider 请求键一起抢占;重复调用返回已完成结果,不算失败。
```java
WriteScope scope = WriteScope.of(
ChannelProvider.LINGXING, // 本次用哪条接入通道
Platform.WALMART_SC,
"oms-wm-001", // 业务店铺维度
"1108413237731", // 平台/领星店铺 ID,用于 provider 请求键
"markShipped",
"PO-1:pkg-1"); // 业务自然键;退款用 returnId:itemId:refundRequestId,禁止用金额
WriteResult<ShipResult> result = sdk.writes().execute(scope,
() -> adapter.markShipped(ctx, command), // 真正调用平台
ShipResult::shipmentId); // 结果引用,回放时返回
result.outcome(); // EXECUTED / ALREADY_COMPLETED
```
行为:
| 情形 | 结果 |
|:---|:---|
| 首次调用 | 抢两把锁 → 执行 → 两把锁都记 SUCCEEDED |
| 重复调用(同 provider) | `ALREADY_COMPLETED`,不调用平台 |
| 重复调用(另一 provider) | `CrossProviderConflictException`,人工确认 |
| 并发调用 | `IdempotencyConflictException`,拒绝重复执行 |
| 抛 `retryable=true` 的异常 | 两把锁记 `FAILED_RETRYABLE`,可重跑 |
| 抛 `retryable=false` 的异常 | 记 `FAILED_FINAL`,需人工介入 |
| 平台已写、业务键未记成功(崩溃) | provider 键命中,回放结果,不重复写 |
`IdempotencyStore.claim` 必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。
`IdempotencyGuard` 不做退避重试,重试节奏由宿主调度决定。
### 3.6 调用日志(审计)
SDK 是纯库,**不写数据库、不写文件、不起线程**。需要调用日志时,宿主注入一个
`CallObserver`,SDK 在**每次门面调用结束**时回调一次(成功与失败都回调)。
#### 最省事的写法
```java
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo)
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) // ← 关键
.register(new LingxingAdapterFactory(...))
.build();
WarehouseSdk wh = WarehouseSdk.builder()
.warehouseRepository(repo)
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
.register(new YqnWarehouseAdapterFactory())
.build();
```
两个门面的 `callObserver(...)` 用法完全一致,都来自 `common.ecommerce.shared.audit`。
| 项 | 说明 |
|:---|:---|
| 不注入 | 默认 `CallObserver.NOOP`,**不产生任何日志** |
| 时区 | `Slf4jCallObserver()` 用 `ZoneId.systemDefault()`;容器里通常是 **UTC**,建议显式传 |
| 日志实现 | SDK 只依赖 `slf4j-api`,**实现由宿主提供**(logback / log4j2 …) |
> ⚠️ 宿主没有 SLF4J 绑定时,日志会被**静默丢弃**,控制台只会出现
> `SLF4J: Defaulting to no-operation (NOP) logger implementation`。
> 启动时建议打一行 `callObserver=...`,确认已注入。
#### 输出样式
成功打 INFO:
```
sdk-call at=2026-11-11 14:37:09 op=warehouse.outbound.create provider=yqn platform=null
omsStoreId=null storeId=RF_NY_US requestId=abc-123 cost=320ms
result=1 failed=0 code=200 params={outboundRequestNo=OB-1}
```
失败打 WARN:
```
sdk-call-failed at=2026-11-11 14:37:09 op=warehouse.outbound.create provider=yqn ...
requestId=abc-124 cost=210ms result=0 failed=0 code=null
params={outboundRequestNo=OB-2} retryable=false
platformCode=999999 platformRequestId=null
error=PlatformBusinessException: yqn business error: code=999999, message=库存不足
```
| 字段 | 含义 |
|:---|:---|
| `at` | 调用时间(按注入的时区渲染,`CallRecord` 内部恒为 UTC) |
| `op` | 操作名,如 `warehouse.outbound.create` / `channel.salesOrder.pull` |
| `provider` / `platform` / `omsStoreId` / `storeId` | 路由维度 |
| `requestId` | 我方链路 ID,可与业务日志对齐 |
| `cost` | 耗时(ms) |
| `result` / `failed` | 返回条数 / 失败条数(`PARTIAL` 也算 INFO) |
| `code` | 平台业务码 |
| `params` | 入参摘要(**不含密钥、买家姓名、收货地址**) |
| `retryable` / `platformCode` / `platformRequestId` | 仅失败时出现 |
| `error` | 异常类型 + 消息;换行/控制字符会被替换、截断到 512 字符(防 log forging) |
#### 落库 / 发 MQ / 接监控
实现 `CallObserver` 即可:
```java
public final class DbCallObserver implements CallObserver {
private final Executor async;
@Override
public void onCall(CallRecord r) {
// 回调发生在业务线程上,要快;慢操作投递到宿主的异步通道
async.execute(() -> insert(r));
}
}
```
接口约束(`CallObserver` 的 Javadoc 同时写明):
- **不要抛异常**。SDK 会兜底捕获并打 WARN,但吞掉异常会掩盖实现问题;
- 回调发生在**业务线程**上,方法应尽快返回;
- `CallRecord.params()` 只是摘要,不要补写密钥、买家姓名、收货地址等敏感信息。
#### 覆盖范围
全部门面方法都经 `CallSupport.observe`,包括:
- 查询类(出库 / 入库 / 退货 / 库存 / 费用 / 轨迹 / 仓库目录 / 物流产品)
- **写操作**(创建、取消、审核、删除、条目处理)——失败时不记日志最难排查,已全部覆盖
- 回调 `sdk.webhook(...)`(operation 为 `warehouse.webhook.parse`,验签失败也能进日志)
#### 部分成功可以区分
需要区分「全部成功 / 部分成功 / 全部失败」时,用 `CallSupport.observeSummary(...)`
并提供 `ResultMapper` 返回 `ResultSummary`,日志里的 `result=` / `failed=` 会分别体现。
---
## 四、扩展方式
### 4.1 新增一个直连平台
以新增 `amazon-sc` 为例,**不改 channel、不改门面、不改宿主**。
**第 1 步:建模块**,`pom.xml` 只依赖 channel、http 与 shared。
**第 2 步:实现能力接口**。只实现真正支持的,其余不实现:
```java
public final class AmazonScAdapter implements SalesOrderCapable, FulfillmentCapable, LabelCapable {
@Override public String adapterId() { return "amazon-sc"; }
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
@Override public Set<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
// 能力并集必须与实际实现一致
@Override public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT,
Capability.MARK_SHIPPED, Capability.LABEL, Capability.BILLING);
}
@Override public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) { ... }
@Override public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { ... }
}
```
**第 3 步:写签名器**,静态工具类即可(如 `LingxingSigner`)——签名参数往往要在构造 `HttpRequest` 之前算,没有统一接口。LWA 只需 `Authorization: Bearer`,连签名器都不用。
**第 4 步:写报文映射**,平台 JSON → 统一模型。**平台字段名只出现在 DTO 和 Mapper 里**。
**第 5 步:实现 `AdapterFactory`**,与直连/聚合器同一套注册机制:
```java
public final class AmazonScAdapterFactory implements AdapterFactory {
@Override public String adapterId() { return "amazon-sc"; }
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
@Override public EnumSet<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
@Override public PlatformAdapter create(AdapterConfig config) { return new AmazonScAdapter(...); }
}
```
**第 6 步:加契约测试**(见第五节)。
**第 7 步:`ChannelSdk.builder().register(...)`**,完成。
### 4.2 新增一个聚合器
与直连的唯一区别是**实现 `AggregatorCapable`**,按账户的子平台细化能力:
```java
public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorCapable {
@Override
public boolean supports(ChannelAccount account, Capability capability) {
if (!capabilities().contains(capability)) return false;
// 按 account.platformCode() 判断,不能一刀切
return isSupportedBySubPlatform(account.platformCode(), capability);
}
@Override
public List<SubChannel> listSubChannels(ChannelAccount account) { ... }
}
```
**不要**为每个子平台新建模块——子平台是配置(`platformCode + externalStoreId`),不是代码。
### 4.3 新增一个能力(如退款)
1. `Capability` 加枚举值;
2. `capability/` 下加接口(可选动作给 `default` 方法抛 `UnsupportedCapabilityException`,适配器只覆写支持的);
3. 适配器声明能力并实现;
4. 领域模型加实体(`Refund` / `ReturnOrder` …);
5. `Sink` 加对应 `upsert`,testkit 加 `InMemory` 实现。
**不会改动的**:`PlatformAdapter`、`ChannelContext`、`AccountKey`、`CanonicalKeys`、`SyncEngine`、`IdempotencyGuard`。
### 4.4 新增一个 SPI
宿主可能需要新的副作用出口(如 `RefundLedger`、`RawPayloadStore`)。
1. `spi/` 下定义**纯接口**,不引入 JDBC/Redis 类型;
2. 提供 `InMemory` 实现进 testkit,保证适配器可脱离宿主测试;
3. 通过 `ChannelSdk.Builder` 或适配器构造器注入。
**判断标准**:是否需要持久化或跨进程状态?是 → 新 SPI;否 → 放管道层(http)。
### 4.5 扩展红线
| 不做 | 原因 |
|:---|:---|
| `channel` 引 Spring / JDBC / Redis / MQ | SDK 要能脱离宿主单测 |
| 把平台端点、字段名做成配置表 | 协议是代码,配置化会让线上线下跑不同协议 |
| 密钥写入 `ChannelAccount` | 只能存 `credentialRef`,密钥经 `ChannelConnection` 在调用时传入 |
| provider 进 canonicalKey | 直连/聚合器切换会产生重复实体 |
| 在适配器里 `new Thread` / 定时器 | 调度归宿主,SDK 不许私起线程 |
| 能力声明与实际实现不一致 | 验收项,缺失能力必须显式抛异常 |
| 写操作盲目重试 | 必须有幂等键;退款/标发超时先回查 |
---
## 五、测试
### 分层
| 层级 | 测什么 | 依赖 |
|:---|:---|:---|
| 单元测试 | 签名、canonicalKey、时间三轴/DST、错误映射 | 纯计算,毫秒级 |
| **契约测试**(核心) | 请求是否构造对、响应是否解析对 | 录制夹具 |
| 集成测试 | 重试、限流、401 刷新 | 真实环境冒烟(`LingxingLiveSmokeTest`) |
| 沙箱联调 | 端到端 | 手动,不进 CI |
适配器测试**不依赖网络、数据库、Spring**。
### 夹具约定
```
src/test/resources/fixtures/{platform}/{operation}/{case}.json
```
例:`lingxing/src/test/resources/fixtures/lingxing/walmartListing/success.json`
每个平台至少准备「正常 + 异常」两套。
### 写法
```java
// 联调直接用真实接口,见 LingxingLiveSmokeTest;
// 契约测试用 RecordingTransport + 夹具,不联网
LingxingAdapter adapter = new LingxingAdapter(transport,
new JacksonJsonCodec(), tokenStore, locks,
Clock.fixed(Instant.parse("2026-10-29T00:00:00Z"), ZoneOffset.UTC));
ChannelContext ctx = ChannelContext.of(account, connection, "req-1", clock);
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
.build());
// 断言请求构造
HttpRequest last = transport.lastRequest();
assertTrue(last.url().contains("sign="));
assertTrue(last.body().contains("\"platform_code\":10008"));
// 断言解析结果
assertEquals("PO-123456789", page.items().get(0).channelOrderId());
```
完整示例见 `lingxing/src/test/java/.../LingxingSdkListingCallTest.java`。
直连抽象与幂等守卫不用真平台也能测:
```java
// channel 抽象没被聚合器带偏:单平台、能力并集、游标翻页
FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build();
// 双锁幂等:第二次调用回放,平台只真正写一次
MutableClock clock = MutableClock.atUtc("2026-10-29T00:00:00Z");
IdempotencyGuard guard = new IdempotencyGuard(new InMemoryIdempotencyStore(), clock);
guard.execute(scope, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v);
guard.execute(scope, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v);
assertEquals(1, adapter.writeCallCount());
```
### 执行
```bash
mvn test # 全部
mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运
mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 下单 / 订单查询
```
---
## 六、待办与待核对
**待实现**
| 项 | 说明 |
|:---|:---|
| `RawPayloadStore` | 原始报文留痕(脱敏) |
| `RefundLedger` | 已退款金额汇总与超退校验,与 `IdempotencyGuard` 配合 |
| `DuplicateOrderGuard` | 跨 provider 重复订单告警 |
| `SalesOrder` 补 `platform` 字段 | `Sink` 落库时无法得知订单来自哪个平台,只能靠 `omsStoreId` 反查 |
| 适配器层重试 | 401/429/5xx 目前只分类不重试,退避由宿主包一层 |
| 写操作门面视图 | 只有 `sdk.writes()`,写之前需手动 `resolve` + 转型 + 查能力,缺 `sdk.fulfillment(key)` 这类视图 |
| 其余由文档 `Spec 0` 定义的能力 | 履约、面单、账单、售后、Webhook、异步报表 |
**待核对(需官方文档 + 真实沙箱,联调时集中修改)**
| 位置 | 内容 |
|:---|:---|
| `LingxingOrderDto` | 字段名:`platform_order_no` / `platform_order_names` / `purchase_time` / `item_list` |
| `LingxingSigner` | 签名大小写、是否排除空值参数 |
| `LingxingTokenClient` | 令牌接口请求体字段名与响应嵌套层级 |
| `LingxingAdapter.get()` | 单订单详情接口是否存在 |
## 设计文档
- [`GUIDE.md`](GUIDE.md):开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试
- OMS 侧 `cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)