Browse Source
按 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 <noreply@anthropic.com>feature/supplier-lingxing
11 changed files with 369 additions and 0 deletions
@ -0,0 +1,66 @@
@@ -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)` 一起带出去 | |
||||
@ -0,0 +1,42 @@
@@ -0,0 +1,42 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?> |
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" |
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> |
||||
<modelVersion>4.0.0</modelVersion> |
||||
|
||||
<parent> |
||||
<groupId>ecommerce</groupId> |
||||
<artifactId>channel-sdk-parent</artifactId> |
||||
<version>1.0.0-SNAPSHOT</version> |
||||
</parent> |
||||
|
||||
<artifactId>warehouse-sdk-edayun</artifactId> |
||||
<description>易达云三方仓适配器(3PL 仓储履约)</description> |
||||
|
||||
<dependencies> |
||||
<dependency> |
||||
<groupId>ecommerce</groupId> |
||||
<artifactId>sdk-common</artifactId> |
||||
</dependency> |
||||
<dependency> |
||||
<groupId>ecommerce</groupId> |
||||
<artifactId>warehouse-sdk-core</artifactId> |
||||
</dependency> |
||||
|
||||
<dependency> |
||||
<groupId>ecommerce</groupId> |
||||
<artifactId>sdk-testkit</artifactId> |
||||
<scope>test</scope> |
||||
</dependency> |
||||
<dependency> |
||||
<groupId>ecommerce</groupId> |
||||
<artifactId>warehouse-sdk-testkit</artifactId> |
||||
<scope>test</scope> |
||||
</dependency> |
||||
<dependency> |
||||
<groupId>org.junit.jupiter</groupId> |
||||
<artifactId>junit-jupiter</artifactId> |
||||
<scope>test</scope> |
||||
</dependency> |
||||
</dependencies> |
||||
</project> |
||||
@ -0,0 +1,41 @@
@@ -0,0 +1,41 @@
|
||||
package common.ecommerce.edayun; |
||||
|
||||
/** |
||||
* 易达云(EDAYUN)协议常量。 |
||||
* |
||||
* <p>端点与路径是<b>协议的一部分</b>,写在代码里,不做成配置表。 |
||||
* 运行时不使用 {@link #PR_BASE_URL}:端点由调用方每次经 |
||||
* {@code WarehouseConnection} 传入。</p> |
||||
* |
||||
* <p><b>待补充</b>:目前只搭了模块骨架,接口路径与鉴权方式等文档到位后再填。 |
||||
* 下面带 {@code TODO} 的常量是占位,不要直接用于生产。</p> |
||||
*/ |
||||
public final class EdayunConstants { |
||||
|
||||
/** 适配器标识。 */ |
||||
public static final String ADAPTER_ID = "edayun"; |
||||
|
||||
/** |
||||
* 测试 / 联调环境基址。 |
||||
* |
||||
* <p><b>TODO 待核对</b>:等易达云提供测试域名后替换。</p> |
||||
*/ |
||||
public static final String PR_BASE_URL = "https://TODO.edayun.example"; |
||||
|
||||
/** |
||||
* 生产环境基址。 |
||||
* |
||||
* <p><b>TODO 待核对</b>。</p> |
||||
*/ |
||||
public static final String PRODUCTION_BASE_URL = "TODO"; |
||||
|
||||
/** |
||||
* 限流:每秒许可数。 |
||||
* |
||||
* <p>易达云未公开限流值,先按保守值处理;确认后再调。</p> |
||||
*/ |
||||
public static final int PERMITS_PER_SECOND = 2; |
||||
|
||||
private EdayunConstants() { |
||||
} |
||||
} |
||||
@ -0,0 +1,52 @@
@@ -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; |
||||
|
||||
/** |
||||
* 易达云适配器。 |
||||
* |
||||
* <p><b>骨架阶段</b>:只搭好类型与能力声明,业务接口等文档到位后逐个实现。 |
||||
* 未实现的能力<b>不声明</b>,门面调用会显式抛 |
||||
* {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p> |
||||
* |
||||
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 |
||||
* {@code WarehouseConnection} 传入。</p> |
||||
*/ |
||||
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; |
||||
} |
||||
|
||||
/** |
||||
* 本期没有已实现的能力。 |
||||
* |
||||
* <p>接入业务接口时逐个声明——<b>声明了就必须有实现</b>, |
||||
* 否则调用方看能力位会以为能用。</p> |
||||
*/ |
||||
@Override |
||||
public EnumSet<WarehouseCapability> capabilities() { |
||||
return EnumSet.noneOf(WarehouseCapability.class); |
||||
} |
||||
} |
||||
@ -0,0 +1,37 @@
@@ -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; |
||||
|
||||
/** |
||||
* 易达云适配器工厂。 |
||||
* |
||||
* <p>端点与凭据由调用方在每次请求时传入,工厂只装配协议与基础设施。</p> |
||||
* |
||||
* <p><b>骨架阶段</b>:鉴权方式(是否会像信仓那样需要换 token)等文档到位后再定, |
||||
* 届时若需要 token 缓存,构造函数补 {@code TokenStore} / {@code LockProvider} / |
||||
* {@code Clock},与信仓同构。</p> |
||||
*/ |
||||
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()); |
||||
} |
||||
} |
||||
@ -0,0 +1,9 @@
@@ -0,0 +1,9 @@
|
||||
/** |
||||
* 易达云报文结构(DTO)。 |
||||
* |
||||
* <p><b>约定</b>:一个接口一个文件,不建大而全的 Dtos;字段名照抄文档, |
||||
* 连拼写错误也照抄并加注释说明;保留 {@code @JsonInclude(NON_NULL)}。</p> |
||||
* |
||||
* <p>待接口文档到位后按 {@code docs-warehouse/onboarding-checklist.md} 阶段 2 逐个补充。</p> |
||||
*/ |
||||
package common.ecommerce.edayun.dto; |
||||
@ -0,0 +1,8 @@
@@ -0,0 +1,8 @@
|
||||
/** |
||||
* 易达云平台枚举:带仓方原始码 + {@code toCore()} 映射到底层枚举。 |
||||
* |
||||
* <p><b>约定</b>:精确匹配不用 {@code contains};未知值归 {@code UNKNOWN} 不猜; |
||||
* 提供反向 {@code codeOf()} 供下发;三套不同码表(如退货的预约 / 检验后 / 回调) |
||||
* 各建各的,绝不共用。</p> |
||||
*/ |
||||
package common.ecommerce.edayun.enums; |
||||
@ -0,0 +1,8 @@
@@ -0,0 +1,8 @@
|
||||
/** |
||||
* 易达云出入网层:请求构造、限流、响应信封校验。 |
||||
* |
||||
* <p><b>约定</b>:信封校验要区分「有 {@code code}」与「只有 {@code status}」两种形态—— |
||||
* 运去哪的仓库目录与运费试算就是后者,真机验证时才发现。4xx 错误要把响应体 |
||||
* 带进异常信息,否则排查只能靠猜。</p> |
||||
*/ |
||||
package common.ecommerce.edayun.http; |
||||
@ -0,0 +1,8 @@
@@ -0,0 +1,8 @@
|
||||
/** |
||||
* 易达云回调验签与解析。 |
||||
* |
||||
* <p><b>约定</b>:用 {@code WebhookSignatures}(HMAC + 恒定时间比较 + 时间窗); |
||||
* 多条回调共用一个地址时按报文特征分派;回调也要走 {@code CallSupport.observe}。 |
||||
* 实现见 {@code docs-warehouse/callback.md}。</p> |
||||
*/ |
||||
package common.ecommerce.edayun.webhook; |
||||
@ -0,0 +1,97 @@
@@ -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; |
||||
|
||||
/** |
||||
* 易达云适配器骨架契约测试。 |
||||
* |
||||
* <p>骨架阶段只验证「类型接对了、能力位是空的、未实现能力会显式拒绝」, |
||||
* 不涉及任何真实接口。</p> |
||||
*/ |
||||
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)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue