From ae25e73b500de897a126f41976b96efd8f059298 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Thu, 12 Nov 2026 10:46:45 +0800 Subject: [PATCH] =?UTF-8?q?feat(edayun):=20=E6=96=B0=E5=BB=BA=E6=98=93?= =?UTF-8?q?=E8=BE=BE=E4=BA=91=E9=80=82=E9=85=8D=E5=99=A8=E9=AA=A8=E6=9E=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按 docs-warehouse/onboarding-checklist.md 阶段 1 搭好模块: - warehouse-sdk-edayun:pom、注册到根 modules - EdayunConstants:端点 / 限流(带 TODO 占位,等文档) - EdayunAdapter / EdayunAdapterFactory:类型就绪,能力位为空 - dto / enums / http / webhook 四个包的 package-info 写明约定, 后续按约定往里填 骨架阶段的行为:任何业务调用抛 WarehouseUnsupportedCapabilityException。 未实现的能力不声明——声明了就必须有实现,否则调用方看能力位会以为能用。 测试 EdayunAdapterTest(5 个):适配器标识、能力位为空、注册后可解析、 未实现能力显式拒绝、能力查询不触发真实 API。 文档 docs-warehouse/edayun/README.md 记了当前状态和 8 项待确认 (文档、测试环境、鉴权、限流、能否走写、回调、费用口径、库存同步)。 全量 510 个测试通过。 Co-Authored-By: Claude --- docs-warehouse/edayun/README.md | 66 +++++++++++++++ pom.xml | 1 + warehouse-sdk-edayun/pom.xml | 42 ++++++++++ .../common/ecommerce/edayun/EdayunConstants.java | 41 +++++++++ .../ecommerce/edayun/adapter/EdayunAdapter.java | 52 ++++++++++++ .../edayun/adapter/EdayunAdapterFactory.java | 37 +++++++++ .../common/ecommerce/edayun/dto/package-info.java | 9 ++ .../ecommerce/edayun/enums/package-info.java | 8 ++ .../common/ecommerce/edayun/http/package-info.java | 8 ++ .../ecommerce/edayun/webhook/package-info.java | 8 ++ .../edayun/adapter/EdayunAdapterTest.java | 97 ++++++++++++++++++++++ 11 files changed, 369 insertions(+) create mode 100644 docs-warehouse/edayun/README.md create mode 100644 warehouse-sdk-edayun/pom.xml create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md new file mode 100644 index 0000000..a83401e --- /dev/null +++ b/docs-warehouse/edayun/README.md @@ -0,0 +1,66 @@ +# 易达云(EDAYUN)接入 + +## 当前状态:骨架 + +| 项 | 状态 | +|---|---| +| 模块 | ✅ `warehouse-sdk-edayun` 已建、已注册 | +| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 | +| 接口 | ⬜ 等文档 | +| 回调 | ⬜ 等文档 | +| 真机验证 | ⬜ 等测试环境 | + +**骨架阶段的行为**:任何业务调用都会抛 +`WarehouseUnsupportedCapabilityException`——这是有意为之,不返回空集合。 + +## 待确认(问易达云) + +| # | 要确认 | +|---|---| +| 1 | **接口文档**(含回调) | +| 2 | **测试环境**:域名、凭证、测试仓、测试 SKU | +| 3 | **鉴权方式**:固定 token / 签名 / OAuth?是否需要换 token 与刷新? | +| 4 | **限流**:每秒许可数、单日配额 | +| 5 | **能否在 PR 环境走写操作**(建单 / 取消 / 销毁),决定探针设计 | +| 6 | **回调**:验签算法、时间戳单位、响应体格式、是否按路径区分 | +| 7 | **费用口径**:是否有费用类型码(运去哪只有中文名) | +| 8 | **库存同步**:支持按时间增量还是只能全量 | + +## 骨架已定的部分 + +``` +warehouse-sdk-edayun/ +├── pom.xml +└── src/main/java/common/ecommerce/edayun/ + ├── EdayunConstants.java 端点 / 路径 / 限流(带 TODO 占位) + ├── adapter/ + │ ├── EdayunAdapter.java 能力位为空,未实现能力不声明 + │ └── EdayunAdapterFactory.java + ├── dto/package-info.java 一个接口一个文件 + ├── enums/package-info.java 平台枚举约定 + ├── http/package-info.java 信封校验约定 + └── webhook/package-info.java 回调约定 +``` + +**测试**:`EdayunAdapterTest`(5 个)验证类型接对、能力位为空、 +未实现能力显式拒绝、注册后可解析、能力查询不触发真实 API。 + +## 接下来怎么推进 + +按 [onboarding-checklist.md](../onboarding-checklist.md): + +1. 拿到文档后补 `EdayunConstants` 的路径常量 +2. 按接口逐个补 `dto/` + `adapter/XxxMapper` + `enums/`(阶段 2 的 6 步) +3. 写只读探针 → 真机验证 → 全链路探针 +4. 补回调实现 +5. 更新本文档 + +## 已知的坑(从运去哪/信仓带来的经验) + +| 坑 | 应对 | +|---|---| +| 文档参数名可能带 `query.` 前缀而实际不带 | 真机验证时必须核对 | +| 有些接口没有 `code` 只有 `status` | 信封校验要兼容两种 | +| 文档示例常是自动生成的占位符 | 不看示例值,看真机返回 | +| 单位可能未标注 | 真机验证量级(kg vs lb 差 2.2 倍) | +| 状态码可能依赖上下文(单据类型) | `(type, status)` 一起带出去 | diff --git a/pom.xml b/pom.xml index fce5317..ceef4af 100644 --- a/pom.xml +++ b/pom.xml @@ -34,6 +34,7 @@ warehouse-sdk-testkit warehouse-sdk-yqn warehouse-sdk-xincang + warehouse-sdk-edayun diff --git a/warehouse-sdk-edayun/pom.xml b/warehouse-sdk-edayun/pom.xml new file mode 100644 index 0000000..561384c --- /dev/null +++ b/warehouse-sdk-edayun/pom.xml @@ -0,0 +1,42 @@ + + + 4.0.0 + + + ecommerce + channel-sdk-parent + 1.0.0-SNAPSHOT + + + warehouse-sdk-edayun + 易达云三方仓适配器(3PL 仓储履约) + + + + ecommerce + sdk-common + + + ecommerce + warehouse-sdk-core + + + + ecommerce + sdk-testkit + test + + + ecommerce + warehouse-sdk-testkit + test + + + org.junit.jupiter + junit-jupiter + test + + + diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java new file mode 100644 index 0000000..2cad1c9 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java @@ -0,0 +1,41 @@ +package common.ecommerce.edayun; + +/** + * 易达云(EDAYUN)协议常量。 + * + *

端点与路径是协议的一部分,写在代码里,不做成配置表。 + * 运行时不使用 {@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 capabilities() { + return EnumSet.noneOf(WarehouseCapability.class); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java new file mode 100644 index 0000000..66dc2c3 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java @@ -0,0 +1,37 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.EdayunConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; + +/** + * 易达云适配器工厂。 + * + *

端点与凭据由调用方在每次请求时传入,工厂只装配协议与基础设施。

+ * + *

骨架阶段:鉴权方式(是否会像信仓那样需要换 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)); + } +}