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