@ -7,35 +7,124 @@
@@ -7,35 +7,124 @@
纯 SDK 库,嵌入宿主(OMS)进程运行。**不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器**。所有外部副作用通过 SPI 注入,由宿主实现。
```
① 统一入口 ChannelSdk / 各能力门面
② 能力接口 ProductCapable / SalesOrderCapable / Fulfillment Capable / ...
③ 平台适配 amazon-sc / walmart-sc / tiktok / temu / lingxing / ...
④ 基础设施 HttpTransport / Signer / TokenManager / RateLimiter / SyncEngine / Idempotency
① 统一入口 ChannelSdk / 各能力视图(SalesOrders / Products / Outbounds / AfterSales / Settlements)
② 能力接口 ProductCapable / SalesOrderCapable / ShippingLabelCapable / AfterSale Capable / ...
③ 平台适配 lingxing(聚合:amazon-sc / walmart / tiktok / temu / ebay / shein / target …)
④ 基础设施 HttpTransport / Signer / TokenManager / Lingxing RateLimiter / SyncEngine / Idempotency
⑤ 宿主 SPI AccountRepository / TokenStore / SyncCursorStore / Sink / Clock / LockProvider / ...
```
## 架构图
**分层与依赖**:业务只依赖 `channel` 的门面与模型;平台协议全部关在适配器里;
`shared` 被所有模块共享,但不反向依赖任何领域模块。
```mermaid
graph TD
subgraph HOST["宿主进程(OMS)"]
BIZ["业务代码"]
IMPL["宿主 SPI 实现< br / > MySQL · Redis/Redisson · KMS"]
end
subgraph SDK["common-ecommerce"]
FACADE["channel · 门面< br / > ChannelSdk · 能力视图< br / > SalesOrders / Products / Outbounds / AfterSales / Settlements"]
CAP["channel · 能力接口< br / > PlatformAdapter · SalesOrderCapable · ProductCapable …"]
CMODEL["channel · 领域模型< br / > SalesOrder · ProductListing · AccountKey · Page"]
ENGINE["channel · 同步管道< br / > SyncEngine"]
SHARED["shared · 跨域共享层< br / > 异常 · 幂等 · 审计 · 枚举 · SPI 定义 · Money/Page"]
HTTPM["http · 出入网层< br / > HttpTransport · Signer · TokenManager · JsonCodec"]
LX["lingxing · 聚合适配器< br / > LingxingAdapter → LingxingSubPlatforms → 子平台 Source"]
end
EXT["领星开放平台 / 各电商平台"]
BIZ --> FACADE
FACADE --> CAP
FACADE --> CMODEL
FACADE --> ENGINE
FACADE --> SHARED
CAP --> CMODEL
ENGINE --> SHARED
LX -. 实现能力接口 .-> CAP
LX --> CMODEL
LX --> HTTPM
LX --> SHARED
HTTPM --> SHARED
IMPL -. 实现 SPI .-> SHARED
HTTPM --> EXT
```
**模块依赖**(与各模块 `pom.xml` 一致,箭头指向被依赖方):
```mermaid
graph BT
shared["shared< br / > common-ecommerce-shared"]
channel["channel< br / > common-ecommerce-channel"]
http["http< br / > common-ecommerce-http"]
testkit["testkit< br / > common-ecommerce-testkit"]
lingxing["lingxing< br / > common-ecommerce-lingxing"]
channel --> shared
http --> shared
testkit --> shared
testkit --> channel
testkit --> http
lingxing --> shared
lingxing --> channel
lingxing --> http
```
**一次商品查询的调用链**(订单、售后、出库等能力走同一条骨架):
```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
```
## 模块
| 模块 | 职责 |
|:---|:---|
| `common-ecommerce-common` | **跨域共享层** :异常体系、SPI 契约、幂等、审计、水位线、通用值对象(Money / Page / PlatformTime / 枚举)。不依赖任何领域模块 |
| `common-ecommerce-core` | 渠道域:领域模型、能力接口、门面、同步管道。依赖 `common` |
| `common-ecommerce-http` | HTTP 传输、签名、令牌管理、JSON 编解码。依赖 `common` ,**不依赖 `core` ** |
| `common-ecommerce-shared ` | **跨域共享层** :异常体系、SPI 契约、幂等、审计、水位线、通用值对象(Money / Page / PlatformTime / 枚举)。不依赖任何领域模块 |
| `common-ecommerce-channel ` | 渠道域:领域模型、能力接口、门面、同步管道。依赖 `shared ` |
| `common-ecommerce-http` | HTTP 传输、签名、令牌管理、JSON 编解码。依赖 `shared` ,**不依赖 `channel ` ** |
| `common-ecommerce-testkit` | InMemory SPI 与测试替身 |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
依赖方向:
```
core ─┐
http ─┼──→ common
channel ─┐
http ────┼──→ shared
testkit ─┘
lingxing ──→ core, http, common
lingxing ──→ channel, http, shared
```
渠道域与未来的仓库域平级,互不依赖,只共享 `common` 。`http` 不依赖 `core` ,仓库域可以直接复用传输层与令牌管理。
渠道域与未来的仓库域平级,互不依赖,只共享 `shared` 。`http` 不依赖 `channel ` ,仓库域可以直接复用传输层与令牌管理。
**Lombok 使用范围**:仅 `lingxing` 模块的 `dto/*` ,`scope=provided`,不进宿主运行时。
`core` 的领域模型是**不可变 + Builder**,不使用 Lombok——省下的行数有限,
而 `core` 要尽量少依赖编译期工具。
`channel ` 的领域模型是**不可变 + Builder**,不使用 Lombok——省下的行数有限,
而 `channel ` 要尽量少依赖编译期工具。
## 构建
@ -54,25 +143,46 @@ mvn clean test
@@ -54,25 +143,46 @@ mvn clean test
```
common.ecommerce
├── model 领域模型(core)
│ ├── account AccountKey / ChannelAccount
│ ├── order SalesOrder / OrderLine / Query / Ref
│ ├── product ProductListing / Query / Ref / SyncStrategy
│ └── support Money / PlatformTime / Page / CanonicalKeys
├── capability 能力接口,适配器实现这些(core)
├── error 统一异常体系(core)
├── sdk 门面、上下文、适配器工厂接口(core)
├── sync 增量同步引擎与水位线计算(core)
├── idempotency 写操作双锁幂等守卫(core)
├── spi 宿主必须实现的扩展点(core)
├── http HTTP 传输、JSON、签名、令牌(http)
├── testkit 测试替身与夹具(testkit)
└── lingxing 领星适配器(lingxing)
├── shared 跨域共享层(shared)
│ ├── model Platform / ChannelProvider / Capability / FulfillmentMode
│ ├── error 统一异常体系
│ ├── spi AccessToken / TokenStore / LockProvider / IdempotencyStore / SyncCursorStore …
│ ├── idempotency 写操作双锁幂等守卫
│ ├── audit CallObserver / CallRecord
│ ├── sync SyncSpec / SyncResult
│ └── support Money / PlatformTime / Page / CanonicalKeys
├── channel 渠道域(channel)
│ ├── model 领域模型
│ │ ├── account AccountKey / ChannelAccount
│ │ ├── order SalesOrder / OrderLine / Query / Ref
│ │ ├── product ProductListing / Query / Ref / SearchField / SyncStrategy
│ │ ├── fulfillment OutboundOrder / OutboundPackage / ShippingLabel / OrderEdit / ShipmentReview
│ │ ├── aftersale AfterSale / Query / Type
│ │ └── settlement SettlementQuery / SettlementTransaction
│ ├── capability 能力接口,适配器实现这些
│ ├── sdk 门面、上下文、适配器工厂接口
│ ├── sync 同步引擎
│ └── spi ChannelAccountRepository / Sink
├── http HTTP 传输、JSON、签名、令牌(http)
├── testkit 测试替身与夹具(testkit)
└── lingxing 领星适配器(lingxing)
```
包名统一前缀 `common.ecommerce.` ,下表省略前缀。
### `model` —— 领域模型
### `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。
@ -80,31 +190,34 @@ common.ecommerce
@@ -80,31 +190,34 @@ common.ecommerce
| 子包 | 内容 |
|:---|:---|
| `model` (本包) | **枚举** :`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` |
| `model.account` | `AccountKey` / `ChannelAccount` |
| `model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` |
| `model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSyncStrategy` |
| `model.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` |
| `shared.model` | **枚举** :`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` |
| `channel.model.account` | `AccountKey` / `ChannelAccount` |
| `channel.model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` |
| `channel.model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSearchField` / `ProductSyncStrategy` |
| `channel.model.fulfillment` | `OutboundOrder` / `OutboundPackage` / `ShippingLabel` / `OrderEditRequest` / `ShipmentReviewResult` … |
| `channel.model.aftersale` | `AfterSale` / `AfterSaleQuery` / `AfterSaleType` |
| `channel.model.settlement` | `SettlementQuery` / `SettlementTransaction` |
| `shared.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` |
| 类 | 包袱 | 职责 |
|:---|:---|:---|
| `Platform` | 枚举 | 业务平台。**不含 provider**,直连与聚合器映射到同一值 |
| `ChannelProvider` | 枚举 | 接入通道:DIRECT / LINGXING / TEAPPLIX / CUSTOM |
| `Capability` | 枚举 | 能力枚举,适配器声明、门面校验 |
| `FulfillmentMode` | 枚举 | A/C/D 三种履约模式(B 平台仓只读,不在枚举内) |
| `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` | 工具 | 三级标识与指纹计算,见下方「标识体系」 |
| `PlatformTime` | 值对象 | 三轴时间:UTC 真值 + 市场当地 + 北京时间 |
| `Money` | 值对象 | `BigDecimal + Currency` ,跨币种运算直接拒绝 |
| `CanonicalKeys` | 工具(shared) | 三级标识与指纹计算,见下方「标识体系」 |
| `PlatformTime` | 值对象(shared) | 三轴时间:UTC 真值 + 市场当地 + 北京时间 |
| `Money` | 值对象(shared) | `BigDecimal + Currency` ,跨币种运算直接拒绝 |
| `SalesOrder` / `OrderLine` | 实体 | 3P 销售订单 |
| `ProductListing` | 实体 | 商品 / Listing |
| `SalesOrderQuery` / `ProductQuery` | 查询 | 查询条件(时间窗 + 分页游标) |
| `SalesOrderRef` / `ProductRef` | 引用 | 详情入参。**不能用裸 String**,否则订单+商品接口签名冲突 |
| `Page<T>` | 载体 | 分页载体,`nextCursor == null` 表示结束 |
| `Page<T>` | 载体(shared) | 分页载体,`nextCursor == null` 表示结束 |
### `capability` —— 能力接口
### `channel.c apability` —— 能力接口
适配器实现哪些接口就声明哪些能力;未实现的方法抛 `UnsupportedCapabilityException` ,不静默返回空。
@ -114,10 +227,11 @@ common.ecommerce
@@ -114,10 +227,11 @@ common.ecommerce
| `AggregatorCapable` | 聚合器扩展:`listSubChannels(account)`,按子平台细化能力 |
| `SalesOrderCapable` | `pull(ctx, query)` / `get(ctx, SalesOrderRef)` |
| `ProductCapable` | `syncStrategy()` / `pull(ctx, query)` / `get(ctx, ProductRef)` |
| `CapabilityReport` | 能力报告:`supports()` / `supported()` / `unsupported()` |
| `SalesOrders` / `Products` | 门面持有的视图,调用前做能力检查 |
| `SettlementCapable` / `OutboundCapable` / `OutboundOrderCapable` / `ShippingLabelCapable` / `ShipmentReviewCapable` / `OrderEditCapable` / `AfterSaleCapable` | 账单 / 快速出库 / 出库单 / 面单 / 审核发货 / 订单编辑 / 售后 |
| `CapabilityReport` / `AdapterCapabilityReport` | 能力报告:`supports()` / `supported()` / `unsupported()` |
| `SalesOrders` / `Products` / `Outbounds` / `Settlements` / `AfterSales` | 门面持有的视图,调用前做能力检查 |
### `error` —— 异常体系
### `shared. error` —— 异常体系
全部继承 `ChannelException` ,带 `platform / provider / omsStoreId / operation / requestId / platformCode / retryable / rawResponse` 。
@ -138,39 +252,41 @@ common.ecommerce
@@ -138,39 +252,41 @@ common.ecommerce
**同名类** `Responses` 有两个:`http.Responses`(状态码 → 异常)与 `testkit.Responses` (快捷构造响应)。测试里注意 import 哪个。
### `sdk` —— 门面与上下文
### `channel. sdk` —— 门面与上下文
| 类 | 职责 |
|:---|:---|
| `ChannelContext` | 单次调用上下文:`account` + `connection` + `requestId` + `clock` 。**由 SDK 创建,适配器不得自造** |
| `AdapterFactory` | 适配器工厂:`adapterId()` / `provider()` / `platforms()` / `create(AdapterConfig)` |
| `ProviderResolver` | 按 `AccountKey` 解析适配器,不自动选路 |
| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders(key, conn)` / `products(key, conn) ` / `writes()` ;`build()` 校验必需项 |
| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders` / `products` / `settlements` / `afterSales` / `outbounds ` / `writes()` ;`build()` 校验必需项 |
| `ChannelConnection` | 一次调用的连接信息(端点 + 凭据)。**由调用方每次传入,SDK 不保存** |
| `CallSupport` | 门面调用的统一包装:能力检查 + 审计回调 |
### `idempotency` —— 写操作幂等
### `shared. idempotency` —— 写操作幂等
| 类 | 职责 |
|:---|:---|
| `WriteScope` | 一次写操作的维度:`provider + platform + omsStoreId + externalStoreId + action + businessRef` |
| `WriteResult` | 执行结果:`EXECUTED` / `ALREADY_COMPLETED` (回放,不算失败) |
| `IdempotencyGuard` | 双锁守卫:业务键(跨 provider)+ provider 请求键(单 provider 内重试) |
| `WriteAudit` | 写操作审计留痕 |
### `sync` —— 增量同步
### `channel.sync` + `shared. sync` —— 增量同步
| 类 | 职责 |
|:---|:---|
| `SyncSpec` | 同步维度:`provider + accountKey + stream + overlap` |
| `SyncResult` | 单次结果:页数、条目数、水位线是否推进 |
| `SyncEngine` | 分页循环 + 落库 + 水位线推进 |
| `SyncSpec` (shared) | 同步维度:`provider + accountKey + stream + overlap` |
| `SyncResult` (shared) | 单次结果:页数、条目数、水位线是否推进 |
| `SyncEngine` (channel) | 分页循环 + 落库 + 水位线推进 |
### `spi` —— 宿主扩展点
### `shared.spi` + `channel.s pi` —— 宿主扩展点
**SDK 只定义,宿主实现。SDK 内部不碰 JDBC / Redis / MQ。**
| SPI | 作用 | 典型实现 |
|:---|:---|:---|
| `ChannelAccountRepository` | 读渠道账户 | MySQL |
| `ChannelAccountRepository` (channel) | 读渠道账户 | MySQL |
| `SecretProvider` | **已不再使用** :凭据改由调用方经 `ChannelConnection` 传入 | — |
| `ChannelSecret` | 凭据载体(appKey/appSecret/clientId/… + endpointBaseUrl),`fingerprint()` 供日志 |
| `TokenStore` | access/refresh token 读写 | MySQL / Redis(加密) |
@ -178,7 +294,7 @@ common.ecommerce
@@ -178,7 +294,7 @@ common.ecommerce
| `SyncCursorStore` | 水位线读写 | MySQL |
| `IdempotencyStore` | 幂等键抢占与结果记录;`claim` 必须原子 | MySQL / Redis |
| `IdempotencyClaim` / `IdempotencyRecord` / `IdempotencyStatus` | 抢占结果、记录、四态(IN_PROGRESS / SUCCEEDED / FAILED_RETRYABLE / FAILED_FINAL) | — |
| `Sink` | 领域对象落库(当前 `upsertSalesOrders` / `upsertProducts` ) | MyBatis |
| `Sink` (channel) | 领域对象落库(当前 `upsertSalesOrders` / `upsertProducts` ) | MyBatis |
| `LockProvider` | token 刷新防击穿、账户级互斥 | Redisson / DB |
### `http` —— 出入网层
@ -204,14 +320,64 @@ common.ecommerce
@@ -204,14 +320,64 @@ common.ecommerce
### `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` | `SalesOrderCapable` + `AggregatorCapable` ,订单列表拉取 |
| `LingxingConstants` | 端点、限制(31 天 / length≤500)、`platform_code → Platform` 映射 |
| `LingxingSigner` | 公共参数 ASCII 升序 + appSecret 前后包裹 + MD5 |
| `LingxingTokenClient` | 换取 access_token |
| `LingxingOrderMapper` | 领星报文 → `SalesOrder` |
| `dto/*` | 领星原始报文结构(Jackson 映射) |
| `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` | 工厂注册 |
---
@ -248,9 +414,10 @@ CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "w
@@ -248,9 +414,10 @@ CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "w
### 状态说明
`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders(key, conn)` / `products(key, conn)` / `writes()` 已挂接,
`build()` 做必需项校验(缺 `accountRepository` 、缺适配器都会抛异常)。
目前仅接入了订单与商品两种能力,其余能力随适配器逐个补齐。
`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders` / `products` / `settlements` /
`afterSales` / `outbounds` / `writes()` 均已挂接,`build()` 做必需项校验(缺 `accountRepository` 、
缺适配器都会抛异常)。领星适配器当前声明订单、商品、账单、标发、退货、出库单、面单、审核发货、
订单编辑能力,能力再按子平台细化(见 3.4)。
两条调用路径都可以用:**门面**(3.3)适合业务层;**适配器 + SyncEngine**(3.1 / 3.2)
适合需要自己控制时间窗、翻页与落库的场景。
@ -262,24 +429,25 @@ CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "w
@@ -262,24 +429,25 @@ CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "w
```java
// 1) 宿主实现 SPI
ChannelAccountRepository accountRepo = ...; // MySQL
SecretProvider secretProvider = ...; // KMS
TokenStore tokenStore = ...; // 加密存储
LockProvider lockProvider = ...; // Redisson / DB
// 2) 创建适配器(也可经 LingxingAdapterFactory.create)
LingxingAdapter adapter = new LingxingAdapter(
LingxingConstants.DEFAULT_BASE_URL,
new OkHttpTransport("common-ecommerce/1.0.0 (lingxing)"),
new JacksonJsonCodec(),
secretProvider, tokenStore, lockProvider,
tokenStore, lockProvider,
Clock.systemUTC());
// 3) 取账户 → 组装调用上下文
// 3) 取账户 + 连接 → 组装调用上下文
ChannelAccount account = accountRepo
.findByKey("LINGXING", "WALMART_SC", "oms-wm-001")
.orElseThrow(() -> new IllegalStateException("account not configured"));
ChannelContext ctx = ChannelContext.of(account, UUID.randomUUID().toString(), Clock.systemUTC());
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()
@ -338,7 +506,7 @@ ChannelSdk sdk = ChannelSdk.builder()
@@ -338,7 +506,7 @@ ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo) // 必需
.clock(Clock.systemUTC()) // 可选,默认 UTC
.idempotencyStore(idempotencyStore) // 写操作用;不注入则 writes() 失败
.register(new LingxingAdapterFactory(secretProvider, tokenStore, lockProvider, Clock.systemUTC()))
.register(new LingxingAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
.build(); // 缺必需项立刻抛异常
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
@ -421,9 +589,9 @@ result.outcome(); // EXECUTED / ALREADY_COMPLETED
@@ -421,9 +589,9 @@ result.outcome(); // EXECUTED / ALREADY_COMPLETED
### 4.1 新增一个直连平台
以新增 `amazon-sc` 为例,**不改 core 、不改门面、不改宿主**。
以新增 `amazon-sc` 为例,**不改 channel 、不改门面、不改宿主**。
**第 1 步:建模块**,`pom.xml` 只依赖 core 与 http 。
**第 1 步:建模块**,`pom.xml` 只依赖 channel、http 与 shared 。
**第 2 步:实现能力接口**。只实现真正支持的,其余不实现:
@ -509,9 +677,9 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC
@@ -509,9 +677,9 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC
| 不做 | 原因 |
|:---|:---|
| `core ` 引 Spring / JDBC / Redis / MQ | SDK 要能脱离宿主单测 |
| `channel ` 引 Spring / JDBC / Redis / MQ | SDK 要能脱离宿主单测 |
| 把平台端点、字段名做成配置表 | 协议是代码,配置化会让线上线下跑不同协议 |
| 密钥写入 `ChannelAccount` | 只能存 `credentialRef` ,密钥走 `SecretProvider` |
| 密钥写入 `ChannelAccount` | 只能存 `credentialRef` ,密钥经 `ChannelConnection` 在调用时传入 |
| provider 进 canonicalKey | 直连/聚合器切换会产生重复实体 |
| 在适配器里 `new Thread` / 定时器 | 调度归宿主,SDK 不许私起线程 |
| 能力声明与实际实现不一致 | 验收项,缺失能力必须显式抛异常 |
@ -538,20 +706,21 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC
@@ -538,20 +706,21 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC
src/test/resources/fixtures/{platform}/{operation}/{case}.json
```
例:`lingxing/src/test/resources/fixtures/lingxing/orderList /success.json`
例:`lingxing/src/test/resources/fixtures/lingxing/walmartListing /success.json`
每个平台至少准备「正常 + 异常」两套。
### 写法
```java
// 联调直接用真实接口,见 LingxingLiveSmokeTest
// 联调直接用真实接口,见 LingxingLiveSmokeTest;
// 契约测试用 RecordingTransport + 夹具,不联网
LingxingAdapter adapter = new LingxingAdapter(LingxingConstants.DEFAULT_BASE_URL, transport,
new JacksonJsonCodec(), accounts, tokenStore, locks,
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, "req-1", clock);
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"))
@ -566,12 +735,12 @@ assertTrue(last.body().contains("\"platform_code\":10008"));
@@ -566,12 +735,12 @@ assertTrue(last.body().contains("\"platform_code\":10008"));
assertEquals("PO-123456789", page.items().get(0).channelOrderId());
```
完整示例见 `lingxing/src/test/java/.../LingxingAdapter Test.java` 。
完整示例见 `lingxing/src/test/java/.../LingxingSdkListingCall Test.java` 。
直连抽象与幂等守卫不用真平台也能测:
```java
// core 抽象没被聚合器带偏:单平台、能力并集、游标翻页
// channel 抽象没被聚合器带偏:单平台、能力并集、游标翻页
FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build();
// 双锁幂等:第二次调用回放,平台只真正写一次
@ -587,7 +756,7 @@ assertEquals(1, adapter.writeCallCount());
@@ -587,7 +756,7 @@ assertEquals(1, adapter.writeCallCount());
```bash
mvn test # 全部
mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingAdapter Test test
mvn -pl lingxing -Dtest=LingxingSdkListingCall Test test
```
---