Browse Source
修复空壳门面可被 build 出来的问题: - ChannelSdk.build() 强校验 accountRepository、clock、至少一个适配器, 缺项直接抛 IllegalStateException,不再返回不可用的空对象 - 同一 provider+platform 重复注册适配器时报错 - ProviderResolver:按 AccountKey 解析,无适配器时显式失败 - 能力视图 SalesOrders / Products:调用前做能力检查, 缺失抛 UnsupportedCapabilityException - CapabilityReport + AdapterCapabilityReport:逐项询问 supports(), 聚合器可给出子平台级精确结果 - 支持 register(AdapterFactory) 与 register(Adapter) 两种注册方式 - ChannelSdkTest 9 个用例覆盖 build 校验、路由、能力检查 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
8 changed files with 541 additions and 15 deletions
@ -0,0 +1,60 @@
@@ -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; |
||||
|
||||
/** |
||||
* 由适配器与账户推导出的能力报告。 |
||||
* |
||||
* <p>逐项询问 {@link PlatformAdapter#supports(ChannelAccount, Capability)}, |
||||
* 因此聚合器能按子平台给出精确结果,而直连适配器等价于 {@code capabilities()}。</p> |
||||
*/ |
||||
public final class AdapterCapabilityReport implements CapabilityReport { |
||||
|
||||
private final PlatformAdapter adapter; |
||||
private final ChannelAccount account; |
||||
private final EnumSet<Capability> 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<Capability> supported() { |
||||
return EnumSet.copyOf(supported); |
||||
} |
||||
|
||||
@Override |
||||
public EnumSet<Capability> unsupported() { |
||||
EnumSet<Capability> 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; |
||||
} |
||||
} |
||||
@ -0,0 +1,19 @@
@@ -0,0 +1,19 @@
|
||||
package apelet.common.ecommerce.capability; |
||||
|
||||
import apelet.common.ecommerce.model.Capability; |
||||
|
||||
import java.util.EnumSet; |
||||
|
||||
/** |
||||
* 能力报告:只读,不触发真实 API。 |
||||
* |
||||
* <p>调用方据此决定是否换账户、走直连或人工,SDK 不做推荐与兜底。</p> |
||||
*/ |
||||
public interface CapabilityReport { |
||||
|
||||
boolean supports(Capability capability); |
||||
|
||||
EnumSet<Capability> supported(); |
||||
|
||||
EnumSet<Capability> unsupported(); |
||||
} |
||||
@ -0,0 +1,39 @@
@@ -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<ProductListing> 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); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,41 @@
@@ -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<SalesOrder> 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); |
||||
} |
||||
} |
||||
} |
||||
@ -1,19 +1,169 @@
@@ -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 统一门面。 |
||||
* |
||||
* <p>业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入, |
||||
* SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。</p> |
||||
* |
||||
* <p>provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、 |
||||
* 不自动选路、不自动兜底;能力缺失时抛 |
||||
* {@code ChannelException.UnsupportedCapabilityException}。</p> |
||||
*/ |
||||
public final class ChannelSdk implements ProviderResolver { |
||||
|
||||
private final Map<String, PlatformAdapter> adapters; |
||||
private final ChannelAccountRepository accountRepository; |
||||
private final Clock clock; |
||||
|
||||
private ChannelSdk(Builder b) { |
||||
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, PlatformAdapter>(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<String, PlatformAdapter> adapters = new LinkedHashMap<String, PlatformAdapter>(); |
||||
private final List<AdapterFactory> factories = new ArrayList<AdapterFactory>(); |
||||
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<? extends AdapterFactory> 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; |
||||
} |
||||
|
||||
/** |
||||
* 构建门面。 |
||||
* |
||||
* <p>缺必需配置时立刻失败,而不是返回一个不可用的空对象。</p> |
||||
*/ |
||||
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()); |
||||
} |
||||
} |
||||
} |
||||
} |
||||
|
||||
@ -0,0 +1,14 @@
@@ -0,0 +1,14 @@
|
||||
package apelet.common.ecommerce.sdk; |
||||
|
||||
import apelet.common.ecommerce.capability.PlatformAdapter; |
||||
import apelet.common.ecommerce.model.AccountKey; |
||||
|
||||
/** |
||||
* 按 AccountKey 解析适配器。 |
||||
* |
||||
* <p>不自动选路、不自动兜底:provider 由调用方在 AccountKey 中显式指定。</p> |
||||
*/ |
||||
public interface ProviderResolver { |
||||
|
||||
PlatformAdapter resolve(AccountKey key); |
||||
} |
||||
@ -0,0 +1,183 @@
@@ -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<Platform> platforms() { |
||||
return EnumSet.of(Platform.WALMART_SC); |
||||
} |
||||
|
||||
@Override |
||||
public EnumSet<Capability> capabilities() { |
||||
return EnumSet.of(Capability.SALES_ORDER); |
||||
} |
||||
|
||||
@Override |
||||
public Page<SalesOrder> 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<ChannelAccount> 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.<ChannelAccount>empty(); |
||||
} |
||||
|
||||
@Override |
||||
public java.util.List<ChannelAccount> 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<SalesOrder> 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())); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue