端点与路径是协议的一部分,写在代码里,不做成配置表。 + * 运行时不使用 {@link #PR_BASE_URL}:端点由调用方每次经 + * {@code WarehouseConnection} 传入。
+ * + *待补充:目前只搭了模块骨架,接口路径与鉴权方式等文档到位后再填。 + * 下面带 {@code TODO} 的常量是占位,不要直接用于生产。
+ */ +public final class EdayunConstants { + + /** 适配器标识。 */ + public static final String ADAPTER_ID = "edayun"; + + /** + * 测试 / 联调环境基址。 + * + *TODO 待核对:等易达云提供测试域名后替换。
+ */ + public static final String PR_BASE_URL = "https://TODO.edayun.example"; + + /** + * 生产环境基址。 + * + *TODO 待核对。
+ */ + public static final String PRODUCTION_BASE_URL = "TODO"; + + /** + * 限流:每秒许可数。 + * + *易达云未公开限流值,先按保守值处理;确认后再调。
+ */ + public static final int PERMITS_PER_SECOND = 2; + + private EdayunConstants() { + } +} 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 new file mode 100644 index 0000000..d060748 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -0,0 +1,52 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import common.ecommerce.edayun.EdayunConstants; + +import java.util.EnumSet; + +/** + * 易达云适配器。 + * + *骨架阶段:只搭好类型与能力声明,业务接口等文档到位后逐个实现。 + * 未实现的能力不声明,门面调用会显式抛 + * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
+ * + *适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 + * {@code WarehouseConnection} 传入。
+ */ +public final class EdayunAdapter implements WarehouseAdapter { + + private final HttpTransport transport; + private final JacksonJsonCodec json; + + public EdayunAdapter(HttpTransport transport, JacksonJsonCodec json) { + this.transport = transport; + this.json = json; + } + + @Override + public String adapterId() { + return EdayunConstants.ADAPTER_ID; + } + + @Override + public WarehouseProvider provider() { + return WarehouseProvider.EDAYUN; + } + + /** + * 本期没有已实现的能力。 + * + *接入业务接口时逐个声明——声明了就必须有实现, + * 否则调用方看能力位会以为能用。
+ */ + @Override + public EnumSet端点与凭据由调用方在每次请求时传入,工厂只装配协议与基础设施。
+ * + *骨架阶段:鉴权方式(是否会像信仓那样需要换 token)等文档到位后再定, + * 届时若需要 token 缓存,构造函数补 {@code TokenStore} / {@code LockProvider} / + * {@code Clock},与信仓同构。
+ */ +public final class EdayunAdapterFactory implements WarehouseAdapterFactory { + + @Override + public String adapterId() { + return EdayunConstants.ADAPTER_ID; + } + + @Override + public WarehouseProvider provider() { + return WarehouseProvider.EDAYUN; + } + + @Override + public WarehouseAdapter create(AdapterConfig config) { + return new EdayunAdapter( + new OkHttpTransport("common-ecommerce/1.0.0 (edayun)"), + new JacksonJsonCodec()); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java new file mode 100644 index 0000000..7c58b4c --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java @@ -0,0 +1,9 @@ +/** + * 易达云报文结构(DTO)。 + * + *约定:一个接口一个文件,不建大而全的 Dtos;字段名照抄文档, + * 连拼写错误也照抄并加注释说明;保留 {@code @JsonInclude(NON_NULL)}。
+ * + *待接口文档到位后按 {@code docs-warehouse/onboarding-checklist.md} 阶段 2 逐个补充。
+ */ +package common.ecommerce.edayun.dto; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java new file mode 100644 index 0000000..765fcd2 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java @@ -0,0 +1,8 @@ +/** + * 易达云平台枚举:带仓方原始码 + {@code toCore()} 映射到底层枚举。 + * + *约定:精确匹配不用 {@code contains};未知值归 {@code UNKNOWN} 不猜; + * 提供反向 {@code codeOf()} 供下发;三套不同码表(如退货的预约 / 检验后 / 回调) + * 各建各的,绝不共用。
+ */ +package common.ecommerce.edayun.enums; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java new file mode 100644 index 0000000..3078f2e --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java @@ -0,0 +1,8 @@ +/** + * 易达云出入网层:请求构造、限流、响应信封校验。 + * + *约定:信封校验要区分「有 {@code code}」与「只有 {@code status}」两种形态—— + * 运去哪的仓库目录与运费试算就是后者,真机验证时才发现。4xx 错误要把响应体 + * 带进异常信息,否则排查只能靠猜。
+ */ +package common.ecommerce.edayun.http; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java new file mode 100644 index 0000000..3bc1497 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java @@ -0,0 +1,8 @@ +/** + * 易达云回调验签与解析。 + * + *约定:用 {@code WebhookSignatures}(HMAC + 恒定时间比较 + 时间窗); + * 多条回调共用一个地址时按报文特征分派;回调也要走 {@code CallSupport.observe}。 + * 实现见 {@code docs-warehouse/callback.md}。
+ */ +package common.ecommerce.edayun.webhook; 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 new file mode 100644 index 0000000..c20662e --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java @@ -0,0 +1,97 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.EdayunConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; +import common.ecommerce.warehouse.sdk.WarehouseSdk; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.spi.WarehouseAccount; +import common.ecommerce.warehouse.testkit.InMemoryWarehouses; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 易达云适配器骨架契约测试。 + * + *骨架阶段只验证「类型接对了、能力位是空的、未实现能力会显式拒绝」, + * 不涉及任何真实接口。
+ */ +class EdayunAdapterTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-11T00:00:00Z"), ZoneOffset.UTC); + private static final String WH = "EDY-US-01"; + + private static WarehouseAccount account() { + return WarehouseAccount.builder() + .warehouseCode(WH) + .provider(WarehouseProvider.EDAYUN.name()) + .providerWarehouseId("EDY-WH-1") + .credentialRef("kms://test/edayun") + .timeZone("America/Los_Angeles") + .build(); + } + + private static WarehouseSdk sdk() { + return WarehouseSdk.builder() + .warehouseRepository(new InMemoryWarehouses().put(account())) + .clock(CLOCK) + .register(new EdayunAdapterFactory()) + .build(); + } + + @Test + void adapterIdentity() { + EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + + assertEquals(EdayunConstants.ADAPTER_ID, adapter.adapterId()); + assertEquals(WarehouseProvider.EDAYUN, adapter.provider()); + } + + /** 骨架阶段没有任何已实现能力;声明了就必须有实现,所以这里必须为空。 */ + @Test + void declaresNoCapabilityYet() { + EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + + assertTrue(adapter.capabilities().isEmpty()); + } + + /** 注册到门面后能按 provider 解析到适配器。 */ + @Test + void registersAndResolves() { + WarehouseSdk sdk = sdk(); + + assertTrue(sdk.capabilities(WH).supported().isEmpty()); + } + + /** 未声明能力时门面显式拒绝,不返回空列表。 */ + @Test + void unimplementedCapabilityIsRejected() { + WarehouseSdk sdk = sdk(); + WarehouseConnection conn = WarehouseConnection.of( + EdayunConstants.PR_BASE_URL, + common.ecommerce.shared.spi.ChannelSecret.builder().appSecret("k").build()); + + assertThrows(WarehouseUnsupportedCapabilityException.class, + () -> sdk.warehouses(WH, conn).outbound().get( + common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("OB-1"))); + } + + /** 能力矩阵查询本身可用(不触发真实 API)。 */ + @Test + void capabilityQueryIsOffline() { + EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + + assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND)); + } +}