|
|
|
@ -7,25 +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-core` | 领域模型、能力接口、门面、管道、SPI。**零第三方运行时依赖** | |
|
|
|
| `common-ecommerce-shared` | **跨域共享层**:异常体系、SPI 契约、幂等、审计、水位线、通用值对象(Money / Page / PlatformTime / 枚举)。不依赖任何领域模块 | |
|
|
|
| `common-ecommerce-http` | HTTP 传输、签名、令牌管理、JSON 编解码 | |
|
|
|
| `common-ecommerce-channel` | 渠道域:领域模型、能力接口、门面、同步管道。依赖 `shared` | |
|
|
|
|
|
|
|
| `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 生成访问器 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
依赖方向: |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
channel ─┐ |
|
|
|
|
|
|
|
http ────┼──→ shared |
|
|
|
|
|
|
|
testkit ─┘ |
|
|
|
|
|
|
|
lingxing ──→ channel, http, shared |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
渠道域与未来的仓库域平级,互不依赖,只共享 `shared`。`http` 不依赖 `channel`,仓库域可以直接复用传输层与令牌管理。 |
|
|
|
|
|
|
|
|
|
|
|
**Lombok 使用范围**:仅 `lingxing` 模块的 `dto/*`,`scope=provided`,不进宿主运行时。 |
|
|
|
**Lombok 使用范围**:仅 `lingxing` 模块的 `dto/*`,`scope=provided`,不进宿主运行时。 |
|
|
|
`core` 的领域模型是**不可变 + Builder**,不使用 Lombok——省下的行数有限, |
|
|
|
`channel` 的领域模型是**不可变 + Builder**,不使用 Lombok——省下的行数有限, |
|
|
|
而 `core` 要尽量少依赖编译期工具。 |
|
|
|
而 `channel` 要尽量少依赖编译期工具。 |
|
|
|
|
|
|
|
|
|
|
|
## 构建 |
|
|
|
## 构建 |
|
|
|
|
|
|
|
|
|
|
|
@ -40,29 +139,149 @@ mvn clean test |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
## 一、包职责 |
|
|
|
## 一、包结构 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
按当前代码实际目录生成(`src/main/java`,测试包与主代码同构)。模块名在注释里标出。 |
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
``` |
|
|
|
common.ecommerce |
|
|
|
common.ecommerce |
|
|
|
├── model 领域模型(core) |
|
|
|
│ |
|
|
|
│ ├── account AccountKey / ChannelAccount |
|
|
|
├── shared 跨域共享层(shared) |
|
|
|
│ ├── order SalesOrder / OrderLine / Query / Ref |
|
|
|
│ ├── model Platform / ChannelProvider / Capability / FulfillmentMode |
|
|
|
│ ├── product ProductListing / Query / Ref / SyncStrategy |
|
|
|
│ ├── error ChannelException + Auth / RateLimit / Transient / Validation / |
|
|
|
│ └── support Money / PlatformTime / Page / CanonicalKeys |
|
|
|
│ │ PlatformBusiness / IdempotencyConflict / CrossProviderConflict |
|
|
|
├── capability 能力接口,适配器实现这些(core) |
|
|
|
│ ├── spi AccessToken / ChannelSecret / TokenStore / LockProvider / |
|
|
|
├── error 统一异常体系(core) |
|
|
|
│ │ IdempotencyStore(+Claim/Record/Status) / SyncCursorStore / |
|
|
|
├── sdk 门面、上下文、适配器工厂接口(core) |
|
|
|
│ │ SecretProvider(已废弃) |
|
|
|
├── sync 增量同步引擎与水位线计算(core) |
|
|
|
│ ├── idempotency IdempotencyGuard / WriteScope / WriteResult / WriteAudit |
|
|
|
├── idempotency 写操作双锁幂等守卫(core) |
|
|
|
│ ├── audit CallObserver / CallRecord / CallOutcome / Slf4jCallObserver |
|
|
|
├── spi 宿主必须实现的扩展点(core) |
|
|
|
│ ├── sync SyncSpec / SyncResult |
|
|
|
├── http HTTP 传输、JSON、签名、令牌(http) |
|
|
|
│ ├── support Money / PlatformTime / Page / CanonicalKeys |
|
|
|
├── testkit 测试替身与夹具(testkit) |
|
|
|
│ └── testkit 测试替身(testkit 模块): |
|
|
|
└── lingxing 领星适配器(lingxing) |
|
|
|
│ 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 / Signer / 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.`,下表省略前缀。 |
|
|
|
包名统一前缀 `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。 |
|
|
|
|
|
|
|
|
|
|
|
@ -70,31 +289,32 @@ common.ecommerce |
|
|
|
|
|
|
|
|
|
|
|
| 子包 | 内容 | |
|
|
|
| 子包 | 内容 | |
|
|
|
|:---|:---| |
|
|
|
|:---|:---| |
|
|
|
| `model`(本包) | **枚举**:`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` | |
|
|
|
| `channel.model.account` | `AccountKey` / `ChannelAccount` | |
|
|
|
| `model.account` | `AccountKey` / `ChannelAccount` | |
|
|
|
| `channel.model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` | |
|
|
|
| `model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` | |
|
|
|
| `channel.model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSearchField` / `ProductStatus` / `ProductSyncStrategy` | |
|
|
|
| `model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSyncStrategy` | |
|
|
|
| `channel.model.fulfillment` | `OutboundOrder` / `OutboundOrderLine` / `OutboundOrderQuery` / `OutboundPackage` / `OutboundResult` / `ShippingLabel` / `LabelQuery` / `OrderEditRequest` / `OrderEditResult` / `ShipmentReviewResult` / `DeclaredItem` | |
|
|
|
| `model.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` | |
|
|
|
| `channel.model.aftersale` | `AfterSale` / `AfterSaleQuery` / `AfterSaleType` | |
|
|
|
|
|
|
|
| `channel.model.settlement` | `SettlementQuery` / `SettlementTransaction` | |
|
|
|
|
|
|
|
|
|
|
|
| 类 | 包袱 | 职责 | |
|
|
|
| 类 | 包袱 | 职责 | |
|
|
|
|:---|:---|:---| |
|
|
|
|:---|:---|:---| |
|
|
|
| `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`,不静默返回空。 |
|
|
|
|
|
|
|
|
|
|
|
@ -104,10 +324,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`。 |
|
|
|
|
|
|
|
|
|
|
|
@ -128,39 +349,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(加密) | |
|
|
|
@ -168,7 +391,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` —— 出入网层 |
|
|
|
@ -194,14 +417,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` | 工厂注册 | |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
@ -238,9 +511,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) |
|
|
|
适合需要自己控制时间窗、翻页与落库的场景。 |
|
|
|
适合需要自己控制时间窗、翻页与落库的场景。 |
|
|
|
@ -252,24 +526,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() |
|
|
|
@ -328,7 +603,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"); |
|
|
|
@ -411,9 +686,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 步:实现能力接口**。只实现真正支持的,其余不实现: |
|
|
|
|
|
|
|
|
|
|
|
@ -499,9 +774,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 不许私起线程 | |
|
|
|
| 能力声明与实际实现不一致 | 验收项,缺失能力必须显式抛异常 | |
|
|
|
| 能力声明与实际实现不一致 | 验收项,缺失能力必须显式抛异常 | |
|
|
|
@ -528,20 +803,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")) |
|
|
|
@ -556,12 +832,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(); |
|
|
|
|
|
|
|
|
|
|
|
// 双锁幂等:第二次调用回放,平台只真正写一次 |
|
|
|
// 双锁幂等:第二次调用回放,平台只真正写一次 |
|
|
|
@ -577,7 +853,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 |
|
|
|
``` |
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|