diff --git a/README.md b/README.md index d5ba042..638a1ae 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,8 @@ apelet.common.ecommerce | `AggregatorCapable` | 聚合器扩展:`listSubChannels(account)`,按子平台细化能力 | | `SalesOrderCapable` | `pull(ctx, query)` / `get(ctx, orderId)` | | `ProductCapable` | `syncStrategy()` / `pull(ctx, query)` / `get(ctx, sku)` | +| `CapabilityReport` | 能力报告:`supports()` / `supported()` / `unsupported()` | +| `SalesOrders` / `Products` | 门面持有的视图,调用前做能力检查 | ### `error` —— 异常体系 @@ -107,7 +109,8 @@ apelet.common.ecommerce |:---|:---| | `ChannelContext` | 单次调用上下文:`account` + `requestId` + `clock`。**由 SDK 创建,适配器不得自造** | | `AdapterFactory` | 适配器工厂:`adapterId()` / `provider()` / `platforms()` / `create(AdapterConfig)` | -| `ChannelSdk` | 统一门面。**当前为骨架,见「调用方式」中的状态说明** | +| `ProviderResolver` | 按 `AccountKey` 解析适配器,不自动选路 | +| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders()` / `products()`;`build()` 校验必需项 | ### `sync` —— 增量同步 @@ -197,8 +200,12 @@ CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "w ### 状态说明 -`ChannelSdk` 门面目前是骨架(`builder().build()` 返回空对象,门面方法尚未挂接)。 -**当前可用的调用路径是「适配器 + SyncEngine」**,即下方 3.1 / 3.2。3.3 是门面接入后的目标形态。 +`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders()` / `products()` 已挂接, +`build()` 做必需项校验(缺 `accountRepository`、缺适配器都会抛异常)。 +目前仅接入了订单与商品两种能力,其余能力随适配器逐个补齐。 + +两条调用路径都可以用:**门面**(3.3)适合业务层;**适配器 + SyncEngine**(3.1 / 3.2) +适合需要自己控制时间窗、翻页与落库的场景。 ### 3.1 单次查询(不推进水位线) @@ -276,15 +283,14 @@ result.watermarkAdvanced(); // true == 水位线已推进到 to - **水位线维度**:`provider + accountKey + stream`,直连与领星各存各的,不能复用。 - **调度归宿主**:SDK 不持有线程和定时器,由 OMS 调度器触发 `syncSalesOrders`。 -### 3.3 门面形态(接入后) - -> ⚠️ 下面这段是**目标形态**,`ChannelSdk.Builder` 的 `register` / `accountRepository` 与门面方法当前尚未实现(见第六节待办)。 +### 3.3 门面调用 ```java ChannelSdk sdk = ChannelSdk.builder() + .accountRepository(accountRepo) // 必需 + .clock(Clock.systemUTC()) // 可选,默认 UTC .register(new LingxingAdapterFactory(secretProvider, tokenStore, lockProvider, Clock.systemUTC())) - .accountRepository(accountRepo) - .build(); + .build(); // 缺必需项立刻抛异常 AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); @@ -296,6 +302,22 @@ if (!caps.supports(Capability.SALES_ORDER)) { ... } Page page = sdk.salesOrders(key).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()`: @@ -479,11 +501,9 @@ mvn -pl lingxing -Dtest=LingxingAdapterTest test | 项 | 说明 | |:---|:---| -| `ChannelSdk` 门面 | 当前为空壳,`create` 与门面方法待挂接 | -| `ProviderResolver` | 按 `AccountKey` 解析适配器的注册表 | +| `FakeDirectAdapter` 进 testkit | 当前以 `ChannelSdkTest` 内部类形式存在,验证后抽到 testkit | | `IdempotencyStore` + 双锁 | 写操作幂等尚未装配 | | `RawPayloadStore` | 原始报文留痕 | -| `FakeDirectAdapter` | 验证 core 抽象未被聚合器带偏 | | 其余由文档 `Spec 0` 定义的能力 | 履约、面单、账单、售后、Webhook、异步报表 | **待核对(需官方文档 + 真实沙箱,联调时集中修改)** diff --git a/core/src/main/java/apelet/common/ecommerce/capability/AdapterCapabilityReport.java b/core/src/main/java/apelet/common/ecommerce/capability/AdapterCapabilityReport.java new file mode 100644 index 0000000..39c2641 --- /dev/null +++ b/core/src/main/java/apelet/common/ecommerce/capability/AdapterCapabilityReport.java @@ -0,0 +1,60 @@ +package apelet.common.ecommerce.capability; + +import apelet.common.ecommerce.model.Capability; +import apelet.common.ecommerce.model.ChannelAccount; + +import java.util.EnumSet; + +/** + * 由适配器与账户推导出的能力报告。 + * + *

逐项询问 {@link PlatformAdapter#supports(ChannelAccount, Capability)}, + * 因此聚合器能按子平台给出精确结果,而直连适配器等价于 {@code capabilities()}。

+ */ +public final class AdapterCapabilityReport implements CapabilityReport { + + private final PlatformAdapter adapter; + private final ChannelAccount account; + private final EnumSet supported; + + public AdapterCapabilityReport(PlatformAdapter adapter, ChannelAccount account) { + this.adapter = adapter; + this.account = account; + this.supported = EnumSet.noneOf(Capability.class); + for (Capability c : Capability.values()) { + if (adapter.supports(account, c)) { + supported.add(c); + } + } + } + + @Override + public boolean supports(Capability capability) { + return supported.contains(capability); + } + + @Override + public EnumSet supported() { + return EnumSet.copyOf(supported); + } + + @Override + public EnumSet unsupported() { + EnumSet all = EnumSet.allOf(Capability.class); + all.removeAll(supported); + return all; + } + + public PlatformAdapter adapter() { + return adapter; + } + + public ChannelAccount account() { + return account; + } + + @Override + public String toString() { + return "Capabilities[" + adapter.adapterId() + "/" + account.omsStoreId() + "] supported=" + supported; + } +} diff --git a/core/src/main/java/apelet/common/ecommerce/capability/CapabilityReport.java b/core/src/main/java/apelet/common/ecommerce/capability/CapabilityReport.java new file mode 100644 index 0000000..7902bc0 --- /dev/null +++ b/core/src/main/java/apelet/common/ecommerce/capability/CapabilityReport.java @@ -0,0 +1,19 @@ +package apelet.common.ecommerce.capability; + +import apelet.common.ecommerce.model.Capability; + +import java.util.EnumSet; + +/** + * 能力报告:只读,不触发真实 API。 + * + *

调用方据此决定是否换账户、走直连或人工,SDK 不做推荐与兜底。

+ */ +public interface CapabilityReport { + + boolean supports(Capability capability); + + EnumSet supported(); + + EnumSet unsupported(); +} diff --git a/core/src/main/java/apelet/common/ecommerce/capability/Products.java b/core/src/main/java/apelet/common/ecommerce/capability/Products.java new file mode 100644 index 0000000..9f83269 --- /dev/null +++ b/core/src/main/java/apelet/common/ecommerce/capability/Products.java @@ -0,0 +1,39 @@ +package apelet.common.ecommerce.capability; + +import apelet.common.ecommerce.error.ChannelException; +import apelet.common.ecommerce.model.Capability; +import apelet.common.ecommerce.model.ChannelAccount; +import apelet.common.ecommerce.model.Page; +import apelet.common.ecommerce.model.ProductListing; +import apelet.common.ecommerce.model.ProductQuery; +import apelet.common.ecommerce.sdk.ChannelContext; + +/** 门面持有的商品视图。 */ +public final class Products { + + private final PlatformAdapter adapter; + private final ChannelAccount account; + private final ChannelContext ctx; + + public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this.adapter = adapter; + this.account = account; + this.ctx = ctx; + } + + public Page pull(ProductQuery query) { + requireProductCapable(); + return ((ProductCapable) adapter).pull(ctx, query); + } + + public ProductListing get(String platformSku) { + requireProductCapable(); + return ((ProductCapable) adapter).get(ctx, platformSku); + } + + private void requireProductCapable() { + if (!adapter.supports(account, Capability.PRODUCT) || !(adapter instanceof ProductCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.PRODUCT); + } + } +} diff --git a/core/src/main/java/apelet/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/apelet/common/ecommerce/capability/SalesOrders.java new file mode 100644 index 0000000..27b2c24 --- /dev/null +++ b/core/src/main/java/apelet/common/ecommerce/capability/SalesOrders.java @@ -0,0 +1,41 @@ +package apelet.common.ecommerce.capability; + +import apelet.common.ecommerce.model.Capability; +import apelet.common.ecommerce.model.ChannelAccount; +import apelet.common.ecommerce.error.ChannelException; +import apelet.common.ecommerce.model.SalesOrder; +import apelet.common.ecommerce.model.SalesOrderQuery; +import apelet.common.ecommerce.model.Page; +import apelet.common.ecommerce.sdk.ChannelContext; + +/** + * 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。 + */ +public final class SalesOrders { + + private final PlatformAdapter adapter; + private final ChannelAccount account; + private final ChannelContext ctx; + + public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { + this.adapter = adapter; + this.account = account; + this.ctx = ctx; + } + + public Page pull(SalesOrderQuery query) { + requireSalesOrderCapable(); + return ((SalesOrderCapable) adapter).pull(ctx, query); + } + + public SalesOrder get(String channelOrderId) { + requireSalesOrderCapable(); + return ((SalesOrderCapable) adapter).get(ctx, channelOrderId); + } + + private void requireSalesOrderCapable() { + if (!adapter.supports(account, Capability.SALES_ORDER) || !(adapter instanceof SalesOrderCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER); + } + } +} diff --git a/core/src/main/java/apelet/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/apelet/common/ecommerce/sdk/ChannelSdk.java index 93aa220..39e66a3 100644 --- a/core/src/main/java/apelet/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/apelet/common/ecommerce/sdk/ChannelSdk.java @@ -1,19 +1,169 @@ package apelet.common.ecommerce.sdk; -/** 渠道 SDK 门面(骨架,逐个能力补齐)。 */ -public final class ChannelSdk { +import apelet.common.ecommerce.capability.AdapterCapabilityReport; +import apelet.common.ecommerce.capability.CapabilityReport; +import apelet.common.ecommerce.capability.PlatformAdapter; +import apelet.common.ecommerce.capability.Products; +import apelet.common.ecommerce.capability.SalesOrders; +import apelet.common.ecommerce.model.AccountKey; +import apelet.common.ecommerce.model.ChannelAccount; +import apelet.common.ecommerce.spi.ChannelAccountRepository; - private ChannelSdk() { +import java.time.Clock; +import java.util.ArrayList; +import java.util.Collection; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.UUID; + +/** + * 渠道 SDK 统一门面。 + * + *

业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入, + * SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。

+ * + *

provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、 + * 不自动选路、不自动兜底;能力缺失时抛 + * {@code ChannelException.UnsupportedCapabilityException}。

+ */ +public final class ChannelSdk implements ProviderResolver { + + private final Map adapters; + private final ChannelAccountRepository accountRepository; + private final Clock clock; + + private ChannelSdk(Builder b) { + this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters)); + this.accountRepository = b.accountRepository; + this.clock = b.clock; } public static Builder builder() { return new Builder(); } + // ------------------------------------------------------------------ 门面方法 + + /** 能力矩阵,只读,不触发任何真实 API。 */ + public CapabilityReport capabilities(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new AdapterCapabilityReport(resolve(key), account); + } + + /** 3P 销售订单视图。 */ + public SalesOrders salesOrders(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new SalesOrders(resolve(key), account, newContext(account)); + } + + /** 商品 / Listing 视图。 */ + public Products products(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new Products(resolve(key), account, newContext(account)); + } + + /** 按 AccountKey 解析适配器;不自动选路、不自动兜底。 */ + @Override + public PlatformAdapter resolve(AccountKey key) { + PlatformAdapter adapter = adapters.get(registryKey(key)); + if (adapter == null) { + throw new IllegalStateException("no adapter registered for " + key + + "; registered: " + adapters.keySet()); + } + return adapter; + } + + // ------------------------------------------------------------------ internals + + private ChannelAccount requireAccount(AccountKey key) { + return accountRepository.findByKey(key.provider().name(), key.platform().name(), key.omsStoreId()) + .orElseThrow(() -> new IllegalStateException("channel account not configured: " + key)); + } + + private ChannelContext newContext(ChannelAccount account) { + return ChannelContext.of(account, UUID.randomUUID().toString(), clock); + } + + /** 注册维度:provider + platform。同一组合下只能有一个适配器。 */ + private static String registryKey(AccountKey key) { + return key.provider().name() + '|' + key.platform().name(); + } + + // ------------------------------------------------------------------ builder + public static final class Builder { + private final Map adapters = new LinkedHashMap(); + private final List factories = new ArrayList(); + private ChannelAccountRepository accountRepository; + private Clock clock = Clock.systemUTC(); + + /** 注入账户仓库;宿主实现。 */ + public Builder accountRepository(ChannelAccountRepository accountRepository) { + this.accountRepository = accountRepository; + return this; + } + + /** 注入时钟;测试可给固定时间。 */ + public Builder clock(Clock clock) { + this.clock = clock; + return this; + } + + /** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */ + public Builder register(AdapterFactory factory) { + this.factories.add(Objects.requireNonNull(factory, "factory")); + return this; + } + + public Builder registerAll(Collection factories) { + if (factories != null) { + for (AdapterFactory f : factories) { + register(f); + } + } + return this; + } + + /** 直接注册适配器实例,主要用于测试替身。 */ + public Builder register(PlatformAdapter adapter) { + Objects.requireNonNull(adapter, "adapter"); + for (apelet.common.ecommerce.model.Platform p : adapter.platforms()) { + put(adapter.provider().name() + '|' + p.name(), adapter); + } + return this; + } + + /** + * 构建门面。 + * + *

缺必需配置时立刻失败,而不是返回一个不可用的空对象。

+ */ public ChannelSdk build() { - return new ChannelSdk(); + if (accountRepository == null) { + throw new IllegalStateException("ChannelSdk requires an accountRepository"); + } + if (clock == null) { + throw new IllegalStateException("ChannelSdk requires a clock"); + } + if (adapters.isEmpty() && factories.isEmpty()) { + throw new IllegalStateException("ChannelSdk requires at least one adapter or adapter factory"); + } + for (AdapterFactory factory : factories) { + register(factory.create(new AdapterFactory.AdapterConfig(null, false))); + } + return new ChannelSdk(this); + } + + private void put(String key, PlatformAdapter adapter) { + PlatformAdapter previous = adapters.put(key, adapter); + if (previous != null && previous != adapter) { + throw new IllegalStateException("duplicate adapter for " + key + + ": " + previous.adapterId() + " / " + adapter.adapterId()); + } } } } diff --git a/core/src/main/java/apelet/common/ecommerce/sdk/ProviderResolver.java b/core/src/main/java/apelet/common/ecommerce/sdk/ProviderResolver.java new file mode 100644 index 0000000..f566925 --- /dev/null +++ b/core/src/main/java/apelet/common/ecommerce/sdk/ProviderResolver.java @@ -0,0 +1,14 @@ +package apelet.common.ecommerce.sdk; + +import apelet.common.ecommerce.capability.PlatformAdapter; +import apelet.common.ecommerce.model.AccountKey; + +/** + * 按 AccountKey 解析适配器。 + * + *

不自动选路、不自动兜底:provider 由调用方在 AccountKey 中显式指定。

+ */ +public interface ProviderResolver { + + PlatformAdapter resolve(AccountKey key); +} diff --git a/core/src/test/java/apelet/common/ecommerce/sdk/ChannelSdkTest.java b/core/src/test/java/apelet/common/ecommerce/sdk/ChannelSdkTest.java new file mode 100644 index 0000000..7aacae7 --- /dev/null +++ b/core/src/test/java/apelet/common/ecommerce/sdk/ChannelSdkTest.java @@ -0,0 +1,183 @@ +package apelet.common.ecommerce.sdk; + +import apelet.common.ecommerce.capability.CapabilityReport; +import apelet.common.ecommerce.capability.PlatformAdapter; +import apelet.common.ecommerce.error.ChannelException; +import apelet.common.ecommerce.model.AccountKey; +import apelet.common.ecommerce.model.Capability; +import apelet.common.ecommerce.model.ChannelAccount; +import apelet.common.ecommerce.model.ChannelProvider; +import apelet.common.ecommerce.model.Page; +import apelet.common.ecommerce.model.Platform; +import apelet.common.ecommerce.model.SalesOrder; +import apelet.common.ecommerce.model.SalesOrderQuery; +import apelet.common.ecommerce.sdk.ChannelContext; +import apelet.common.ecommerce.spi.ChannelAccountRepository; +import org.junit.jupiter.api.Test; + +import java.util.Collections; +import java.util.EnumSet; +import java.util.Optional; +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 门面骨架测试:校验 build 的必需项、路由解析、能力检查。 + */ +class ChannelSdkTest { + + private static final AccountKey WM = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001"); + + /** 假直连适配器:单平台,只有订单能力。 */ + static final class FakeDirectAdapter implements apelet.common.ecommerce.capability.SalesOrderCapable { + + @Override + public String adapterId() { + return "fake-walmart-sc"; + } + + @Override + public ChannelProvider provider() { + return ChannelProvider.DIRECT; + } + + @Override + public Set platforms() { + return EnumSet.of(Platform.WALMART_SC); + } + + @Override + public EnumSet capabilities() { + return EnumSet.of(Capability.SALES_ORDER); + } + + @Override + public Page pull(ChannelContext ctx, SalesOrderQuery query) { + return Page.empty(); + } + + @Override + public SalesOrder get(ChannelContext ctx, String channelOrderId) { + return null; + } + } + + static final class FixedAccounts implements ChannelAccountRepository { + + private final ChannelAccount account; + + FixedAccounts(ChannelAccount account) { + this.account = account; + } + + @Override + public Optional findByKey(String provider, String platform, String omsStoreId) { + return account.provider().name().equals(provider) + && account.platform().name().equals(platform) + && account.omsStoreId().equals(omsStoreId) + ? Optional.of(account) : Optional.empty(); + } + + @Override + public java.util.List findByOmsStoreId(String omsStoreId) { + return Collections.singletonList(account); + } + } + + private static ChannelAccount walmartAccount() { + return ChannelAccount.builder() + .key(WM) + .externalStoreId("wm-seller-01") + .credentialRef("kms://test/wm") + .marketplaceZone("America/Chicago") + .currency("USD") + .build(); + } + + private static ChannelSdk sdkWith(PlatformAdapter adapter) { + return ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .register(adapter) + .build(); + } + + @Test + void buildRequiresAccountRepository() { + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> ChannelSdk.builder().register(new FakeDirectAdapter()).build()); + assertTrue(ex.getMessage().contains("accountRepository"), ex.getMessage()); + } + + @Test + void buildRequiresAtLeastOneAdapter() { + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .build()); + assertTrue(ex.getMessage().contains("adapter"), ex.getMessage()); + } + + @Test + void resolveReturnsRegisteredAdapter() { + FakeDirectAdapter adapter = new FakeDirectAdapter(); + ChannelSdk sdk = sdkWith(adapter); + assertSame(adapter, sdk.resolve(WM)); + } + + @Test + void resolveFailsForUnregisteredProvider() { + ChannelSdk sdk = sdkWith(new FakeDirectAdapter()); + AccountKey lingxing = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); + IllegalStateException ex = assertThrows(IllegalStateException.class, () -> sdk.resolve(lingxing)); + assertTrue(ex.getMessage().contains("no adapter registered"), ex.getMessage()); + } + + @Test + void capabilitiesReflectAdapter() { + ChannelSdk sdk = sdkWith(new FakeDirectAdapter()); + CapabilityReport caps = sdk.capabilities(WM); + assertTrue(caps.supports(Capability.SALES_ORDER)); + assertEquals(false, caps.supports(Capability.REFUND)); + assertTrue(caps.unsupported().contains(Capability.REFUND)); + } + + @Test + void facadeDelegatesToAdapter() { + ChannelSdk sdk = sdkWith(new FakeDirectAdapter()); + Page page = sdk.salesOrders(WM).pull(SalesOrderQuery.builder() + .updatedAfter(java.time.Instant.parse("2026-10-25T00:00:00Z")) + .build()); + assertNotNull(page); + assertEquals(0, page.size()); + } + + @Test + void missingCapabilityThrowsUnsupported() { + ChannelSdk sdk = sdkWith(new FakeDirectAdapter()); + assertThrows(ChannelException.UnsupportedCapabilityException.class, + () -> sdk.products(WM).pull(apelet.common.ecommerce.model.ProductQuery.builder().build())); + } + + @Test + void unknownAccountFailsFast() { + ChannelSdk sdk = ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .register(new FakeDirectAdapter()) + .build(); + AccountKey other = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-unknown"); + assertThrows(IllegalStateException.class, () -> sdk.capabilities(other)); + } + + @Test + void duplicateAdapterRegistrationRejected() { + ChannelSdk.Builder builder = ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .register(new FakeDirectAdapter()); + assertThrows(IllegalStateException.class, () -> builder.register(new FakeDirectAdapter())); + } +}