Compare commits

...

2 Commits

Author SHA1 Message Date
chenchuchuan 8d76933a8d Merge branch 'feature/supplier-lingxing' of http://124.222.6.97:3000/chencc/common-ecommerce into feature/supplier-lingxing 1 week ago
chenchuchuan ae25e73b50 feat(edayun): 新建易达云适配器骨架 1 week ago
  1. 66
      docs-warehouse/edayun/README.md
  2. 1
      pom.xml
  3. 42
      warehouse-sdk-edayun/pom.xml
  4. 41
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  5. 52
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  6. 37
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
  7. 9
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java
  8. 8
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java
  9. 8
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java
  10. 8
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java
  11. 97
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java

66
docs-warehouse/edayun/README.md

@ -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)` 一起带出去 |

1
pom.xml

@ -34,6 +34,7 @@ @@ -34,6 +34,7 @@
<module>warehouse-sdk-testkit</module>
<module>warehouse-sdk-yqn</module>
<module>warehouse-sdk-xincang</module>
<module>warehouse-sdk-edayun</module>
</modules>
<dependencyManagement>

42
warehouse-sdk-edayun/pom.xml

@ -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>

41
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java

@ -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() {
}
}

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

@ -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);
}
}

37
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java

@ -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());
}
}

9
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/package-info.java

@ -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;

8
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/package-info.java

@ -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;

8
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/http/package-info.java

@ -0,0 +1,8 @@ @@ -0,0 +1,8 @@
/**
* 易达云出入网层:请求构造、限流、响应信封校验。
*
* <p><b>约定</b>:信封校验要区分「有 {@code code}」与「只有 {@code status}」两种形态——
* 运去哪的仓库目录与运费试算就是后者,真机验证时才发现。4xx 错误要把响应体
* 带进异常信息,否则排查只能靠猜。</p>
*/
package common.ecommerce.edayun.http;

8
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/webhook/package-info.java

@ -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;

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

@ -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…
Cancel
Save