|
|
|
|
# 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 总体设计)
|