diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java index 3d30508..baa6501 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java @@ -15,7 +15,10 @@ import java.util.Objects; */ public final class ChannelConnection { + /** 目标基址,如 {@code https://openapi.lingxing.com};末尾斜杠会被去掉。 */ private final String endpointBaseUrl; + + /** 凭据;端点会被写回其中,供 token 刷新回调使用。 */ private final ChannelSecret secret; private ChannelConnection(String endpointBaseUrl, ChannelSecret secret) { diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 3429374..8599d67 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -29,23 +29,60 @@ import java.util.Objects; import java.util.UUID; /** - * 渠道 SDK 统一门面。 + * 渠道 SDK 统一门面。业务层只依赖本类。 * - *
业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入, - * SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。
+ *provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、 - * 不自动选路、不自动兜底;能力缺失时抛 - * {@code ChannelException.UnsupportedCapabilityException}。
+ *连接信息由调用方每次传入,见 {@link ChannelConnection}:SDK 不保存端点、 - * 不读配置、不读环境变量。门面只负责按 {@link AccountKey} 找账户与适配器。
+ *+ * AccountKey ──→ 账户仓库找 ChannelAccount ──┐ + * ├──→ ChannelContext ──→ 适配器方法 + * ChannelConnection ────────────────────────┘ + *+ * + *
SDK 不访问数据库 / Redis / MQ,也不持有线程或定时器。
*/ public final class ChannelSdk implements ProviderResolver { + /** + * 已注册的适配器。 + * + *键是 {@code "PROVIDER|PLATFORM"},如 {@code "LINGXING|WALMART_SC"}。 + * 同一组合只能有一个适配器。
+ */ private final Map生产用默认 {@link Clock#systemUTC()} 即可;测试注入固定时钟, + * 让「不传 updatedBefore 时终点取现在」这类逻辑可重复断言。
+ */ private final Clock clock; + + /** + * 写操作幂等守卫。 + * + *只有在 {@code Builder.idempotencyStore(...)} 注入后才有值; + * 否则为 {@code null},{@link #writes()} 直接抛异常。
+ */ private final IdempotencyGuard idempotencyGuard; private ChannelSdk(Builder b) { @@ -63,19 +100,35 @@ public final class ChannelSdk implements ProviderResolver { // ------------------------------------------------------------------ 门面方法 - /** 能力矩阵,只读,不触发任何真实 API。 */ + /** + * 能力矩阵:这个账户支持哪些能力。 + * + *只读,不触发任何真实 API。聚合器(如领星)会按子平台细化, + * 例如领星下 eBay 只有订单、沃尔玛有订单和商品。
+ * + * @param key 账户标识;账户未配置时抛 {@link IllegalStateException} + * @throws IllegalStateException 账户未配置,或该 provider+platform 没有适配器 + */ public CapabilityReport capabilities(AccountKey key) { ChannelAccount account = requireAccount(key); return new AdapterCapabilityReport(resolve(key), account); } - /** 3P 销售订单视图。 */ + /** + * 3P 销售订单视图。 + * + *能力检查发生在 {@code pull()} 调用时,不是取视图时。
+ */ public SalesOrders salesOrders(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new SalesOrders(resolve(key), account, newContext(account, connection)); } - /** 商品 / Listing 视图。 */ + /** + * 商品 / Listing 视图。 + * + *能力检查发生在 {@code pull()} 调用时,不是取视图时。
+ */ public Products products(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new Products(resolve(key), account, newContext(account, connection)); @@ -87,7 +140,11 @@ public final class ChannelSdk implements ProviderResolver { return new Settlements(resolve(key), account, newContext(account, connection)); } - /** 履约 / 出库视图。 */ + /** + * 履约 / 出库视图。 + * + *写操作:会改变平台数据。领星没有测试环境,验证阶段禁止调用。
+ */ public Outbounds outbounds(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); return new Outbounds(resolve(key), account, newContext(account, connection)); @@ -96,9 +153,10 @@ public final class ChannelSdk implements ProviderResolver { /** * 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。 * - *调用方拿到 {@code platformCode + externalStoreId} 后,用来构造 - * {@link ChannelAccount},业务调用仍走 {@link AccountKey}。 - * 非聚合器适配器会抛 {@code UnsupportedCapabilityException}。
+ *典型用途是首次接入:把 platformCode + externalStoreId 拉下来, + * 落成 {@link ChannelAccount} 配置。日常业务调用不需要它。
+ * + * @throws IllegalStateException 该 provider 的适配器不是聚合器(未实现 AggregatorCapable) */ public List最少配置:{@code accountRepository(...)} + 至少一个 {@code register(...)}。
+ */ public static final class Builder { + /** 适配器注册表,键为 provider|platform。 */ private final MapSDK 用它把 {@link AccountKey} 解析成 {@link ChannelAccount}; + * 没注入时 {@link #build()} 直接失败。
+ */ public Builder accountRepository(ChannelAccountRepository accountRepository) { this.accountRepository = accountRepository; return this; } - /** 注入时钟;测试可给固定时间。 */ + /** + * 注入时钟,默认 {@link Clock#systemUTC()}。 + * + *作用:查询未传 {@code updatedBefore} 时的终点时间,以及幂等记录的时间戳。 + * 生产一般不用传;测试传 {@code Clock.fixed(...)} 让断言可重复。
+ */ public Builder clock(Clock clock) { this.clock = clock; return this; } - /** 注入幂等存储;不注入时调用 {@link ChannelSdk#writes()} 会失败。 */ + /** + * 注入幂等存储。只有写操作需要。 + * + *不注入时 {@link ChannelSdk#writes()} 直接抛异常; + * 只做查询的场景可以不注入。
+ */ public Builder idempotencyStore(IdempotencyStore idempotencyStore) { this.idempotencyStore = idempotencyStore; return this; @@ -184,12 +279,19 @@ public final class ChannelSdk implements ProviderResolver { return this; } - /** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */ + /** + * 注册适配器工厂。 + * + *生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)}, + * 适配器需要的基础设施(传输层、编解码、token 存储)由工厂自己装配, + * 宿主不用关心构造参数。
+ */ 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) { @@ -199,7 +301,12 @@ public final class ChannelSdk implements ProviderResolver { return this; } - /** 直接注册适配器实例,主要用于测试替身。 */ + /** + * 直接注册适配器实例。 + * + *主要用于测试替身、或需要替换传输层的场景。 + * 生产优先用 {@link #register(AdapterFactory)}。
+ */ public Builder register(PlatformAdapter adapter) { Objects.requireNonNull(adapter, "adapter"); for (Platform p : adapter.platforms()) { @@ -212,6 +319,9 @@ public final class ChannelSdk implements ProviderResolver { * 构建门面。 * *缺必需配置时立刻失败,而不是返回一个不可用的空对象。
+ * + * @throws IllegalStateException 缺 accountRepository、缺时钟、 + * 一个适配器都没注册、或同一 provider+platform 注册两次 */ public ChannelSdk build() { if (accountRepository == null) { @@ -230,6 +340,7 @@ public final class ChannelSdk implements ProviderResolver { return new ChannelSdk(this); } + /** 注册单个适配器,键为 provider|platform;重复注册不同实例直接失败。 */ private void put(String key, PlatformAdapter adapter) { PlatformAdapter previous = adapters.put(key, adapter); if (previous != null && previous != adapter) { diff --git a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java index b1c9d2b..87bbde5 100644 --- a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java +++ b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java @@ -4,14 +4,28 @@ import java.util.Objects; /** * 凭证内容。按 provider 需要取用,未使用的字段为 null。 + * + *整体由调用方在每次调用时通过 {@code ChannelConnection} 传入,SDK 不落盘。 + * 日志只能用 {@link #fingerprint()},禁止打印原始值。
*/ public final class ChannelSecret { + /** 目标基址;由 ChannelConnection 构造时写回,供 TokenManager 的刷新回调使用。 */ private final String endpointBaseUrl; + + /** 应用标识。领星:appId(同时作为签名 AES 密钥,长度须为 16/24/32 字节)。 */ private final String appKey; + + /** 应用密钥。领星:appSecret;用于换 token 与签名。 */ private final String appSecret; + + /** OAuth 客户端 ID。亚马逊 LWA、沃尔玛使用。 */ private final String clientId; + + /** OAuth 客户端密钥。亚马逊 LWA、沃尔玛使用。 */ private final String clientSecret; + + /** 长期刷新令牌。亚马逊 LWA、TikTok 使用。 */ private final String refreshToken; private ChannelSecret(Builder b) { diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java new file mode 100644 index 0000000..8567e14 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/ProductCallExampleTest.java @@ -0,0 +1,182 @@ +package common.ecommerce.lingxing; + +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.lingxing.adapter.LingxingAdapter; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelConnection; +import common.ecommerce.sdk.ChannelSdk; +import common.ecommerce.spi.ChannelSecret; +import common.ecommerce.testkit.InMemoryAccounts; +import common.ecommerce.testkit.InMemoryLockProvider; +import common.ecommerce.testkit.InMemoryTokenStore; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * 从 ChannelSdk 拉商品的完整示例。 + * + *这是用法文档,不是契约测试。传输层返回一页固定的领星 Listing 响应, + * 目的是让你看清:三段配置分别是什么、拼出来的请求长什么样、结果如何映射成统一模型。
+ */ +class ProductCallExampleTest { + + /** 领星生产域名。SDK 不保存它,每次调用通过 ChannelConnection 传入。 */ + private static final String ENDPOINT = "https://openapi.lingxing.com"; + + // ==================== 第 1 段:账户 ==================== + + /** 你自己的店铺 ID,业务归属维度。 */ + private static final String OMS_STORE_ID = "oms-wm-001"; + + /** 领星侧的店铺 ID(store_id)。 */ + private static final String LINGXING_STORE_ID = "1108413237731"; + + /** 领星平台码:10008 = Walmart,10001 = Amazon SC。 */ + private static final int PLATFORM_CODE = 10008; + + /** + * 领星 AppID。同时作为签名用的 AES 密钥,长度必须是 16/24/32 字节, + * 否则 LingxingSigner 会直接拒绝。 + */ + private static final String APP_KEY = "test-app-id-1234"; + + /** 领星 AppSecret。 */ + private static final String APP_SECRET = "test-app-secret"; + + /** 账户:告诉 SDK「这是哪个店铺」,SDK 用它校验归属、拼请求参数。 */ + private static ChannelAccount account() { + return ChannelAccount.builder() + // provider + platform + omsStoreId:三个一起决定用哪个适配器 + .key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, OMS_STORE_ID)) + // 领星 store_id,会拼进请求体的 store_ids + .externalStoreId(LINGXING_STORE_ID) + // 领星 platform_code,会拼进请求体的 platform_code + .platformCode(PLATFORM_CODE) + // 密钥引用;本 SDK 目前不使用(密钥从 ChannelConnection 传) + .credentialRef("kms://test/lingxing") + // 市场时区,必须能被 ZoneId.of 解析;影响返回时间的当地视图 + .marketplaceZone("America/Los_Angeles") + // 店铺币种 + .currency("USD") + .build(); + } + + // ==================== 第 2 段:连接 ==================== + + /** 连接:告诉 SDK「这次连哪里、用谁的身份」。每次调用都可以不同(换环境、换 app)。 */ + private static ChannelConnection connection() { + return ChannelConnection.of(ENDPOINT, ChannelSecret.builder() + .appKey(APP_KEY) // 领星 AppID + .appSecret(APP_SECRET) // 领星 AppSecret + .build()); + } + + // ==================== 第 3 段:构建 SDK ==================== + + /** 构建 SDK:账户仓库 + 适配器。写操作才需要幂等存储。 */ + private static ChannelSdk buildSdk(HttpTransport transport) { + InMemoryAccounts accounts = new InMemoryAccounts().put(account()); + + // 生产写法是 .register(new LingxingAdapterFactory(tokenStore, lockProvider, clock)), + // 工厂内部会 new OkHttpTransport;这里为了接管网络层,直接注册适配器实例。 + LingxingAdapter adapter = new LingxingAdapter(transport, + new common.ecommerce.http.JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), Clock.systemUTC()); + + return ChannelSdk.builder() + .accountRepository(accounts) // 必需:按 AccountKey 找账户 + .register(adapter) // 必需:至少一个适配器 + .build(); + } + + // ==================== 调用 ==================== + + @Test + void pullProductsThroughSdk() { + FixedResponseTransport transport = new FixedResponseTransport(); + ChannelSdk sdk = buildSdk(transport); + + // 每次调用都传 AccountKey + ChannelConnection + AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, OMS_STORE_ID); + + Page