|
|
7 hours ago | |
|---|---|---|
| channel-sdk-core | 13 hours ago | |
| docs-warehouse | 2 days ago | |
| lingxing | 14 hours ago | |
| sdk-common | 14 hours ago | |
| sdk-testkit | 13 hours ago | |
| warehouse-sdk-core | 8 hours ago | |
| warehouse-sdk-edayun | 8 hours ago | |
| warehouse-sdk-hengjian | 7 hours ago | |
| warehouse-sdk-testkit | 12 hours ago | |
| warehouse-sdk-xincang | 8 hours ago | |
| warehouse-sdk-yqn | 7 hours ago | |
| .gitattributes | 3 weeks ago | |
| .gitignore | 2 weeks ago | |
| GUIDE.md | 1 week ago | |
| README.md | 2 days ago | |
| pom.xml | 1 week ago | |
| 操作手册.md | 1 week ago | |
README.md
common-ecommerce
多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。
三方仓(warehouse-sdk-*)的架构、回调、运去哪接入汇总见 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 / ...
架构图
分层与依赖:业务只依赖两个门面(ChannelSdk / WarehouseSdk)与各自的模型;
平台与仓方协议全部关在适配器里;sdk-common 被所有模块共享,但不反向依赖任何领域模块。
graph TD
subgraph HOST["宿主进程(OMS)"]
BIZ["业务代码"]
IMPL["宿主 SPI 实现<br/>MySQL · Redis/Redisson · KMS"]
end
subgraph SDK["common-ecommerce"]
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
EXT["领星开放平台 / 电商平台 / 三方仓"]
BIZ --> FACADE
BIZ --> WFACADE
FACADE --> CAP
FACADE --> CMODEL
FACADE --> ENGINE
WFACADE --> WCAP
WFACADE --> WMODEL
CAP --> CMODEL
FACADE --> SHARED
WFACADE --> SHARED
ENGINE --> SHARED
LX -. 实现能力接口 .-> CAP
LX --> CMODEL
LX --> SHARED
YQN -. 实现能力接口 .-> WCAP
YQN --> WMODEL
YQN --> SHARED
XC -. 实现能力接口 .-> WCAP
XC --> WMODEL
XC --> SHARED
IMPL -. 实现 SPI .-> SHARED
YQN --> EXT
XC --> EXT
模块依赖(与各模块 pom.xml 一致,箭头指向被依赖方):
graph BT
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"]
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
一次商品查询的调用链(订单、售后、出库等能力走同一条骨架):
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
模块
| 模块 | 职责 |
|---|---|
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 生成访问器 |
warehouse-sdk-yqn |
运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
warehouse-sdk-xincang |
信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
warehouse-sdk-hengjian |
恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁 / 箱标) |
依赖方向:
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
渠道域与仓库域平级、互不依赖,只在 sdk-common 上共享 SPI 契约与管道基础设施。
出库回传运单后由 OMS 调渠道域标发,仓库域不调用渠道域。
http 已合并进 sdk-common(Spec W0 §11)。
Lombok 使用范围:仅 lingxing 模块的 dto/*,scope=provided,不进宿主运行时。
channel 的领域模型是不可变 + Builder,不使用 Lombok——省下的行数有限,
而 channel 要尽量少依赖编译期工具。
构建
mvn clean test
要求 JDK 1.8、Maven 3.6+。
第一次接触这个库,先读
GUIDE.md:分层心智模型、三条流水线逐段讲、 接入一个新平台的 8 个步骤与 5 层测试。本文档是速查,GUIDE 是教程。
一、包结构
按当前代码实际目录生成(src/main/java,测试包与主代码同构)。模块名在注释里标出。
common.ecommerce
│
├── 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
│
├── 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
│
├── http HTTP 与令牌(sdk-common)
│ HttpTransport / OkHttpTransport / HttpRequest / HttpResponse /
│ JsonCodec / JacksonJsonCodec / TokenManager / Responses
│
├── 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/
│
├── warehouse 仓库域(warehouse-sdk-core)
│ ├── enums (底层枚举,带 SDK 自编 code + 中文名)
│ │ WarehouseProvider / WarehouseCapability / OutboundStatus /
│ │ InboundStatus / TransferStatus / TransferType / LabelMode /
│ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType /
│ │ ReturnDealMethod / ReturnProcessDisposition / ReturnStatus / AttachmentType / WarehouseEventType /
│ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType
│ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine /
│ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec /
│ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult /
│ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine /
│ │ InboundCommand / InboundLine / InboundCarton / InboundBatch /
│ │ InboundReceipt / InboundOrderBatch / InboundOrderBox / WarehouseAttachment / SerialNumber /
│ │ ReturnCommand / ReturnProcessCommand /
│ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/
│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult /
│ │ TrackEvent / TrackingInfo / WarehouseCallback / DestructionCommand / DestructionOrder /
│ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel /
│ │ LogisticsProduct / WarehouseInfo
│ ├── capability OutboundCapable / InventoryCapable / InboundCapable /
│ │ WarehouseReturnCapable / WarehouseFeeCapable /
│ │ WarehouseFeeEstimateCapable / TransferCapable /
│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable /
│ │ WarehouseProduct / WarehouseProductCapable / LogisticsProductCapable /
│ │ WarehouseDirectoryCapable
│ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired /
│ │ DuplicateOrder / WebhookVerification
│ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore /
│ │ UnmatchedCallbackStore
│ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds /
│ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext /
│ WarehouseConnection(主基址 + 可选辅助基址)/ WarehouseWriteScope /
│ WebhookSignatures(HMAC / 恒定时间比较 / 时间窗)
│
├── yqn 运去哪三方仓(warehouse-sdk-yqn)
│ ├── 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 /
│ │ YqnLogisticsProductDtos / YqnWarehouseDtos /
│ │ 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 / HengjianTrackingChangeMapper /
│ HengjianFeeMapper / HengjianEstimateMapper /
│ HengjianInventoryMapper / HengjianInboundMapper /
│ HengjianInboundQueryMapper / HengjianTransferMapper /
│ HengjianReturnMapper / HengjianReturnQueryMapper /
│ HengjianDestructionMapper / HengjianBoxLabelMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
│ HengjianCancelOrderDtos / HengjianTrackingChangeDtos /
│ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos /
│ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos /
│ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos /
│ HengjianInventoryDtos / HengjianInventoryMovementDtos /
│ HengjianInboundCreateDtos / HengjianInboundQueryDtos /
│ HengjianTransferDtos / HengjianReturnPlanCreateDtos /
│ HengjianReturnDetailDtos / HengjianReturnListDtos /
│ HengjianReturnHandleDtos / HengjianOrderAttachmentDtos /
│ HengjianDestructionDtos / HengjianBoxLabelDtos
├── 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。
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 |
原始报文、水位线、审计 |
CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
// → "WALMART_SC:oms-wm-001:PO-123" 直连与领星算出来完全一样
写操作要两把锁:
// 业务幂等键:不带 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 单次查询(不推进水位线)
适合人工排查、补偿。宿主自己决定拉哪个时间窗。
// 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 负责「翻页 + 落库 + 水位线」。整批成功才推进,失败不推进。
// 宿主实现这两个 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 门面调用
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():
// 领星上 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 请求键一起抢占;重复调用返回已完成结果,不算失败。
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 在每次门面调用结束时回调一次(成功与失败都回调)。
最省事的写法
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 即可:
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 步:实现能力接口。只实现真正支持的,其余不实现:
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,与直连/聚合器同一套注册机制:
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,按账户的子平台细化能力:
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 新增一个能力(如退款)
Capability加枚举值;capability/下加接口(可选动作给default方法抛UnsupportedCapabilityException,适配器只覆写支持的);- 适配器声明能力并实现;
- 领域模型加实体(
Refund/ReturnOrder…); Sink加对应upsert,testkit 加InMemory实现。
不会改动的:PlatformAdapter、ChannelContext、AccountKey、CanonicalKeys、SyncEngine、IdempotencyGuard。
4.4 新增一个 SPI
宿主可能需要新的副作用出口(如 RefundLedger、RawPayloadStore)。
spi/下定义纯接口,不引入 JDBC/Redis 类型;- 提供
InMemory实现进 testkit,保证适配器可脱离宿主测试; - 通过
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
每个平台至少准备「正常 + 异常」两套。
写法
// 联调直接用真实接口,见 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。
直连抽象与幂等守卫不用真平台也能测:
// 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());
执行
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:开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试- OMS 侧
cross-border-fulfillment-sdk-design.md(Spec 0 总体设计)