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.

887 lines
42 KiB

# common-ecommerce
多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。
## 定位
纯 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 / ...
```
## 架构图
**分层与依赖**:业务只依赖 `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 · 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-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 生成访问器 |
依赖方向:
```
channel ─┐
http ────┼──→ shared
testkit ─┘
lingxing ──→ channel, http, shared
```
渠道域与未来的仓库域平级,互不依赖,只共享 `shared`。`http` 不依赖 `channel`,仓库域可以直接复用传输层与令牌管理。
**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
│
├── shared 跨域共享层(shared)
│ ├── 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 / 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)
│ ├── 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 与令牌(http)
│ 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/
```
包名统一前缀 `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` 不做退避重试,重试节奏由宿主调度决定。
---
## 四、扩展方式
### 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
```
---
## 六、待办与待核对
**待实现**
| 项 | 说明 |
|:---|:---|
| `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 总体设计)