Browse Source

refactor: 连接配置收敛到 SecretProvider,调用点只传身份

调用方不再每次构造 ChannelConnection 传地址和密钥,改为:
- 账户只保留业务字段(warehouseCode / provider / providerWarehouseId / credentialRef)
- 密钥与地址由 SecretProvider 按 credentialRef 统一提供
- 门面新增免连接重载:sdk.warehouses(code)、sdk.salesOrders(key) 等

主要改动:
- ChannelSecret 承接 endpointBaseUrl / auxEndpointBaseUrl,与密钥一起配置
- WarehouseAccount 删除 timeZone / endpointBaseUrl / auxEndpointBaseUrl
- ChannelAccount 增加 endpointBaseUrl
- PlatformAdapter / WarehouseAdapter 新增 defaultEndpointBaseUrl(),适配器提供内置默认地址
  (运去哪 / 信仓 / 恒健 / 领星取生产地址;易达云生产地址未定,返回 null)
- WarehouseConnection 不再无条件覆盖凭据里的地址,凭据已有地址时优先采用
- 两个门面的 Builder 新增 secretProvider(...),未注入时仍可用带连接的老入口
- 旧签名(带 connection)全部保留,向后兼容

适配器内部未改动:它们只消费 ctx.secret() / ctx.endpointBaseUrl(),
来源由调用方传入改为门面装配。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 20 hours ago
parent
commit
dc4db1c208
  1. 10
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java
  2. 46
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java
  3. 127
      channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java
  4. 44
      channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java
  5. 10
      lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
  6. 37
      sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java
  7. 6
      sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java
  8. 10
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java
  9. 10
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java
  10. 74
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java
  11. 27
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java
  12. 11
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  13. 1
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java
  14. 2
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java
  15. 6
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  16. 1
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  17. 1
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java
  18. 7
      warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java
  19. 70
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java
  20. 6
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  21. 8
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

10
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/PlatformAdapter.java

@ -26,6 +26,16 @@ public interface PlatformAdapter { @@ -26,6 +26,16 @@ public interface PlatformAdapter {
EnumSet<Capability> capabilities();
/**
* 该适配器的默认接口基址。
*
* <p>仅当账户未配置 {@code endpointBaseUrl} 时使用;返回 null 表示适配器不提供默认值,
* 此时调用方必须显式传入连接。默认 null,适配器按需覆盖。</p>
*/
default String defaultEndpointBaseUrl() {
return null;
}
/**
* 按账户细化能力。
*
* <p>直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖,

46
channel-sdk-core/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java

@ -12,7 +12,8 @@ import java.util.Objects; @@ -12,7 +12,8 @@ import java.util.Objects;
* 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。
*
* <p>凭证不落配置:本对象只保存 {@code credentialRef}(账户维度的标识),
* 真实密钥由调用方在每次调用时经 {@code ChannelConnection} 传入,SDK 不保存、不读取。</p>
* 真实密钥由 {@code SecretProvider} 按引用解析;调用方也可以在每次调用时
* 经 {@code ChannelConnection} 直接传入,SDK 不保存、不落盘。</p>
*/
public final class ChannelAccount {
@ -31,9 +32,18 @@ public final class ChannelAccount { @@ -31,9 +32,18 @@ public final class ChannelAccount {
/** 市场 ID 列表;单市场平台可为空列表。 */
private final List<String> marketplaceIds;
/** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;真实密钥经 ChannelConnection 传入。 */
/** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;由 {@code SecretProvider} 解析。 */
private final String credentialRef;
/**
* 该账户的接口基址,如 {@code https://openapi.lingxing.com}。
*
* <p>为 null 时由适配器按 provider 取内置默认地址(各适配器常量);
* 联调 / 私有化部署时可在此覆盖。配置后调用方不必再传
* {@code ChannelConnection}。</p>
*/
private final String endpointBaseUrl;
/** 市场时区 IANA ID,如 America/Los_Angeles。 */
private final String marketplaceZone;
@ -53,6 +63,7 @@ public final class ChannelAccount { @@ -53,6 +63,7 @@ public final class ChannelAccount {
this.region = b.region;
this.marketplaceIds = Collections.unmodifiableList(new ArrayList<String>(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 { @@ -109,6 +120,15 @@ public final class ChannelAccount {
return credentialRef;
}
/**
* 该账户的接口基址;null 表示用适配器内置默认地址。
*
* <p>有值时 {@code ChannelSdk} 的免连接重载会用它组装调用上下文。</p>
*/
public String endpointBaseUrl() {
return endpointBaseUrl;
}
/** IANA 时区 ID,如 America/Los_Angeles */
public String marketplaceZone() {
return marketplaceZone;
@ -150,6 +170,9 @@ public final class ChannelAccount { @@ -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 { @@ -198,6 +221,16 @@ public final class ChannelAccount {
return this;
}
/**
* 设置接口基址。
*
* <p>不设置时由适配器按 provider 取内置默认地址;需要连 PR / 私有化环境时在这里覆盖。</p>
*/
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 { @@ -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;
}
}

127
channel-sdk-core/src/main/java/common/ecommerce/channel/sdk/ChannelSdk.java

@ -22,6 +22,8 @@ import common.ecommerce.channel.model.account.ChannelAccount; @@ -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 { @@ -112,12 +114,21 @@ public final class ChannelSdk implements ProviderResolver {
*/
private final Supplier<String> requestIdSupplier;
/**
* 凭据解析器;把账户的 {@code credentialRef} 换成真实密钥。
*
* <p>未注入时为 {@code null},此时只能用带 {@code ChannelConnection} 的入口;
* 注入后可使用免连接重载({@code salesOrders(key)} 等)。</p>
*/
private final SecretProvider secretProvider;
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, PlatformAdapter>(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 { @@ -157,6 +168,19 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
* 3P 销售订单视图(免连接)。
*
* <p>连接由账户端点 + {@link SecretProvider} 自动组装;需要显式覆盖地址或密钥时
* 用 {@link #salesOrders(AccountKey, ChannelConnection)}。</p>
*
* @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 销售订单视图。
*
* <p>能力检查发生在 {@code pull()} 调用时,不是取视图时。</p>
@ -167,6 +191,16 @@ public final class ChannelSdk implements ProviderResolver { @@ -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 视图。
*
* <p>能力检查发生在 {@code pull()} 调用时,不是取视图时。</p>
@ -176,6 +210,12 @@ public final class ChannelSdk implements ProviderResolver { @@ -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 { @@ -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);
}
/**
* 售后视图:拉取退款 / 退货 / 换货订单(只读)。
*
* <p>能力检查发生在 {@code pull()} 调用时;适配器未实现 {@code AfterSaleCapable}
@ -194,6 +244,16 @@ public final class ChannelSdk implements ProviderResolver { @@ -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);
}
/**
* 履约 / 出库视图。
*
* <p><b>写操作</b>:会改变平台数据。领星没有测试环境,验证阶段禁止调用。</p>
@ -204,6 +264,16 @@ public final class ChannelSdk implements ProviderResolver { @@ -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 到货接收明细(只读)。
*
* <p>能力检查发生在 {@code shipments()} / {@code receipts()} 调用时;
@ -216,6 +286,16 @@ public final class ChannelSdk implements ProviderResolver { @@ -216,6 +286,16 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
* 聚合器的子店铺列表(免连接)。
*
* @throws IllegalStateException 未注入 {@code secretProvider},或账户缺端点且适配器无默认地址
*/
public List<AggregatorCapable.SubChannel> subChannels(AccountKey key) {
ChannelAccount account = requireAccount(key);
return subChannels(key, connectionOf(key, account));
}
/**
* 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。
*
* <p>典型用途是<b>首次接入</b>:把 platformCode + externalStoreId 拉下来,
@ -326,6 +406,37 @@ public final class ChannelSdk implements ProviderResolver { @@ -326,6 +406,37 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
* 免连接重载用:按账户端点 + {@link SecretProvider} 组装连接。
*
* <p>端点优先级:{@code account.endpointBaseUrl()} → 适配器默认地址。
* 两者都没有时明确报错,不猜地址。</p>
*
* @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 { @@ -388,6 +499,22 @@ public final class ChannelSdk implements ProviderResolver {
/** 时钟,默认 UTC;测试注入固定时钟。 */
private Clock clock = Clock.systemUTC();
/** 凭据解析器;注入后才能用免连接重载。 */
private SecretProvider secretProvider;
/**
* 注入凭据解析器。
*
* <p>注入后可使用 {@code salesOrders(key)} 这类免连接入口:SDK 用
* {@code ChannelAccount.endpointBaseUrl()}(为空则取适配器默认地址)和
* 本解析器按 {@code credentialRef} 取到的密钥组装连接。
* 密钥只在内存中出现,SDK 不保存、不落盘。</p>
*/
public Builder secretProvider(SecretProvider secretProvider) {
this.secretProvider = secretProvider;
return this;
}
/**
* 注入账户仓库。<b>必需</b>。
*

44
channel-sdk-core/src/test/java/common/ecommerce/channel/sdk/ChannelSdkTest.java

@ -16,6 +16,7 @@ import common.ecommerce.channel.sdk.ChannelContext; @@ -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 { @@ -58,6 +59,11 @@ class ChannelSdkTest {
}
@Override
public String defaultEndpointBaseUrl() {
return "https://api.example.com";
}
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER);
}
@ -251,4 +257,42 @@ class ChannelSdkTest { @@ -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<SalesOrder> 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));
}
}

10
lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java

@ -166,6 +166,16 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -166,6 +166,16 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
return ChannelProvider.LINGXING;
}
/**
* 领星只有一个开放平台域名,没有 PR / 生产之分。
*
* <p>账户配置了 {@code endpointBaseUrl} 时以账户为准(私有化部署 / 代理场景)。</p>
*/
@Override
public String defaultEndpointBaseUrl() {
return common.ecommerce.lingxing.LingxingConstants.PRODUCTION_BASE_URL;
}
@Override
public Set<Platform> platforms() {
return EnumSet.of(Platform.AMAZON_SC, Platform.AMAZON_VC, Platform.WALMART_SC, Platform.TIKTOK,

37
sdk-common/src/main/java/common/ecommerce/shared/spi/ChannelSecret.java

@ -3,16 +3,25 @@ package common.ecommerce.shared.spi; @@ -3,16 +3,25 @@ package common.ecommerce.shared.spi;
import java.util.Objects;
/**
* 凭证内容。按 provider 需要取用,未使用的字段为 null。
* 凭证内容与接入端点。按 provider 需要取用,未使用的字段为 null。
*
* <p>整体由调用方在每次调用时通过 {@code ChannelConnection} 传入,SDK 不落盘。
* <p>地址与密钥放在一起:它们同属「一套接入身份」,换环境时一起换。</p>
*
* <p>本对象由调用方经 {@code SecretProvider} 或 {@code ChannelConnection} 传入,SDK 不落盘。
* 日志只能用 {@link #fingerprint()},禁止打印原始值。</p>
*/
public final class ChannelSecret {
/** 目标基址;由 ChannelConnection 构造时写回,供 TokenManager 的刷新回调使用。 */
/** 主接口基址,如 {@code https://open-hwc.yqn.com};由调用方配置,SDK 不猜。 */
private final String endpointBaseUrl;
/**
* 辅助接口基址;仅少数仓把部分接口放在另一个主机时使用(如运去哪的轨迹查询)。
*
* <p>为 null 时,需要它的能力会显式拒绝,不会退回主基址。</p>
*/
private final String auxEndpointBaseUrl;
/** 应用标识。领星:appId(同时作为签名 AES 密钥,长度须为 16/24/32 字节)。 */
private final String appKey;
@ -30,6 +39,7 @@ public final class ChannelSecret { @@ -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 { @@ -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 { @@ -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 { @@ -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;

6
sdk-testkit/src/main/java/common/ecommerce/shared/testkit/FakeDirectAdapter.java

@ -116,6 +116,12 @@ public final class FakeDirectAdapter implements SalesOrderCapable, ProductCapabl @@ -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<Platform> platforms() {
return EnumSet.of(platform);

10
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java

@ -21,6 +21,16 @@ public interface WarehouseAdapter { @@ -21,6 +21,16 @@ public interface WarehouseAdapter {
EnumSet<WarehouseCapability> capabilities();
/**
* 该适配器的默认主接口基址。
*
* <p>仅当账户未配置 {@code endpointBaseUrl} 时使用;返回 null 表示适配器不提供默认值,
* 此时调用方必须显式传入 {@code WarehouseConnection}。默认 null,适配器按需覆盖。</p>
*/
default String defaultEndpointBaseUrl() {
return null;
}
/**
* 按仓细化能力。一个 provider 账户下可能挂多个仓,能力可能不同。
*
* <p>默认等价于 {@link #capabilities()};需要按仓细化的适配器覆盖它。</p>

10
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java

@ -49,9 +49,15 @@ public final class WarehouseConnection { @@ -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())

74
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java

@ -4,6 +4,7 @@ import common.ecommerce.shared.audit.CallObserver; @@ -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 { @@ -81,12 +82,21 @@ public final class WarehouseSdk {
/** 链路 ID 生成器。 */
private final Supplier<String> requestIdSupplier;
/**
* 凭据解析器;把账户的 {@code credentialRef} 换成真实密钥。
*
* <p>未注入时为 {@code null},此时只能用带 {@code WarehouseConnection} 的入口;
* 注入后可使用 {@link #warehouses(String)} 免连接重载。</p>
*/
private final SecretProvider secretProvider;
private WarehouseSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, WarehouseAdapter>(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 { @@ -97,6 +107,22 @@ public final class WarehouseSdk {
}
/**
* 取某个仓的接入视图(免连接)。
*
* <p>密钥与地址一起由 {@link SecretProvider} 按 {@code credentialRef} 提供:
* 地址取 {@code ChannelSecret.endpointBaseUrl()},为空时退回适配器默认地址;
* 辅助基址取 {@code ChannelSecret.auxEndpointBaseUrl()}(如运去哪的轨迹主机)。</p>
*
* @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 { @@ -231,6 +257,38 @@ public final class WarehouseSdk {
account.providerWarehouseId(), connection, id, clock);
}
/**
* 免连接重载用:按 {@link SecretProvider} 返回的凭据组装连接。
*
* <p>地址取自 {@code ChannelSecret.endpointBaseUrl()}(与密钥一起配置);
* 未配置时退回适配器内置默认地址。两者都没有时明确报错,不猜地址。</p>
*
* @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 { @@ -249,6 +307,22 @@ public final class WarehouseSdk {
};
private Clock clock = Clock.systemUTC();
/** 凭据解析器;注入后才能用免连接重载。 */
private SecretProvider secretProvider;
/**
* 注入凭据解析器。
*
* <p>注入后可使用 {@code warehouses(warehouseCode)} 免连接入口:SDK 按
* {@code credentialRef} 取到的 {@code ChannelSecret} 里同时含密钥与地址,
* 据此组装连接(地址为空时退回适配器默认地址)。
* 密钥只在内存中出现,SDK 不保存、不落盘。</p>
*/
public Builder secretProvider(SecretProvider secretProvider) {
this.secretProvider = secretProvider;
return this;
}
/** 注入仓主数据仓库。<b>必需</b>。 */
public Builder warehouseRepository(WarehouseRepository repository) {
this.repository = repository;

27
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseAccount.java

@ -5,23 +5,29 @@ import java.util.Objects; @@ -5,23 +5,29 @@ import java.util.Objects;
/**
* 仓接入账户配置。
*
* <p><b>不保存密钥</b>:只存 {@link #credentialRef()},真实凭证由调用方
* 在每次调用时经 {@code WarehouseConnection} 传入。</p>
* <p><b>只有业务数据</b>:哪家仓、仓方怎么称呼它。地址与密钥都不在这里——
* 它们随 {@code SecretProvider} 返回的 {@code ChannelSecret} 一起提供,
* 账户表可以用纯业务表的方式管理、备份与导出。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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);
}

11
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

@ -157,6 +157,17 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -157,6 +157,17 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
}
/**
* 不提供默认地址:生产域名尚未确定({@code EdayunConstants.PRODUCTION_BASE_URL} 仍是占位)。
*
* <p>在账户上配置 {@code endpointBaseUrl} 后即可使用免连接重载;
* 未配置时会明确报错,不会悄悄连到测试环境。</p>
*/
@Override
public String defaultEndpointBaseUrl() {
return null;
}
/**
* 已实现的能力。
*
* <p><b>声明了就必须有实现</b>,否则调用方看能力位会以为能用。</p>

1
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java

@ -38,7 +38,6 @@ class EdayunAdapterTest { @@ -38,7 +38,6 @@ class EdayunAdapterTest {
.provider(WarehouseProvider.EDAYUN.name())
.providerWarehouseId("EDY-WH-1")
.credentialRef("kms://test/edayun")
.timeZone("America/Los_Angeles")
.build();
}

2
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java

@ -84,7 +84,6 @@ class EdayunSdkSmokeTest { @@ -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 { @@ -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)

6
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -199,6 +199,12 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -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<WarehouseCapability> capabilities() {
return EnumSet.of(

1
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java

@ -35,7 +35,6 @@ class HengjianAdapterTest { @@ -35,7 +35,6 @@ class HengjianAdapterTest {
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
.credentialRef("kms://test/hengjian")
.timeZone("America/Los_Angeles")
.build();
}

1
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java

@ -493,7 +493,6 @@ class HengjianCreateOrderTest { @@ -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())

7
warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java

@ -56,7 +56,6 @@ public final class FakeWarehouseAdapter implements OutboundCapable { @@ -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 { @@ -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;

70
warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java

@ -168,4 +168,74 @@ class WarehouseSdkTest { @@ -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));
}
}

6
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -140,6 +140,12 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -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<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,

8
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -133,6 +133,14 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -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<WarehouseCapability> capabilities() {
return java.util.EnumSet.of(

Loading…
Cancel
Save