diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java index 8637ce0..5045ea5 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java @@ -26,6 +26,16 @@ public interface PlatformAdapter { EnumSet capabilities(); /** + * 该适配器的默认接口基址。 + * + *

仅当账户未配置 {@code endpointBaseUrl} 时使用;返回 null 表示适配器不提供默认值, + * 此时调用方必须显式传入连接。默认 null,适配器按需覆盖。

+ */ + default String defaultEndpointBaseUrl() { + return null; + } + + /** * 按账户细化能力。 * *

直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖, diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java index 7222d16..4522b80 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java @@ -12,7 +12,8 @@ import java.util.Objects; * 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。 * *

凭证不落配置:本对象只保存 {@code credentialRef}(账户维度的标识), - * 真实密钥由调用方在每次调用时经 {@code ChannelConnection} 传入,SDK 不保存、不读取。

+ * 真实密钥由 {@code SecretProvider} 按引用解析;调用方也可以在每次调用时 + * 经 {@code ChannelConnection} 直接传入,SDK 不保存、不落盘。

*/ public final class ChannelAccount { @@ -31,9 +32,18 @@ public final class ChannelAccount { /** 市场 ID 列表;单市场平台可为空列表。 */ private final List marketplaceIds; - /** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;真实密钥经 ChannelConnection 传入。 */ + /** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;由 {@code SecretProvider} 解析。 */ private final String credentialRef; + /** + * 该账户的接口基址,如 {@code https://openapi.lingxing.com}。 + * + *

为 null 时由适配器按 provider 取内置默认地址(各适配器常量); + * 联调 / 私有化部署时可在此覆盖。配置后调用方不必再传 + * {@code ChannelConnection}。

+ */ + private final String endpointBaseUrl; + /** 市场时区 IANA ID,如 America/Los_Angeles。 */ private final String marketplaceZone; @@ -53,6 +63,7 @@ public final class ChannelAccount { this.region = b.region; this.marketplaceIds = Collections.unmodifiableList(new ArrayList(b.marketplaceIds)); this.credentialRef = Objects.requireNonNull(b.credentialRef, "credentialRef"); + this.endpointBaseUrl = trimToNull(b.endpointBaseUrl); this.marketplaceZone = Objects.requireNonNull(b.marketplaceZone, "marketplaceZone"); this.currency = Objects.requireNonNull(b.currency, "currency"); this.shipNode = b.shipNode; @@ -109,6 +120,15 @@ public final class ChannelAccount { return credentialRef; } + /** + * 该账户的接口基址;null 表示用适配器内置默认地址。 + * + *

有值时 {@code ChannelSdk} 的免连接重载会用它组装调用上下文。

+ */ + public String endpointBaseUrl() { + return endpointBaseUrl; + } + /** IANA 时区 ID,如 America/Los_Angeles */ public String marketplaceZone() { return marketplaceZone; @@ -150,6 +170,9 @@ public final class ChannelAccount { /** 凭证引用;必填。 */ private String credentialRef; + /** 接口基址;为 null 时用适配器内置默认地址。 */ + private String endpointBaseUrl; + /** 市场时区 IANA ID;必填。 */ private String marketplaceZone; @@ -198,6 +221,16 @@ public final class ChannelAccount { return this; } + /** + * 设置接口基址。 + * + *

不设置时由适配器按 provider 取内置默认地址;需要连 PR / 私有化环境时在这里覆盖。

+ */ + public Builder endpointBaseUrl(String endpointBaseUrl) { + this.endpointBaseUrl = endpointBaseUrl; + return this; + } + /** 设置市场时区 IANA ID。 */ public Builder marketplaceZone(String marketplaceZone) { this.marketplaceZone = marketplaceZone; @@ -232,4 +265,13 @@ public final class ChannelAccount { return new ChannelAccount(this); } } + + /** 空白归一为 null;不去空白以外的内容。 */ + private static String trimToNull(String v) { + if (v == null) { + return null; + } + String t = v.trim(); + return t.isEmpty() ? null : t; + } } diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java index 9e0b5cf..c5136a2 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java @@ -22,6 +22,8 @@ import common.ecommerce.channel.model.account.ChannelAccount; import common.ecommerce.channel.spi.ChannelAccountRepository; import common.ecommerce.channel.sdk.AdapterFactory.AdapterConfig; import common.ecommerce.shared.spi.IdempotencyStore; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.spi.SecretProvider; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -112,12 +114,21 @@ public final class ChannelSdk implements ProviderResolver { */ private final Supplier requestIdSupplier; + /** + * 凭据解析器;把账户的 {@code credentialRef} 换成真实密钥。 + * + *

未注入时为 {@code null},此时只能用带 {@code ChannelConnection} 的入口; + * 注入后可使用免连接重载({@code salesOrders(key)} 等)。

+ */ + private final SecretProvider secretProvider; + private ChannelSdk(Builder b) { this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters)); this.accountRepository = b.accountRepository; this.clock = b.clock; this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver; this.requestIdSupplier = b.requestIdSupplier; + this.secretProvider = b.secretProvider; this.idempotencyGuard = b.idempotencyStore == null ? null : new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock, IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, callObserver); @@ -157,6 +168,19 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 3P 销售订单视图(免连接)。 + * + *

连接由账户端点 + {@link SecretProvider} 自动组装;需要显式覆盖地址或密钥时 + * 用 {@link #salesOrders(AccountKey, ChannelConnection)}。

+ * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public SalesOrders salesOrders(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new SalesOrders(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + + /** * 3P 销售订单视图。 * *

能力检查发生在 {@code pull()} 调用时,不是取视图时。

@@ -167,6 +191,16 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 商品 / Listing 视图(免连接)。 + * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public Products products(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new Products(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + + /** * 商品 / Listing 视图。 * *

能力检查发生在 {@code pull()} 调用时,不是取视图时。

@@ -176,6 +210,12 @@ public final class ChannelSdk implements ProviderResolver { return new Products(resolve(key), account, newContext(account, connection), callObserver); } + /** 结算 / 账单交易明细视图(免连接)。 */ + public Settlements settlements(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new Settlements(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + /** 结算 / 账单交易明细视图。 */ public Settlements settlements(AccountKey key, ChannelConnection connection) { ChannelAccount account = requireAccount(key); @@ -183,6 +223,16 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 售后视图(免连接):拉取退款 / 退货 / 换货订单(只读)。 + * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public AfterSales afterSales(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new AfterSales(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + + /** * 售后视图:拉取退款 / 退货 / 换货订单(只读)。 * *

能力检查发生在 {@code pull()} 调用时;适配器未实现 {@code AfterSaleCapable} @@ -194,6 +244,16 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 履约 / 出库视图(免连接)。 + * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public Outbounds outbounds(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new Outbounds(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + + /** * 履约 / 出库视图。 * *

写操作:会改变平台数据。领星没有测试环境,验证阶段禁止调用。

@@ -204,6 +264,16 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 入库视图(免连接):平台仓入库货件(FBT / WFS / AWD)与 FBA 到货接收明细(只读)。 + * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public Inbounds inbounds(AccountKey key) { + ChannelAccount account = requireAccount(key); + return new Inbounds(resolve(key), account, newContext(account, connectionOf(key, account)), callObserver); + } + + /** * 入库视图:平台仓入库货件(FBT / WFS / AWD)与 FBA 到货接收明细(只读)。 * *

能力检查发生在 {@code shipments()} / {@code receipts()} 调用时; @@ -216,6 +286,16 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 聚合器的子店铺列表(免连接)。 + * + * @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址 + */ + public List subChannels(AccountKey key) { + ChannelAccount account = requireAccount(key); + return subChannels(key, connectionOf(key, account)); + } + + /** * 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。 * *

典型用途是首次接入:把 platformCode + externalStoreId 拉下来, @@ -326,6 +406,37 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 免连接重载用:按账户端点 + {@link SecretProvider} 组装连接。 + * + *

端点优先级:{@code account.endpointBaseUrl()} → 适配器默认地址。 + * 两者都没有时明确报错,不猜地址。

+ * + * @throws IllegalStateException 未注入 secretProvider、账户无端点且适配器无默认地址, + * 或解析器返回 null + */ + private ChannelConnection connectionOf(AccountKey key, ChannelAccount account) { + if (secretProvider == null) { + throw new IllegalStateException( + "ChannelSdk requires a secretProvider for connection-less calls; " + + "either inject secretProvider(...) or pass a ChannelConnection"); + } + String endpoint = account.endpointBaseUrl(); + if (endpoint == null || endpoint.trim().isEmpty()) { + endpoint = resolve(key).defaultEndpointBaseUrl(); + } + if (endpoint == null || endpoint.trim().isEmpty()) { + throw new IllegalStateException("no endpoint configured for " + key + + "; set ChannelAccount.endpointBaseUrl or use the ChannelConnection overload"); + } + ChannelSecret secret = secretProvider.get(account.credentialRef()); + if (secret == null) { + throw new IllegalStateException("secretProvider returned null for credentialRef=" + + account.credentialRef()); + } + return ChannelConnection.of(endpoint, secret); + } + + /** * 没有账户也要能埋点的调用({@code capabilities}):成功路径能拿到真实账户, * 账户缺失时用 {@link ChannelContext#ofKey} 记一条失败记录,而不是什么都没留。 */ @@ -388,6 +499,22 @@ public final class ChannelSdk implements ProviderResolver { /** 时钟,默认 UTC;测试注入固定时钟。 */ private Clock clock = Clock.systemUTC(); + /** 凭据解析器;注入后才能用免连接重载。 */ + private SecretProvider secretProvider; + + /** + * 注入凭据解析器。 + * + *

注入后可使用 {@code salesOrders(key)} 这类免连接入口:SDK 用 + * {@code ChannelAccount.endpointBaseUrl()}(为空则取适配器默认地址)和 + * 本解析器按 {@code credentialRef} 取到的密钥组装连接。 + * 密钥只在内存中出现,SDK 不保存、不落盘。

+ */ + public Builder secretProvider(SecretProvider secretProvider) { + this.secretProvider = secretProvider; + return this; + } + /** * 注入账户仓库。必需。 * diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/sync/SyncEngine.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/sync/SyncEngine.java index 168646f..4a8ec44 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/sync/SyncEngine.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/sync/SyncEngine.java @@ -4,26 +4,28 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.shared.sync.SyncResult; import common.ecommerce.shared.sync.SyncSpec; import common.ecommerce.channel.model.order.SalesOrder; -import common.ecommerce.channel.model.order.SalesOrderQuery; +import common.ecommerce.channel.model.product.ProductListing; import common.ecommerce.channel.spi.Sink; import common.ecommerce.shared.spi.SyncCursorStore; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.time.Instant; -import java.util.function.BiFunction; /** * 增量同步引擎。 * *
  * from = lastWatermark - overlapWindow
- * to   = now
- * loop 拉一页 → 经 Sink upsert → cursor = page.nextCursor
+ * to   = 本次批次终点(宿主传入,不取系统时间)
+ * loop 拉一页([from, to)) → 经 Sink upsert → cursor = page.nextCursor
  * 直到 cursor == null
  * 全部成功才推进水位线,失败不推进
  * 
* + *

查询窗口与水位线一致:拉取用 {@code [from, to)},推进也到 {@code to}。 + * 若查询不带上界、水位线却推到 {@code to},窗口内尚未入账的数据会被永久跳过。

+ * *

引擎不持有线程或定时器,由宿主调度触发。

*/ public final class SyncEngine { @@ -46,33 +48,49 @@ public final class SyncEngine { } /** - * 同步销售订单。 + * 拉一页的函数。 + * + *

{@code from} 与 {@code to} 构成左闭右开的时间窗;首页 {@code cursor} 为 null, + * 后续页原样传回上一页的 {@code nextCursor}。

+ */ + public interface PageFetcher { + Page fetch(Instant from, Instant to, String cursor); + } + + /** + * 增量同步销售订单。 * *

整批成功才推进水位线;任何一页抛异常都会直接冒出, * {@code SyncResult} 不会返回,水位线保持原值。引擎不私起线程/定时器。

* * @param spec 同步维度(provider + account + stream + overlap) - * @param to 本次增量终点;会作为新水位线写入,需非 null - * @param fetch 拉一页的函数:(from, cursor) → page;首页 {@code cursor} 为 null + * @param to 本次增量终点(不含);查询上界,同时作为新水位线 + * @param fetch 拉一页:(from, to, cursor) → page * @return 本次同步统计;成功路径恒为 {@code watermarkAdvanced=true} - * @throws IllegalStateException 账户/流还没有水位线(必须先跑一次全量建底) - * @throws RuntimeException {@code fetch} / {@code sink} 抛出的异常原样冒出 + * @throws IllegalArgumentException {@code to} 为 null 或不晚于起点 + * @throws IllegalStateException 账户/流还没有水位线(必须先跑 {@link #bootstrapSalesOrders}) + * @throws RuntimeException {@code fetch} / {@code sink} 抛出的异常原样冒出 */ - public SyncResult syncSalesOrders(SyncSpec spec, Instant to, - BiFunction> fetch) { + public SyncResult syncSalesOrders(SyncSpec spec, Instant to, PageFetcher fetch) { + if (to == null) { + throw new IllegalArgumentException("to must not be null"); + } Instant watermark = cursorStore.get(spec.provider().name(), spec.accountKey(), spec.stream()); Instant from = spec.from(watermark); if (from == null) { throw new IllegalStateException("no watermark for " + spec.accountKey() + "/" + spec.stream() + ", run full bootstrap first"); } + if (!to.isAfter(from)) { + throw new IllegalArgumentException("to (" + to + ") must be after from (" + from + ")"); + } int pages = 0; int items = 0; String cursor = null; - // 首页需要 from,后续页沿用同一 from(时间窗固定,靠游标翻页) + // 时间窗固定为 [from, to):翻页靠游标,窗口不变 while (true) { - Page page = fetch.apply(from, cursor); + Page page = fetch.fetch(from, to, cursor); if (page == null || page.size() == 0) { break; } @@ -89,4 +107,126 @@ public final class SyncEngine { LOG.debug("sync {} pages={} items={} from={} to={}", spec.stream(), pages, items, from, to); return SyncResult.of(pages, items, true); } + + /** + * 增量同步商品 / Listing。 + * + * @see #syncSalesOrders(SyncSpec, Instant, PageFetcher) + */ + public SyncResult syncProducts(SyncSpec spec, Instant to, PageFetcher fetch) { + if (to == null) { + throw new IllegalArgumentException("to must not be null"); + } + Instant watermark = cursorStore.get(spec.provider().name(), spec.accountKey(), spec.stream()); + Instant from = spec.from(watermark); + if (from == null) { + throw new IllegalStateException("no watermark for " + spec.accountKey() + + "/" + spec.stream() + ", run full bootstrap first"); + } + if (!to.isAfter(from)) { + throw new IllegalArgumentException("to (" + to + ") must be after from (" + from + ")"); + } + + int pages = 0; + int items = 0; + String cursor = null; + while (true) { + Page page = fetch.fetch(from, to, cursor); + if (page == null || page.size() == 0) { + break; + } + sink.upsertProducts(page); + pages++; + items += page.size(); + cursor = page.nextCursor(); + if (cursor == null) { + break; + } + } + + cursorStore.advance(spec.provider().name(), spec.accountKey(), spec.stream(), to); + LOG.debug("sync {} pages={} items={} from={} to={}", spec.stream(), pages, items, from, to); + return SyncResult.of(pages, items, true); + } + + /** + * 首次全量建底:拉完整个窗口并落库,然后把水位线播种到 {@code to}。 + * + *

增量同步要求先有水位线;首次接入时用本方法把历史数据补一遍。 + * 与增量一样,整批成功才写入水位线。

+ * + * @param spec 同步维度 + * @param from 全量起点(含) + * @param to 全量终点(不含);建成后的水位线 + * @param fetch 拉一页:(from, to, cursor) → page + * @return 本次同步统计 + * @throws IllegalArgumentException 任一时间点为空,或 {@code from} 不早于 {@code to} + * @throws IllegalArgumentException 该账户/流已有水位线(避免误把线上水位线回退) + */ + public SyncResult bootstrapSalesOrders(SyncSpec spec, Instant from, Instant to, + PageFetcher fetch) { + return bootstrap(spec, from, to, fetch, new SinkStep() { + @Override + public void upsert(Page page) { + sink.upsertSalesOrders(page); + } + }); + } + + /** + * 商品 / Listing 的首次全量建底。 + * + * @see #bootstrapSalesOrders(SyncSpec, Instant, Instant, PageFetcher) + */ + public SyncResult bootstrapProducts(SyncSpec spec, Instant from, Instant to, + PageFetcher fetch) { + return bootstrap(spec, from, to, fetch, new SinkStep() { + @Override + public void upsert(Page page) { + sink.upsertProducts(page); + } + }); + } + + /** 落库动作;只为复用 bootstrap 的分页与水位线逻辑。 */ + private interface SinkStep { + void upsert(Page page); + } + + /** 建底通用流程:分页拉取 → 落库 → 成功后播种水位线。 */ + private SyncResult bootstrap(SyncSpec spec, Instant from, Instant to, + PageFetcher fetch, SinkStep sinkStep) { + if (from == null || to == null) { + throw new IllegalArgumentException("from and to must not be null"); + } + if (!to.isAfter(from)) { + throw new IllegalArgumentException("to (" + to + ") must be after from (" + from + ")"); + } + Instant existing = cursorStore.get(spec.provider().name(), spec.accountKey(), spec.stream()); + if (existing != null) { + throw new IllegalArgumentException("watermark already exists for " + spec.accountKey() + + "/" + spec.stream() + " (" + existing + "); bootstrap would roll it back"); + } + + int pages = 0; + int items = 0; + String cursor = null; + while (true) { + Page page = fetch.fetch(from, to, cursor); + if (page == null || page.size() == 0) { + break; + } + sinkStep.upsert(page); + pages++; + items += page.size(); + cursor = page.nextCursor(); + if (cursor == null) { + break; + } + } + + cursorStore.advance(spec.provider().name(), spec.accountKey(), spec.stream(), to); + LOG.info("bootstrap {} pages={} items={} from={} to={}", spec.stream(), pages, items, from, to); + return SyncResult.of(pages, items, true); + } } diff --git a/channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java b/channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java index 2c5a4a2..51f19c2 100644 --- a/channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java +++ b/channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java @@ -16,6 +16,7 @@ import common.ecommerce.channel.sdk.ChannelContext; import common.ecommerce.channel.spi.ChannelAccountRepository; import org.junit.jupiter.api.Test; +import java.time.Instant; import java.util.Collections; import java.util.EnumSet; import java.util.Optional; @@ -58,6 +59,11 @@ class ChannelSdkTest { } @Override + public String defaultEndpointBaseUrl() { + return "https://api.example.com"; + } + + @Override public EnumSet capabilities() { return EnumSet.of(Capability.SALES_ORDER); } @@ -251,4 +257,42 @@ class ChannelSdkTest { assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, sdk.writes().execute(scope, () -> "SHIP-2", v -> v).outcome()); } + + // ---------------------------------------------------------------- 免连接重载 + + private static ChannelSdk sdkWithSecret() { + return ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .secretProvider(credentialRef -> + common.ecommerce.shared.spi.ChannelSecret.builder() + .appKey("ak").appSecret("sk").build()) + .register(new FakeDirectAdapter()) + .build(); + } + + @Test + void connectionlessSalesOrdersUsesAdapterDefaultEndpoint() { + Page page = sdkWithSecret().salesOrders(WM).pull( + SalesOrderQuery.builder() + .updatedAfter(Instant.parse("2026-10-01T00:00:00Z")) + .build()); + assertNotNull(page); + } + + @Test + void connectionlessWithoutSecretProviderFails() { + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> sdkWith(new FakeDirectAdapter()).salesOrders(WM)); + assertTrue(ex.getMessage().contains("secretProvider"), ex.getMessage()); + } + + @Test + void connectionlessWithNullSecretFails() { + ChannelSdk sdk = ChannelSdk.builder() + .accountRepository(new FixedAccounts(walmartAccount())) + .secretProvider(credentialRef -> null) + .register(new FakeDirectAdapter()) + .build(); + assertThrows(IllegalStateException.class, () -> sdk.salesOrders(WM)); + } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index aa50bff..97e5205 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java @@ -166,6 +166,16 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, return ChannelProvider.LINGXING; } + /** + * 领星只有一个开放平台域名,没有 PR / 生产之分。 + * + *

账户配置了 {@code endpointBaseUrl} 时以账户为准(私有化部署 / 代理场景)。

+ */ + @Override + public String defaultEndpointBaseUrl() { + return common.ecommerce.lingxing.LingxingConstants.PRODUCTION_BASE_URL; + } + @Override public Set platforms() { return EnumSet.of(Platform.AMAZON_SC, Platform.AMAZON_VC, Platform.WALMART_SC, Platform.TIKTOK, diff --git a/sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java b/sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java index 7bfb33d..7650e9d 100644 --- a/sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java +++ b/sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java @@ -3,16 +3,25 @@ package common.ecommerce.shared.spi; import java.util.Objects; /** - * 凭证内容。按 provider 需要取用,未使用的字段为 null。 + * 凭证内容与接入端点。按 provider 需要取用,未使用的字段为 null。 * - *

整体由调用方在每次调用时通过 {@code ChannelConnection} 传入,SDK 不落盘。 + *

地址与密钥放在一起:它们同属「一套接入身份」,换环境时一起换。

+ * + *

本对象由调用方经 {@code SecretProvider} 或 {@code ChannelConnection} 传入,SDK 不落盘。 * 日志只能用 {@link #fingerprint()},禁止打印原始值。

*/ public final class ChannelSecret { - /** 目标基址;由 ChannelConnection 构造时写回,供 TokenManager 的刷新回调使用。 */ + /** 主接口基址,如 {@code https://open-hwc.yqn.com};由调用方配置,SDK 不猜。 */ private final String endpointBaseUrl; + /** + * 辅助接口基址;仅少数仓把部分接口放在另一个主机时使用(如运去哪的轨迹查询)。 + * + *

为 null 时,需要它的能力会显式拒绝,不会退回主基址。

+ */ + private final String auxEndpointBaseUrl; + /** 应用标识。领星:appId(同时作为签名 AES 密钥,长度须为 16/24/32 字节)。 */ private final String appKey; @@ -30,6 +39,7 @@ public final class ChannelSecret { private ChannelSecret(Builder b) { this.endpointBaseUrl = b.endpointBaseUrl; + this.auxEndpointBaseUrl = b.auxEndpointBaseUrl; this.appKey = b.appKey; this.appSecret = b.appSecret; this.clientId = b.clientId; @@ -43,13 +53,17 @@ public final class ChannelSecret { } /** - * 调用方指定的目标基址。凭据与端点绑定在一起,避免 TokenManager 的 refresh 回调拿不到地址 - * (缓存命中时 Context 不参与调用)。整个对象只经调用方传入,SDK 不落盘。 + * 主接口基址。由调用方配置(账户 / KMS / 配置文件均可),SDK 不提供隐式默认值。 */ public String endpointBaseUrl() { return endpointBaseUrl; } + /** 辅助接口基址;未使用该字段的 provider 为 null。 */ + public String auxEndpointBaseUrl() { + return auxEndpointBaseUrl; + } + /** 应用标识;未使用该字段的 provider 为 null。 */ public String appKey() { return appKey; @@ -84,9 +98,12 @@ public final class ChannelSecret { /** 凭证构建器。所有字段都可空,由 provider 按需取用。 */ public static final class Builder { - /** 目标基址;ChannelConnection 构造时会写回。 */ + /** 主接口基址。 */ private String endpointBaseUrl; + /** 辅助接口基址。 */ + private String auxEndpointBaseUrl; + /** 应用标识。 */ private String appKey; @@ -102,12 +119,18 @@ public final class ChannelSecret { /** 长期刷新令牌。 */ private String refreshToken; - /** 端点与凭据一起传入;TokenManager 刷新时需要它。 */ + /** 主接口基址。 */ public Builder endpointBaseUrl(String endpointBaseUrl) { this.endpointBaseUrl = endpointBaseUrl; return this; } + /** 辅助接口基址;仅少数仓需要(如运去哪的轨迹查询)。 */ + public Builder auxEndpointBaseUrl(String auxEndpointBaseUrl) { + this.auxEndpointBaseUrl = auxEndpointBaseUrl; + return this; + } + /** 设置应用标识(领星 appId)。 */ public Builder appKey(String appKey) { this.appKey = appKey; diff --git a/sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java b/sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java index f825295..da5600f 100644 --- a/sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java +++ b/sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java @@ -116,6 +116,12 @@ public final class FakeDirectAdapter implements SalesOrderCapable, ProductCapabl return ChannelProvider.DIRECT; } + /** 免连接测试用默认端点;与测试里的固定地址保持一致。 */ + @Override + public String defaultEndpointBaseUrl() { + return "https://fake.direct.example.com"; + } + @Override public Set platforms() { return EnumSet.of(platform); diff --git a/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/FakeDirectAdapterTest.java b/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/FakeDirectAdapterTest.java index bd29dfb..d52c8d7 100644 --- a/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/FakeDirectAdapterTest.java +++ b/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/FakeDirectAdapterTest.java @@ -83,8 +83,8 @@ class FakeDirectAdapterTest { SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", stream, Duration.ofMinutes(15)); Instant to = Instant.parse("2026-10-29T00:00:00Z"); SyncResult result = new SyncEngine(cursors, sink).syncSalesOrders(spec, to, - (from, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() - .updatedAfter(from).updatedBefore(to).cursor(cursor).build())); + (from, end, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(from).updatedBefore(end).cursor(cursor).build())); assertEquals(3, result.pages()); assertEquals(5, result.items()); @@ -94,6 +94,85 @@ class FakeDirectAdapterTest { assertEquals(5, sink.salesOrders().size()); // 起点回退了重叠窗口 assertEquals(Instant.parse("2026-10-27T23:45:00Z"), adapter.orderQueries().get(0).updatedAfter()); + // 查询上界必须等于推进的水位线,否则窗口内未入账的数据会被永久跳过 + for (SalesOrderQuery q : adapter.orderQueries()) { + assertEquals(to, q.updatedBefore(), "每页查询上界都应等于 to"); + } + } + + @Test + void syncWithoutWatermarkFails() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(2).build(); + InMemoryCursorStore cursors = new InMemoryCursorStore(); // 未播种 + SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(15)); + + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> new SyncEngine(cursors, new InMemorySink()).syncSalesOrders(spec, + Instant.parse("2026-10-29T00:00:00Z"), + (from, end, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(from).updatedBefore(end).cursor(cursor).build()))); + assertTrue(ex.getMessage().contains("bootstrap"), ex.getMessage()); + } + + @Test + void syncRejectsToNotAfterFrom() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(2).build(); + InMemoryCursorStore cursors = new InMemoryCursorStore(); + // 水位线 10:00 + 15 分钟重叠回退 => 起点 09:45 + cursors.seed(ChannelProvider.DIRECT.name(), "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Instant.parse("2026-10-28T10:00:00Z")); + SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(15)); + + // to 早于回退后的起点,属于调用方算错,明确拒绝 + assertThrows(IllegalArgumentException.class, + () -> new SyncEngine(cursors, new InMemorySink()).syncSalesOrders(spec, + Instant.parse("2026-10-28T09:30:00Z"), + (from, end, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(from).updatedBefore(end).cursor(cursor).build()))); + } + + @Test + void bootstrapSeedsWatermarkAndSinksEverything() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build(); + InMemoryCursorStore cursors = new InMemoryCursorStore(); + InMemorySink sink = new InMemorySink(); + SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(15)); + + Instant from = Instant.parse("2026-10-01T00:00:00Z"); + Instant to = Instant.parse("2026-10-29T00:00:00Z"); + SyncResult result = new SyncEngine(cursors, sink).bootstrapSalesOrders(spec, from, to, + (start, end, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(start).updatedBefore(end).cursor(cursor).build())); + + assertEquals(3, result.pages()); + assertEquals(5, result.items()); + assertEquals(5, sink.salesOrders().size()); + assertEquals(to, cursors.watermark(ChannelProvider.DIRECT.name(), "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS)); + // 建底不受 overlap 影响,直接用传入的 from + assertEquals(from, adapter.orderQueries().get(0).updatedAfter()); + } + + @Test + void bootstrapRefusesToOverwriteExistingWatermark() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(3).build(); + InMemoryCursorStore cursors = new InMemoryCursorStore(); + cursors.seed(ChannelProvider.DIRECT.name(), "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Instant.parse("2026-10-28T00:00:00Z")); + SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", + SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(15)); + + assertThrows(IllegalArgumentException.class, + () -> new SyncEngine(cursors, new InMemorySink()).bootstrapSalesOrders(spec, + Instant.parse("2026-10-01T00:00:00Z"), Instant.parse("2026-10-29T00:00:00Z"), + (start, end, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(start).updatedBefore(end).cursor(cursor).build()))); + // 原水位线没被改动 + assertEquals(Instant.parse("2026-10-28T00:00:00Z"), cursors.watermark( + ChannelProvider.DIRECT.name(), "oms-test-001", SyncSpec.STREAM_SALES_ORDERS)); } @Test diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java index 30f73f1..5dce403 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java @@ -30,6 +30,10 @@ public final class InventorySnapshot { private final int packageCurrent; /** 商品名(仓方原值);无则为 null。 */ private final String productName; + /** 条码(仓方原值,UPC / EAN / GTIN 等);仓方未给为 null。 */ + private final String barcode; + /** 中文品名(仓方原值);仓方未给或只给了一种语言时为 null。 */ + private final String productNameCn; /** 待出库数量;仓方未给时为 -1。 */ private final int pendingOutbound; /** 预警数量;仓方未给时为 -1。 */ @@ -55,6 +59,8 @@ public final class InventorySnapshot { this.packageInTransit = b.packageInTransit; this.packageCurrent = b.packageCurrent; this.productName = b.productName; + this.barcode = b.barcode; + this.productNameCn = b.productNameCn; this.pendingOutbound = b.pendingOutbound; this.alertQuantity = b.alertQuantity; this.volumeCbm = b.volumeCbm; @@ -142,6 +148,16 @@ public final class InventorySnapshot { return productName; } + /** 条码(UPC / EAN / GTIN 等,仓方原值);仓方未给为 null。 */ + public String barcode() { + return barcode; + } + + /** 中文品名(仓方原值);仓方未给或只给了一种语言时为 null。 */ + public String productNameCn() { + return productNameCn; + } + /** 待出库数量;仓方未给时为 -1。 */ public int pendingOutbound() { return pendingOutbound; @@ -182,6 +198,8 @@ public final class InventorySnapshot { private int packageInTransit; private int packageCurrent; private String productName; + private String barcode; + private String productNameCn; /** 仓方未给时为 -1。 */ private int pendingOutbound = -1; /** 仓方未给时为 -1。 */ @@ -274,6 +292,18 @@ public final class InventorySnapshot { return this; } + /** 条码(UPC / EAN / GTIN 等,仓方原值)。 */ + public Builder barcode(String v) { + this.barcode = v; + return this; + } + + /** 中文品名(仓方原值)。 */ + public Builder productNameCn(String v) { + this.productNameCn = v; + return this; + } + /** 待出库数量;仓方未给时传 -1。 */ public Builder pendingOutbound(int v) { this.pendingOutbound = v; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java index 10b9ec1..8e11d15 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java @@ -21,6 +21,16 @@ public interface WarehouseAdapter { EnumSet capabilities(); /** + * 该适配器的默认主接口基址。 + * + *

仅当账户未配置 {@code endpointBaseUrl} 时使用;返回 null 表示适配器不提供默认值, + * 此时调用方必须显式传入 {@code WarehouseConnection}。默认 null,适配器按需覆盖。

+ */ + default String defaultEndpointBaseUrl() { + return null; + } + + /** * 按仓细化能力。一个 provider 账户下可能挂多个仓,能力可能不同。 * *

默认等价于 {@link #capabilities()};需要按仓细化的适配器覆盖它。

diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java index a022d47..1f56250 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java @@ -49,9 +49,15 @@ public final class WarehouseConnection { ? null : trimTrailingSlash(auxEndpointBaseUrl.trim()); this.zone = zone; Objects.requireNonNull(secret, "secret"); - // 端点写回凭据:需要换 token 的仓,TokenManager 的 refresh 回调只拿得到 ChannelSecret + // 地址优先取凭据里已带的(由 SecretProvider 提供);旧写法只给 URL 时补写进副本, + // 保证 TokenManager 的刷新回调(只拿得到 ChannelSecret)仍能拿到地址。 + String secretEndpoint = secret.endpointBaseUrl(); + String secretAuxEndpoint = secret.auxEndpointBaseUrl(); this.secret = ChannelSecret.builder() - .endpointBaseUrl(this.endpointBaseUrl) + .endpointBaseUrl(secretEndpoint == null || secretEndpoint.trim().isEmpty() + ? this.endpointBaseUrl : secretEndpoint) + .auxEndpointBaseUrl(secretAuxEndpoint == null || secretAuxEndpoint.trim().isEmpty() + ? this.auxEndpointBaseUrl : secretAuxEndpoint) .appKey(secret.appKey()) .appSecret(secret.appSecret()) .clientId(secret.clientId()) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java index 880782b..9ee92fe 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java @@ -4,6 +4,7 @@ import common.ecommerce.shared.audit.CallObserver; import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.spi.IdempotencyStore; +import common.ecommerce.shared.spi.SecretProvider; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.InboundCapable; @@ -81,12 +82,21 @@ public final class WarehouseSdk { /** 链路 ID 生成器。 */ private final Supplier requestIdSupplier; + /** + * 凭据解析器;把账户的 {@code accountId} 换成真实密钥。 + * + *

未注入时为 {@code null},此时只能用带 {@code WarehouseConnection} 的入口; + * 注入后可使用 {@link #warehouses(String)} 免连接重载。

+ */ + private final SecretProvider secretProvider; + private WarehouseSdk(Builder b) { this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters)); this.repository = b.repository; this.clock = b.clock; this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver; this.requestIdSupplier = b.requestIdSupplier; + this.secretProvider = b.secretProvider; this.idempotencyGuard = b.idempotencyStore == null ? null : new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock, IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, callObserver); @@ -97,6 +107,22 @@ public final class WarehouseSdk { } /** + * 取某个仓的接入视图(免连接)。 + * + *

密钥与地址一起由 {@link SecretProvider} 按 {@code accountId} 提供: + * 地址取 {@code ChannelSecret.endpointBaseUrl()},为空时退回适配器默认地址; + * 辅助基址取 {@code ChannelSecret.auxEndpointBaseUrl()}(如运去哪的轨迹主机)。

+ * + * @throws IllegalStateException 未注入 {@code secretProvider}、凭据无端点且适配器无默认地址, + * 或解析器返回 null + */ + public WarehouseOperations warehouses(String warehouseCode) { + WarehouseAccount account = requireAccount(warehouseCode); + WarehouseProvider provider = WarehouseProvider.valueOf(account.provider()); + return warehouses(warehouseCode, connectionOf(account, resolve(provider))); + } + + /** * 取某个仓的接入视图。 * * @param warehouseCode OMS 下发的仓编码 @@ -231,6 +257,38 @@ public final class WarehouseSdk { account.providerWarehouseId(), connection, id, clock); } + /** + * 免连接重载用:按 {@link SecretProvider} 返回的凭据组装连接。 + * + *

地址取自 {@code ChannelSecret.endpointBaseUrl()}(与密钥一起配置); + * 未配置时退回适配器内置默认地址。两者都没有时明确报错,不猜地址。

+ * + * @throws IllegalStateException 未注入 secretProvider、凭据里没有地址且适配器无默认地址, + * 或解析器返回 null + */ + private WarehouseConnection connectionOf(WarehouseAccount account, WarehouseAdapter adapter) { + if (secretProvider == null) { + throw new IllegalStateException( + "WarehouseSdk requires a secretProvider for connection-less calls; " + + "either inject secretProvider(...) or pass a WarehouseConnection"); + } + ChannelSecret secret = secretProvider.get(account.accountId()); + if (secret == null) { + throw new IllegalStateException("secretProvider returned null for accountId=" + + account.accountId()); + } + String endpoint = secret.endpointBaseUrl(); + if (endpoint == null || endpoint.trim().isEmpty()) { + endpoint = adapter.defaultEndpointBaseUrl(); + } + if (endpoint == null || endpoint.trim().isEmpty()) { + throw new IllegalStateException("no endpoint configured for warehouse " + + account.warehouseCode() + "; set ChannelSecret.endpointBaseUrl " + + "or use the WarehouseConnection overload"); + } + return WarehouseConnection.of(endpoint, secret.auxEndpointBaseUrl(), secret); + } + // ------------------------------------------------------------------ builder public static final class Builder { @@ -249,6 +307,22 @@ public final class WarehouseSdk { }; private Clock clock = Clock.systemUTC(); + /** 凭据解析器;注入后才能用免连接重载。 */ + private SecretProvider secretProvider; + + /** + * 注入凭据解析器。 + * + *

注入后可使用 {@code warehouses(warehouseCode)} 免连接入口:SDK 按 + * {@code accountId} 取到的 {@code ChannelSecret} 里同时含密钥与地址, + * 据此组装连接(地址为空时退回适配器默认地址)。 + * 密钥只在内存中出现,SDK 不保存、不落盘。

+ */ + public Builder secretProvider(SecretProvider secretProvider) { + this.secretProvider = secretProvider; + return this; + } + /** 注入仓主数据仓库。必需。 */ public Builder warehouseRepository(WarehouseRepository repository) { this.repository = repository; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java index bcfd50b..351d8b3 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java @@ -5,30 +5,47 @@ import java.util.Objects; /** * 仓接入账户配置。 * - *

不保存密钥:只存 {@link #credentialRef()},真实凭证由调用方 - * 在每次调用时经 {@code WarehouseConnection} 传入。

+ *

只有业务数据:哪家仓、仓方怎么称呼它。地址与密钥都不在这里—— + * 它们随 {@code SecretProvider} 返回的 {@code ChannelSecret} 一起提供, + * 账户表可以用纯业务表的方式管理、备份与导出。

*/ public final class WarehouseAccount { + /** + * 账户主键,同时是取密钥的键。 + * + *

由 OMS 自己定(自增 ID / 业务编号均可),一个账户一条。 + * {@code SecretProvider} 拿它去取对应的 {@code ChannelSecret}。 + * 同一账户下挂多个仓时,这些仓共用这一套密钥。

+ */ + private final String accountId; + + /** OMS 仓编码,业务主键;{@code sdk.warehouses()} 传的就是它。 */ private final String warehouseCode; + + /** 接入通道名({@code WarehouseProvider.name()})。 */ private final String provider; + + /** 仓方仓编码,如 {@code RF_NY_US};下发与回传时使用。 */ private final String providerWarehouseId; - private final String credentialRef; - private final String timeZone; private WarehouseAccount(Builder b) { + this.accountId = require(b.accountId, "accountId"); this.warehouseCode = require(b.warehouseCode, "warehouseCode"); this.provider = require(b.provider, "provider"); this.providerWarehouseId = b.providerWarehouseId; - this.credentialRef = require(b.credentialRef, "credentialRef"); - this.timeZone = require(b.timeZone, "timeZone"); } public static Builder builder() { return new Builder(); } - /** OMS 下发的仓编码,本域主键。 */ + /** 账户主键,同时作为 {@code SecretProvider} 的取密钥键。 */ + public String accountId() { + return accountId; + } + + /** OMS 下发的仓编码,本域业务主键。 */ public String warehouseCode() { return warehouseCode; } @@ -43,16 +60,6 @@ public final class WarehouseAccount { return providerWarehouseId; } - /** 凭证引用,不是凭证本体。 */ - public String credentialRef() { - return credentialRef; - } - - /** 仓所在地 IANA 时区,如 {@code America/Los_Angeles}。 */ - public String timeZone() { - return timeZone; - } - private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -61,11 +68,16 @@ public final class WarehouseAccount { } public static final class Builder { + private String accountId; private String warehouseCode; private String provider; private String providerWarehouseId; - private String credentialRef; - private String timeZone; + + /** 账户主键;不填时默认等于 {@code warehouseCode}。 */ + public Builder accountId(String v) { + this.accountId = v; + return this; + } public Builder warehouseCode(String v) { this.warehouseCode = v; @@ -82,17 +94,11 @@ public final class WarehouseAccount { return this; } - public Builder credentialRef(String v) { - this.credentialRef = v; - return this; - } - - public Builder timeZone(String v) { - this.timeZone = v; - return this; - } - + /** 构建账户;{@code accountId} 未设置时取 {@code warehouseCode}。 */ public WarehouseAccount build() { + if (accountId == null || accountId.trim().isEmpty()) { + accountId = warehouseCode; + } return new WarehouseAccount(this); } } diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index a08bf2a..2ae67a4 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -157,6 +157,17 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa } /** + * 不提供默认地址:生产域名尚未确定({@code EdayunConstants.PRODUCTION_BASE_URL} 仍是占位)。 + * + *

在账户上配置 {@code endpointBaseUrl} 后即可使用免连接重载; + * 未配置时会明确报错,不会悄悄连到测试环境。

+ */ + @Override + public String defaultEndpointBaseUrl() { + return null; + } + + /** * 已实现的能力。 * *

声明了就必须有实现,否则调用方看能力位会以为能用。

@@ -596,6 +607,16 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa */ @Override public Page query(WarehouseContext ctx, InventoryQuery query) { + if (query.updatedAfter() != null) { + throw new common.ecommerce.shared.error.ValidationException( + WarehouseException.builder() + .message("edayun inventory has no updatedAfter filter; full-pull and diff instead") + .operation("warehouse.inventory.query") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false)); + } int pageNum = EdayunInventoryMapper.pageNumber(query.cursor()); EdayunInventoryDtos.QueryInventoryRequest body = EdayunInventoryMapper.toRequest(query, ctx.providerWarehouseId(), pageNum); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java index 157f01b..1ebe2a2 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java @@ -82,6 +82,7 @@ public final class EdayunInventoryMapper { .inventoryType(0) .asOfUtc(asOf) .productName(blankToNull(row.skuName)) + .barcode(blankToNull(row.barcode)) // 这两个字段仓方会缺:真机 500 行里 430 行 safeStock 为 null。 // 统一模型的约定是「仓方未给时为 -1」,不能和真实的 0 混为一谈 .pendingOutbound(intOfUnknown(row.toDeliverStock)) diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java index 4181505..1d8b12f 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java @@ -37,8 +37,7 @@ class EdayunAdapterTest { .warehouseCode(WH) .provider(WarehouseProvider.EDAYUN.name()) .providerWarehouseId("EDY-WH-1") - .credentialRef("kms://test/edayun") - .timeZone("America/Los_Angeles") + .accountId("acc-edayun") .build(); } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java index 0f09551..5bd0244 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java @@ -83,8 +83,7 @@ class EdayunSdkSmokeTest { .warehouseCode(WH) .provider(WarehouseProvider.EDAYUN.name()) .providerWarehouseId("2") - .credentialRef("kms://test/edayun") - .timeZone("America/Los_Angeles") + .accountId("acc-edayun") .build()); // 直接注册适配器实例:把传输层换成假的,其余装配(token 缓存 / 锁 / 时钟)与 // 生产走同一套构造参数。工厂路径由 factoryAssemblesAdapter 单独验证。 @@ -191,8 +190,7 @@ class EdayunSdkSmokeTest { .warehouseCode(WH) .provider(WarehouseProvider.EDAYUN.name()) .providerWarehouseId("2") - .credentialRef("kms://test/edayun") - .timeZone("America/Los_Angeles") + .accountId("acc-edayun") .build()); WarehouseSdk built = WarehouseSdk.builder() .warehouseRepository(repo) diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 882d8d1..5cf6ee7 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -199,6 +199,12 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti return WarehouseProvider.HENGJIAN; } + /** 默认连生产环境;联调请在账户上配置 {@code endpointBaseUrl} 覆盖。 */ + @Override + public String defaultEndpointBaseUrl() { + return common.ecommerce.hengjian.HengjianConstants.PRODUCTION_BASE_URL; + } + @Override public EnumSet capabilities() { return EnumSet.of( diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java index 55e2fc2..cf4168a 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java @@ -144,7 +144,7 @@ public final class HengjianInventoryMapper { .onHand(intOfText(row.inventoryCurrent)) .inventoryType(row.inventoryType == null ? 0 : row.inventoryType) .asOfUtc(asOf) - .productName(trimToNull(row.lineName)) + // 刻意不映射 lineName:仓方口径是「项目名称」,不是商品名(已确认) .build(); } @@ -270,7 +270,7 @@ public final class HengjianInventoryMapper { .warehouseCode(warehouseCode == null ? fallbackWarehouseCode : warehouseCode) .providerSku(sku) .sellerSku(trimToNull(row.sellerSku)) - .productName(trimToNull(row.lineName)) + // 刻意不映射 lineName:仓方口径是「项目名称」,不是商品名(已确认) .inventoryType(row.inventoryType) .documentType(trimToNull(row.documentType)) .changeType(trimToNull(row.inventoryChangeType)) diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java index a729152..dc97dcb 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -34,8 +34,7 @@ class HengjianAdapterTest { .warehouseCode(WH) .provider(WarehouseProvider.HENGJIAN.name()) .providerWarehouseId("EFCA") - .credentialRef("kms://test/hengjian") - .timeZone("America/Los_Angeles") + .accountId("acc-hengjian") .build(); } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java index 41ac27e..12f7f99 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -492,8 +492,7 @@ class HengjianCreateOrderTest { .warehouseCode("HJ-EFCA") .provider(WarehouseProvider.HENGJIAN.name()) .providerWarehouseId("EFCA") - .credentialRef("kms://test") - .timeZone("America/Los_Angeles") + .accountId("acc-test") .build())) .clock(CLOCK) .register(new HengjianAdapterFactory()) diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java index 6cfe969..1ac8119 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java @@ -24,6 +24,7 @@ import java.util.List; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -302,7 +303,8 @@ class HengjianInventoryTest { assertEquals("EFCA", m.warehouseCode()); assertEquals("SKU-A", m.providerSku()); assertEquals("SELLER-A", m.sellerSku()); - assertEquals("项目A", m.productName()); + // lineName 是项目名称,不映射到商品名 + assertNull(m.productName()); assertEquals(Integer.valueOf(0), m.inventoryType()); assertEquals("销售出库", m.documentType()); assertEquals("出库", m.changeType()); diff --git a/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java index 4efe786..658deb8 100644 --- a/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java +++ b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java @@ -55,8 +55,7 @@ public final class FakeWarehouseAdapter implements OutboundCapable { .warehouseCode(warehouseCode) .provider(provider.name()) .providerWarehouseId("WH-" + warehouseCode) - .credentialRef("kms://test/fake-warehouse") - .timeZone("America/Los_Angeles") + .accountId("acc-" + warehouseCode) .build(); } @@ -65,6 +64,12 @@ public final class FakeWarehouseAdapter implements OutboundCapable { ChannelSecret.builder().appSecret("fake-token").build()); } + /** 免连接测试用默认端点。 */ + @Override + public String defaultEndpointBaseUrl() { + return "https://fake.warehouse.example.com"; + } + public FakeWarehouseAdapter chargeCancel(String fee) { this.cancelFee = fee; return this; diff --git a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java index 29544d8..bfd8c90 100644 --- a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java +++ b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java @@ -168,4 +168,74 @@ class WarehouseSdkTest { assertThrows(IllegalStateException.class, () -> sdk.warehouses("NOT-CONFIGURED", FakeWarehouseAdapter.connection())); } + + // ---------------------------------------------------------------- 免连接重载 + + private WarehouseSdk sdkWithSecret() { + InMemoryWarehouses repo = new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)); + common.ecommerce.shared.spi.SecretProvider secrets = + accountId -> common.ecommerce.shared.spi.ChannelSecret.builder() + .appSecret("fake-token").build(); + return WarehouseSdk.builder() + .warehouseRepository(repo) + .secretProvider(secrets) + .idempotencyStore(idempotency) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .build(); + } + + @Test + void connectionlessCallUsesAdapterDefaultEndpoint() { + WarehouseSdk withSecret = sdkWithSecret(); + + // 账户未配端点 → 走适配器默认地址;密钥由解析器按 accountId 取 + assertNotNull(withSecret.warehouses(WH)); + withSecret.warehouses(WH).outbound().create(cmd("OB-CC-1")); + } + + @Test + void connectionlessCallUsesSecretEndpointWhenConfigured() { + InMemoryWarehouses repo = new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)); + common.ecommerce.shared.spi.SecretProvider secrets = + accountId -> common.ecommerce.shared.spi.ChannelSecret.builder() + .appSecret("fake-token") + .endpointBaseUrl("https://custom.endpoint.example.com") + .build(); + + WarehouseSdk withSecret = WarehouseSdk.builder() + .warehouseRepository(repo) + .secretProvider(secrets) + .idempotencyStore(idempotency) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .build(); + + assertNotNull(withSecret.warehouses(WH).outbound()); + } + + @Test + void connectionlessCallWithoutSecretProviderFails() { + // setUp 里的 sdk 没注入 secretProvider + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> sdk.warehouses(WH)); + assertTrue(ex.getMessage().contains("secretProvider"), ex.getMessage()); + } + + @Test + void connectionlessCallWithNullSecretFails() { + InMemoryWarehouses repo = new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)); + WarehouseSdk withSecret = WarehouseSdk.builder() + .warehouseRepository(repo) + .secretProvider(accountId -> null) + .idempotencyStore(idempotency) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .build(); + + assertThrows(IllegalStateException.class, () -> withSecret.warehouses(WH)); + } } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java index 6185e7f..b233717 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java @@ -140,6 +140,12 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa return WarehouseProvider.XINCANG; } + /** 默认连生产环境;联调请在账户上配置 {@code endpointBaseUrl} 覆盖。 */ + @Override + public String defaultEndpointBaseUrl() { + return common.ecommerce.xincang.XincangConstants.PRODUCTION_BASE_URL; + } + @Override public EnumSet capabilities() { return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, @@ -662,6 +668,16 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa */ @Override public Page query(WarehouseContext ctx, InventoryQuery query) { + if (query.updatedAfter() != null) { + throw new common.ecommerce.shared.error.ValidationException( + WarehouseException.builder() + .message("xincang inventory has no updatedAfter filter; full-pull and diff instead") + .operation("warehouse.inventory.query") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false)); + } Map params = XincangInventoryMapper.toStockParams(query, ctx.providerWarehouseId()); String raw = executeGet(ctx, XincangConstants.PATH_STOCK_LIST, params, login(ctx), diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java index b3fed89..e0854da 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java @@ -102,6 +102,7 @@ public final class XincangInventoryMapper { .inventoryType(0) .asOfUtc(asOf) .productName(blankToNull(row.chnName)) + .productNameCn(blankToNull(row.chnName)) .pendingOutbound(intOf(row.waitSkuCount)) .alertQuantity(intOf(row.alarmCount)) .volumeCbm(decimalOf(row.volumeCm)) diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 02e5749..01b3699 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -133,6 +133,14 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return WarehouseProvider.YQN; } + /** + * 默认连生产环境;联调 / 私有化部署请在账户上配置 {@code endpointBaseUrl} 覆盖。 + */ + @Override + public String defaultEndpointBaseUrl() { + return common.ecommerce.yqn.YqnConstants.PRODUCTION_BASE_URL; + } + @Override public java.util.EnumSet capabilities() { return java.util.EnumSet.of( @@ -428,6 +436,16 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl */ @Override public Page query(WarehouseContext ctx, InventoryQuery query) { + if (query.updatedAfter() != null) { + throw new common.ecommerce.shared.error.ValidationException( + WarehouseException.builder() + .message("yqn inventory has no updatedAfter filter; full-pull and diff instead") + .operation("warehouse.inventory.query") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false)); + } Map> params = YqnInventoryMapper.toParams(query, ctx.providerWarehouseId()); rateLimiter.acquire(YqnConstants.PATH_INVENTORY_PAGE, YqnConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), YqnConstants.PATH_INVENTORY_PAGE, diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java index 7414bd4..439cad8 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java @@ -97,6 +97,7 @@ public final class YqnInventoryMapper { .packageReserved(intOf(row.inventoryPcsReserved)) .packageInTransit(intOf(row.inventoryPcsTransport)) .packageCurrent(intOf(row.inventoryPcsCurrent)) + // 刻意不映射 line_name:仓方口径是「项目名称」,不是商品名(已确认) // 没有更新时间时用调用方给的时刻兜底:快照必须带 asOfUtc 才能与逻辑库存对齐 .asOfUtc(updatedAt == null ? fallbackAsOf : updatedAt) .build();