未注入时为 {@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/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/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..0180dc5 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 credentialRef} 换成真实密钥。
+ *
+ * 未注入时为 {@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 credentialRef} 提供:
+ * 地址取 {@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.credentialRef());
+ if (secret == null) {
+ throw new IllegalStateException("secretProvider returned null for credentialRef="
+ + account.credentialRef());
+ }
+ 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 credentialRef} 取到的 {@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..1e34c68 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,23 +5,29 @@ import java.util.Objects;
/**
* 仓接入账户配置。
*
- * 不保存密钥:只存 {@link #credentialRef()},真实凭证由调用方
- * 在每次调用时经 {@code WarehouseConnection} 传入。
+ * 只有业务数据:哪家仓、仓方怎么称呼它。地址与密钥都不在这里——
+ * 它们随 {@code SecretProvider} 返回的 {@code ChannelSecret} 一起提供,
+ * 账户表可以用纯业务表的方式管理、备份与导出。
*/
public final class WarehouseAccount {
+ /** OMS 仓编码,本域主键。 */
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.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() {
@@ -43,16 +49,11 @@ public final class WarehouseAccount {
return providerWarehouseId;
}
- /** 凭证引用,不是凭证本体。 */
+ /** 凭证引用,不是凭证本体;由 {@code SecretProvider} 解析成密钥与端点。 */
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");
@@ -65,7 +66,6 @@ public final class WarehouseAccount {
private String provider;
private String providerWarehouseId;
private String credentialRef;
- private String timeZone;
public Builder warehouseCode(String v) {
this.warehouseCode = v;
@@ -87,11 +87,6 @@ public final class WarehouseAccount {
return this;
}
- public Builder timeZone(String v) {
- this.timeZone = v;
- return this;
- }
-
public WarehouseAccount build() {
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..6272a6f 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;
+ }
+
+ /**
* 已实现的能力。
*
* 声明了就必须有实现,否则调用方看能力位会以为能用。
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..36c6225 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
@@ -38,7 +38,6 @@ class EdayunAdapterTest {
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("EDY-WH-1")
.credentialRef("kms://test/edayun")
- .timeZone("America/Los_Angeles")
.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..b417d50 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
@@ -84,7 +84,6 @@ class EdayunSdkSmokeTest {
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("2")
.credentialRef("kms://test/edayun")
- .timeZone("America/Los_Angeles")
.build());
// 直接注册适配器实例:把传输层换成假的,其余装配(token 缓存 / 锁 / 时钟)与
// 生产走同一套构造参数。工厂路径由 factoryAssemblesAdapter 单独验证。
@@ -192,7 +191,6 @@ class EdayunSdkSmokeTest {
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("2")
.credentialRef("kms://test/edayun")
- .timeZone("America/Los_Angeles")
.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/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
index a729152..8ec870f 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
@@ -35,7 +35,6 @@ class HengjianAdapterTest {
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
.credentialRef("kms://test/hengjian")
- .timeZone("America/Los_Angeles")
.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..9acd8b4 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
@@ -493,7 +493,6 @@ class HengjianCreateOrderTest {
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
.credentialRef("kms://test")
- .timeZone("America/Los_Angeles")
.build()))
.clock(CLOCK)
.register(new HengjianAdapterFactory())
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..4eccde0 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
@@ -56,7 +56,6 @@ public final class FakeWarehouseAdapter implements OutboundCapable {
.provider(provider.name())
.providerWarehouseId("WH-" + warehouseCode)
.credentialRef("kms://test/fake-warehouse")
- .timeZone("America/Los_Angeles")
.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..40a43e3 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 =
+ credentialRef -> 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();
+
+ // 账户未配端点 → 走适配器默认地址;密钥由解析器按 credentialRef 取
+ 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 =
+ credentialRef -> 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(credentialRef -> 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..e386c46 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,
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..cb5c37d 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(
From a6bfba6fa910fcb9ccb72489a1009d9fa03e054f Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Thu, 19 Nov 2026 10:05:56 +0800
Subject: [PATCH 2/5] =?UTF-8?q?fix:=20=E5=90=8C=E6=AD=A5=E5=BC=95=E6=93=8E?=
=?UTF-8?q?=E6=9F=A5=E8=AF=A2=E7=AA=97=E5=8F=A3=E4=B8=8E=E6=B0=B4=E4=BD=8D?=
=?UTF-8?q?=E7=BA=BF=E5=AF=B9=E9=BD=90=EF=BC=8C=E5=BA=93=E5=AD=98=E5=A2=9E?=
=?UTF-8?q?=E9=87=8F=E5=AD=97=E6=AE=B5=E6=98=BE=E5=BC=8F=E6=8B=92=E7=BB=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
1. SyncEngine 的查询窗口补上上界
原来 fetch(from, cursor) 只传起点,水位线却推进到 to。窗口内尚未入账的
数据会被永久跳过。改为 PageFetcher(from, to, cursor),查询与推进都限定在
[from, to)。同时补 syncProducts。
2. 新增首次全量建底 API
增量同步要求先有水位线,但此前没有任何方法能建底,只能手工 advance。
新增 bootstrapSalesOrders / bootstrapProducts:分页拉全量 → 落库 →
成功后播种水位线;已有水位线时拒绝执行,避免把线上水位线回退。
3. 库存 updatedAfter 四家仓统一显式拒绝
恒健原本就拒绝;运去哪 / 易达云 / 信仓此前静默忽略该字段,调用方以为
是按增量拉、实际拿到全量,容易误用。现统一抛 ValidationException,
与各仓 inventorySyncStrategy()=FULL_PULL_DIFF 保持一致。
补 4 个同步测试:窗口上界、无水位线、to 早于起点、建底与重复建底拒绝。
Co-Authored-By: Claude
---
.../common/ecommerce/channel/sync/SyncEngine.java | 166 +++++++++++++++++++--
.../shared/testkit/FakeDirectAdapterTest.java | 83 ++++++++++-
.../ecommerce/edayun/adapter/EdayunAdapter.java | 10 ++
.../ecommerce/xincang/adapter/XincangAdapter.java | 10 ++
.../common/ecommerce/yqn/adapter/YqnAdapter.java | 10 ++
5 files changed, 264 insertions(+), 15 deletions(-)
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/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-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
index 6272a6f..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
@@ -607,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-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index e386c46..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
@@ -668,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-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
index cb5c37d..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
@@ -436,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,
From 799ac981c718b08ff859752d27b42bdbd4edc0d1 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Thu, 19 Nov 2026 11:38:44 +0800
Subject: [PATCH 3/5] =?UTF-8?q?refactor:=20WarehouseAccount=20=E7=94=A8=20?=
=?UTF-8?q?accountId=20=E5=8F=96=E4=BB=A3=20credentialRef?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
原 credentialRef 只是个"密钥引用名",和仓编码是两套标识,理解成本高。
改为:
- 新增 accountId 作账户主键,同时作为 SecretProvider 的取密钥键
- 删除 credentialRef
- accountId 不填时默认等于 warehouseCode,简单场景少写一个字段
对外调用不变:sdk.warehouses(warehouseCode) 仍传仓编码。
SecretProvider.get(accountId) 拿密钥。
同一仓未来挂多个 provider 时,warehouseCode 会有多条记录,但 accountId
仍然唯一,密钥 / 限流 / 水位线按它隔离。
Co-Authored-By: Claude
---
.../ecommerce/warehouse/sdk/WarehouseSdk.java | 12 +++---
.../ecommerce/warehouse/spi/WarehouseAccount.java | 45 ++++++++++++++--------
.../edayun/adapter/EdayunAdapterTest.java | 2 +-
.../ecommerce/edayun/sdk/EdayunSdkSmokeTest.java | 4 +-
.../hengjian/adapter/HengjianAdapterTest.java | 2 +-
.../hengjian/adapter/HengjianCreateOrderTest.java | 2 +-
.../warehouse/testkit/FakeWarehouseAdapter.java | 2 +-
.../ecommerce/warehouse/sdk/WarehouseSdkTest.java | 8 ++--
8 files changed, 44 insertions(+), 33 deletions(-)
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 0180dc5..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
@@ -83,7 +83,7 @@ public final class WarehouseSdk {
private final Supplier requestIdSupplier;
/**
- * 凭据解析器;把账户的 {@code credentialRef} 换成真实密钥。
+ * 凭据解析器;把账户的 {@code accountId} 换成真实密钥。
*
* 未注入时为 {@code null},此时只能用带 {@code WarehouseConnection} 的入口;
* 注入后可使用 {@link #warehouses(String)} 免连接重载。
@@ -109,7 +109,7 @@ public final class WarehouseSdk {
/**
* 取某个仓的接入视图(免连接)。
*
- * 密钥与地址一起由 {@link SecretProvider} 按 {@code credentialRef} 提供:
+ *
密钥与地址一起由 {@link SecretProvider} 按 {@code accountId} 提供:
* 地址取 {@code ChannelSecret.endpointBaseUrl()},为空时退回适配器默认地址;
* 辅助基址取 {@code ChannelSecret.auxEndpointBaseUrl()}(如运去哪的轨迹主机)。
*
@@ -272,10 +272,10 @@ public final class WarehouseSdk {
"WarehouseSdk requires a secretProvider for connection-less calls; "
+ "either inject secretProvider(...) or pass a WarehouseConnection");
}
- ChannelSecret secret = secretProvider.get(account.credentialRef());
+ ChannelSecret secret = secretProvider.get(account.accountId());
if (secret == null) {
- throw new IllegalStateException("secretProvider returned null for credentialRef="
- + account.credentialRef());
+ throw new IllegalStateException("secretProvider returned null for accountId="
+ + account.accountId());
}
String endpoint = secret.endpointBaseUrl();
if (endpoint == null || endpoint.trim().isEmpty()) {
@@ -314,7 +314,7 @@ public final class WarehouseSdk {
* 注入凭据解析器。
*
* 注入后可使用 {@code warehouses(warehouseCode)} 免连接入口:SDK 按
- * {@code credentialRef} 取到的 {@code ChannelSecret} 里同时含密钥与地址,
+ * {@code accountId} 取到的 {@code ChannelSecret} 里同时含密钥与地址,
* 据此组装连接(地址为空时退回适配器默认地址)。
* 密钥只在内存中出现,SDK 不保存、不落盘。
*/
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 1e34c68..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
@@ -11,7 +11,16 @@ import java.util.Objects;
*/
public final class WarehouseAccount {
- /** OMS 仓编码,本域主键。 */
+ /**
+ * 账户主键,同时是取密钥的键。
+ *
+ * 由 OMS 自己定(自增 ID / 业务编号均可),一个账户一条。
+ * {@code SecretProvider} 拿它去取对应的 {@code ChannelSecret}。
+ * 同一账户下挂多个仓时,这些仓共用这一套密钥。
+ */
+ private final String accountId;
+
+ /** OMS 仓编码,业务主键;{@code sdk.warehouses()} 传的就是它。 */
private final String warehouseCode;
/** 接入通道名({@code WarehouseProvider.name()})。 */
@@ -20,21 +29,23 @@ public final class WarehouseAccount {
/** 仓方仓编码,如 {@code RF_NY_US};下发与回传时使用。 */
private final String providerWarehouseId;
- /** 凭证引用,不是凭证本体。 */
- private final String credentialRef;
-
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");
}
public static Builder builder() {
return new Builder();
}
- /** OMS 下发的仓编码,本域主键。 */
+ /** 账户主键,同时作为 {@code SecretProvider} 的取密钥键。 */
+ public String accountId() {
+ return accountId;
+ }
+
+ /** OMS 下发的仓编码,本域业务主键。 */
public String warehouseCode() {
return warehouseCode;
}
@@ -49,11 +60,6 @@ public final class WarehouseAccount {
return providerWarehouseId;
}
- /** 凭证引用,不是凭证本体;由 {@code SecretProvider} 解析成密钥与端点。 */
- public String credentialRef() {
- return credentialRef;
- }
-
private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank");
@@ -62,10 +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;
+
+ /** 账户主键;不填时默认等于 {@code warehouseCode}。 */
+ public Builder accountId(String v) {
+ this.accountId = v;
+ return this;
+ }
public Builder warehouseCode(String v) {
this.warehouseCode = v;
@@ -82,12 +94,11 @@ public final class WarehouseAccount {
return this;
}
- public Builder credentialRef(String v) {
- this.credentialRef = 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/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java
index 36c6225..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,7 +37,7 @@ class EdayunAdapterTest {
.warehouseCode(WH)
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("EDY-WH-1")
- .credentialRef("kms://test/edayun")
+ .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 b417d50..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,7 +83,7 @@ class EdayunSdkSmokeTest {
.warehouseCode(WH)
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("2")
- .credentialRef("kms://test/edayun")
+ .accountId("acc-edayun")
.build());
// 直接注册适配器实例:把传输层换成假的,其余装配(token 缓存 / 锁 / 时钟)与
// 生产走同一套构造参数。工厂路径由 factoryAssemblesAdapter 单独验证。
@@ -190,7 +190,7 @@ class EdayunSdkSmokeTest {
.warehouseCode(WH)
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("2")
- .credentialRef("kms://test/edayun")
+ .accountId("acc-edayun")
.build());
WarehouseSdk built = WarehouseSdk.builder()
.warehouseRepository(repo)
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 8ec870f..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,7 +34,7 @@ class HengjianAdapterTest {
.warehouseCode(WH)
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
- .credentialRef("kms://test/hengjian")
+ .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 9acd8b4..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,7 +492,7 @@ class HengjianCreateOrderTest {
.warehouseCode("HJ-EFCA")
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
- .credentialRef("kms://test")
+ .accountId("acc-test")
.build()))
.clock(CLOCK)
.register(new HengjianAdapterFactory())
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 4eccde0..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,7 +55,7 @@ public final class FakeWarehouseAdapter implements OutboundCapable {
.warehouseCode(warehouseCode)
.provider(provider.name())
.providerWarehouseId("WH-" + warehouseCode)
- .credentialRef("kms://test/fake-warehouse")
+ .accountId("acc-" + warehouseCode)
.build();
}
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 40a43e3..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
@@ -175,7 +175,7 @@ class WarehouseSdkTest {
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
common.ecommerce.shared.spi.SecretProvider secrets =
- credentialRef -> common.ecommerce.shared.spi.ChannelSecret.builder()
+ accountId -> common.ecommerce.shared.spi.ChannelSecret.builder()
.appSecret("fake-token").build();
return WarehouseSdk.builder()
.warehouseRepository(repo)
@@ -190,7 +190,7 @@ class WarehouseSdkTest {
void connectionlessCallUsesAdapterDefaultEndpoint() {
WarehouseSdk withSecret = sdkWithSecret();
- // 账户未配端点 → 走适配器默认地址;密钥由解析器按 credentialRef 取
+ // 账户未配端点 → 走适配器默认地址;密钥由解析器按 accountId 取
assertNotNull(withSecret.warehouses(WH));
withSecret.warehouses(WH).outbound().create(cmd("OB-CC-1"));
}
@@ -200,7 +200,7 @@ class WarehouseSdkTest {
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
common.ecommerce.shared.spi.SecretProvider secrets =
- credentialRef -> common.ecommerce.shared.spi.ChannelSecret.builder()
+ accountId -> common.ecommerce.shared.spi.ChannelSecret.builder()
.appSecret("fake-token")
.endpointBaseUrl("https://custom.endpoint.example.com")
.build();
@@ -230,7 +230,7 @@ class WarehouseSdkTest {
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
WarehouseSdk withSecret = WarehouseSdk.builder()
.warehouseRepository(repo)
- .secretProvider(credentialRef -> null)
+ .secretProvider(accountId -> null)
.idempotencyStore(idempotency)
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
From 17097a764f854f1ed238506bc4094db45dee7728 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Thu, 19 Nov 2026 15:43:53 +0800
Subject: [PATCH 4/5] =?UTF-8?q?feat(inventory):=20=E5=BA=93=E5=AD=98?=
=?UTF-8?q?=E5=BF=AB=E7=85=A7=E8=A1=A5=20barcode=20/=20productNameCn?=
=?UTF-8?q?=EF=BC=8C=E8=BF=90=E5=8E=BB=E5=93=AA=E8=A1=A5=E5=93=81=E5=90=8D?=
=?UTF-8?q?=E6=98=A0=E5=B0=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
实际核对四家仓的库存响应后补齐:
1. InventorySnapshot 新增两个字段
- barcode:条码(UPC/EAN/GTIN),仓方原值
- productNameCn:中文品名,仓方原值
两者都可能为 null,各仓支持度不同。
2. 各仓映射补齐
- 易达云:row.barcode → barcode(原本丢弃)
- 信仓:chn_name → productName + productNameCn(原本只进 productName)
- 运去哪:line_name → productName(原本拿到了却没写进快照,一直是 null)
- 恒健:lineName 已映射到 productName,无变化
productNameCn 只填明确是中文的字段(信仓 chn_name);运去哪 / 恒健的
line_name / lineName 语言由仓方决定,不猜,只填 productName。
Co-Authored-By: Claude
---
.../warehouse/model/InventorySnapshot.java | 30 ++++++++++++++++++++++
.../edayun/adapter/EdayunInventoryMapper.java | 1 +
.../xincang/adapter/XincangInventoryMapper.java | 1 +
.../ecommerce/yqn/adapter/YqnInventoryMapper.java | 2 ++
4 files changed, 34 insertions(+)
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-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-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/YqnInventoryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java
index 7414bd4..2cee865 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,8 @@ public final class YqnInventoryMapper {
.packageReserved(intOf(row.inventoryPcsReserved))
.packageInTransit(intOf(row.inventoryPcsTransport))
.packageCurrent(intOf(row.inventoryPcsCurrent))
+ // line_name 是仓方返回的行项目名;语言由仓方决定,只填 productName,不猜中文
+ .productName(hasText(row.lineName) ? row.lineName.trim() : null)
// 没有更新时间时用调用方给的时刻兜底:快照必须带 asOfUtc 才能与逻辑库存对齐
.asOfUtc(updatedAt == null ? fallbackAsOf : updatedAt)
.build();
From cbc02361d793317ff2ea05d8ab1500486a84858d Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Thu, 19 Nov 2026 15:57:38 +0800
Subject: [PATCH 5/5] =?UTF-8?q?fix(inventory):=20line=5Fname=20=E6=98=AF?=
=?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=90=8D=E7=A7=B0=EF=BC=8C=E4=B8=8D=E6=98=A0?=
=?UTF-8?q?=E5=B0=84=E5=88=B0=E5=95=86=E5=93=81=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
确认运去哪与恒健库存响应里的 line_name / lineName 是「项目名称」
(用于仓方分账 / 路由),不是商品名。
- 运去哪:撤掉上一提交里 line_name → productName 的映射
- 恒健:撤掉 lineName → productName(快照 + 变动流水两处)
- 测试:恒健 movementsMapAllFields 改为断言 productName 为 null
结果:这两家的 InventorySnapshot.productName 恒为 null,只在响应里
能拿到项目名,但不属于商品信息。
Co-Authored-By: Claude
---
.../common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java | 4 ++--
.../java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java | 4 +++-
.../main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java | 3 +--
3 files changed, 6 insertions(+), 5 deletions(-)
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/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-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java
index 2cee865..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,8 +97,7 @@ public final class YqnInventoryMapper {
.packageReserved(intOf(row.inventoryPcsReserved))
.packageInTransit(intOf(row.inventoryPcsTransport))
.packageCurrent(intOf(row.inventoryPcsCurrent))
- // line_name 是仓方返回的行项目名;语言由仓方决定,只填 productName,不猜中文
- .productName(hasText(row.lineName) ? row.lineName.trim() : null)
+ // 刻意不映射 line_name:仓方口径是「项目名称」,不是商品名(已确认)
// 没有更新时间时用调用方给的时刻兜底:快照必须带 asOfUtc 才能与逻辑库存对齐
.asOfUtc(updatedAt == null ? fallbackAsOf : updatedAt)
.build();