Browse Source

feat(edayun): 对接客户自有物流服务(承运商)清单

POST /webApi/carrier/v1/listCarrierByWarehouse → List<WarehouseCarrier>

返回两层:承运商(carrierId / 名称中英文)→ 物流服务(logisticId / 名称)。
自提单下单时 carrierName 可以填承运商名,也可以用某个物流服务的名字。

统一模型新增 WarehouseCarrier;能力挂在
WarehouseDirectoryCapable.carrierDirectory(门面 carrierDirectory())。
原有的 carriers()(List<String>,只有码)保留不动——carrierDirectory 的
默认实现会把码包装成无名条目,能给出结构的仓覆盖它。

ownLogisticList 文档写成对象、真机返回数组,DTO 按 List 收。

真机(2026-11-16):仓 2 返回 11 个承运商(FedEx 下 12 个物流服务);
不传仓 22 个;countryCode=US 10 个。

顺带:易达云没有仓库列表接口,warehouses() 显式抛不支持,
不返回空列表——空列表和「没有仓」调用方分不清。DIRECTORY 能力位
目前只覆盖承运商这一半。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 4 days ago
parent
commit
17ef1c574a
  1. 53
      docs-warehouse/edayun/README.md
  2. 3
      docs-warehouse/edayun/TODO.md
  3. 25
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java
  4. 116
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java
  5. 14
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 3
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  7. 48
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  8. 83
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java
  9. 60
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java
  10. 160
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
  11. 117
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java

53
docs-warehouse/edayun/README.md

@ -29,6 +29,7 @@
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | | 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) |
| 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | | 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) |
| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** | | 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** |
| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) |
| 其它业务接口 | ⬜ 等文档 | | 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 | | 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 | | 真机验证 | ⬜ 等测试环境 |
@ -1210,6 +1211,58 @@ POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel
`madeInChina` 与 `separation` 是易达云特有语义,统一模型没有对应概念 → 默认关。 `madeInChina` 与 `separation` 是易达云特有语义,统一模型没有对应概念 → 默认关。
## 承运商清单(客户自有物流服务)
```
POST /webApi/carrier/v1/listCarrierByWarehouse → List<WarehouseCarrier>
```
客户自有物流(自有物流 + 客户上传面单)下单时要用:`carrierName` 可以填承运商名,
也可以用某个下属物流服务的名字。
### 两层结构
```
承运商(carrierId / carrierNameEn / carrierNameCn)
└── 物流服务(logisticId / logisticName)
```
统一模型新增 `WarehouseCarrier`(带 `logists()`),挂到
`WarehouseDirectoryCapable.carrierDirectory(ctx)`,门面 `carrierDirectory()`。
原有的 `carriers()` 返回 `List<String>`(只有码),保留不动;
`carrierDirectory()` 的默认实现会把 `carriers()` 的码包装成无名条目,
能给出结构的仓覆盖它。
### `ownLogisticList` 文档写成对象、真机是数组
```json
"ownLogisticList": [ {"logisticId":"583","logisticName":"..."}, ... ]
```
DTO 按 `List` 收。
### 入参
| 字段 | 我们的值 |
|---|---|
| `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字/为空时不传 |
| `countryCode` | 本地不传(统一模型没有对应字段) |
### 真机验证(2026-11-16)
| 场景 | 结果 |
|---|---|
| 仓 2 | **11 个承运商**,FedEx 下有 12 个物流服务 |
| 不传仓 | 22 个承运商 |
| `countryCode=US` | 10 个承运商 |
### 仓库列表接口没有
易达云文档没给「查仓库列表」,所以 `warehouses()` 显式抛
`WarehouseUnsupportedCapabilityException`——不返回空列表,免得和「没有仓」混淆。
能力位 `DIRECTORY` 只覆盖承运商这一半。
## 待确认(问易达云) ## 待确认(问易达云)
| # | 要确认 | | # | 要确认 |

3
docs-warehouse/edayun/TODO.md

@ -71,6 +71,9 @@
| 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) | | 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) |
| 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 | | 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 |
| 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) | | 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) |
| 74 | 易达云**没有仓库列表接口** | `warehouses()` 显式拒绝;`DIRECTORY` 只覆盖承运商 | 宿主不能从仓方拉仓库清单 |
| 75 | 承运商接口的 `countryCode` 过滤统一模型没有对应字段 | 不下发 | 宿主想按国家筛承运商得用扩展方法 |
| 76 | `ownLogisticList` 文档写成对象、真机是数组 | DTO 按 List 收 | 无(已兼容) |
| 70 | 箱唛的 `madeInChina` / `separation` 统一模型没有语义 | 默认关 | 需要打「Made in China」时得走扩展重载 | | 70 | 箱唛的 `madeInChina` / `separation` 统一模型没有语义 | 默认关 | 需要打「Made in China」时得走扩展重载 |
| 71 | 箱唛选箱条件(系统箱号 / SKU / 箱序号 / 客户箱号)统一模型没有 | 提供 `CaseSelection` 扩展重载 | 宿主想要部分箱打印必须用易达云专有 API | | 71 | 箱唛选箱条件(系统箱号 / SKU / 箱序号 / 客户箱号)统一模型没有 | 提供 `CaseSelection` 扩展重载 | 宿主想要部分箱打印必须用易达云专有 API |
|---|---|---|---| |---|---|---|---|

25
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java

@ -37,4 +37,29 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY); common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY);
} }
/**
* 客户自有的承运商及其下属物流服务(带名称与 id 的完整结构)。
*
* <p>与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 →
* 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。</p>
*
* <p>默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。</p>
*
* @return 承运商列表;仓方返回空时为 empty list(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code DIRECTORY} 或没有承运商接口
*/
default List<common.ecommerce.warehouse.model.WarehouseCarrier> carrierDirectory(
WarehouseContext ctx) {
List<common.ecommerce.warehouse.model.WarehouseCarrier> out =
new java.util.ArrayList<common.ecommerce.warehouse.model.WarehouseCarrier>();
for (String code : carriers(ctx)) {
out.add(common.ecommerce.warehouse.model.WarehouseCarrier.builder()
.carrierId(code)
.nameEn(code)
.build());
}
return out;
}
} }

116
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java

@ -0,0 +1,116 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 客户自有的承运商(物流服务商)及其下属物流服务。
*
* <p>用于「客户自有物流 + 客户上传面单」的自提单场景:下单时
* {@code carrierName} 填 {@link #nameEn()} 或某个 {@link OwnLogistic#name()}。</p>
*
* <p>这是<b>主数据</b>,不是状态:同一仓的承运商清单很少变,适合宿主缓存。</p>
*/
public final class WarehouseCarrier {
/** 承运商 id(仓方码)。 */
private final String carrierId;
/** 承运商英文名,如 {@code FedEx}。 */
private final String nameEn;
/** 承运商中文名。 */
private final String nameCn;
/** 该承运商下的物流服务;仓方未给时为空列表。 */
private final List<OwnLogistic> logists;
private WarehouseCarrier(Builder b) {
this.carrierId = require(b.carrierId, "carrierId");
this.nameEn = b.nameEn;
this.nameCn = b.nameCn;
this.logists = Collections.unmodifiableList(new ArrayList<OwnLogistic>(b.logists));
}
public static Builder builder() {
return new Builder();
}
public String carrierId() {
return carrierId;
}
public String nameEn() {
return nameEn;
}
public String nameCn() {
return nameCn;
}
/** 下属物流服务;可能为空。 */
public List<OwnLogistic> logists() {
return logists;
}
/** 展示名:优先中文名,没有再用英文名。 */
public String displayName() {
return nameCn != null && !nameCn.trim().isEmpty() ? nameCn : nameEn;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
/** 承运商下的一个物流服务。 */
public static final class OwnLogistic {
private final String logisticId;
private final String name;
public OwnLogistic(String logisticId, String name) {
this.logisticId = require(logisticId, "logisticId");
this.name = name;
}
public String logisticId() {
return logisticId;
}
public String name() {
return name;
}
}
public static final class Builder {
private String carrierId;
private String nameEn;
private String nameCn;
private final List<OwnLogistic> logists = new ArrayList<OwnLogistic>();
public Builder carrierId(String v) {
this.carrierId = v;
return this;
}
public Builder nameEn(String v) {
this.nameEn = v;
return this;
}
public Builder nameCn(String v) {
this.nameCn = v;
return this;
}
public Builder logistic(OwnLogistic v) {
this.logists.add(v);
return this;
}
public WarehouseCarrier build() {
return new WarehouseCarrier(this);
}
}
}

14
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -315,6 +315,20 @@ public final class WarehouseOperations {
} }
/** /**
* 仓方基础资料:客户自有的承运商及其下属物流服务。
*
* <p>只读主数据。与 {@link #carriers()} 的区别是带名称与两层结构,
* 宿主可直接渲染成「承运商 → 物流服务」两级下拉。</p>
*/
public List<common.ecommerce.warehouse.model.WarehouseCarrier> carrierDirectory() {
require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.directory.carriers.detail",
CallSupport.params(),
List::size,
() -> ((WarehouseDirectoryCapable) adapter).carrierDirectory(ctx));
}
/**
* 查物流产品(承运商渠道)清单。只读主数据,不走幂等。 * 查物流产品(承运商渠道)清单。只读主数据,不走幂等。
* *
* @param warehouseCode 仓 code;null 时用账户配置的仓 * @param warehouseCode 仓 code;null 时用账户配置的仓

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

@ -115,6 +115,9 @@ public final class EdayunConstants {
public static final String PATH_SKU_LABEL_PRINT = public static final String PATH_SKU_LABEL_PRINT =
"/webApi/entryInfo/v1/newPrintCaseMarkContentType"; "/webApi/entryInfo/v1/newPrintCaseMarkContentType";
/** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */
public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse";
/** 物流增值:签收服务。 */ /** 物流增值:签收服务。 */
public static final String ADD_SERVICE_SIGNATURE = "is_signature"; public static final String ADD_SERVICE_SIGNATURE = "is_signature";

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

@ -4,6 +4,7 @@ import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient; import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; import common.ecommerce.edayun.dto.EdayunAccountFlowDtos;
import common.ecommerce.edayun.dto.EdayunBolDtos; import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCancelDtos;
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos; import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos; import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
@ -80,6 +81,9 @@ import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.model.WarehouseLabel; import common.ecommerce.warehouse.model.WarehouseLabel;
import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
@ -102,7 +106,7 @@ import java.util.List;
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable, public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable,
InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable, InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable,
TrackingCapable, CaseMarkPrintCapable { TrackingCapable, CaseMarkPrintCapable, WarehouseDirectoryCapable {
/** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */ /** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */
private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1; private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1;
@ -160,7 +164,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND,
WarehouseCapability.RETURN, WarehouseCapability.BOL, WarehouseCapability.RETURN, WarehouseCapability.BOL,
WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRACKING, WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRACKING,
WarehouseCapability.CASE_MARK_PRINT); WarehouseCapability.CASE_MARK_PRINT, WarehouseCapability.DIRECTORY);
} }
/** /**
@ -1073,6 +1077,46 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
return EdayunSkuLabelMapper.toLabel(parsed.data.trim()); return EdayunSkuLabelMapper.toLabel(parsed.data.trim());
} }
// ------------------------------------------------------------------ 承运商
/**
* 客户名下的仓库列表。
*
* <p><b>易达云文档没给仓库列表接口</b>,显式拒绝而不是返回空列表——
* 空列表和「不支持」调用方分不清。</p>
*/
@Override
public List<WarehouseFacility> warehouses(WarehouseContext ctx) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.DIRECTORY);
}
/**
* 客户自有物流服务(承运商)清单
* ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>返回「承运商 → 物流服务」两层。{@code warehouseId} 只认数字;
* 非数字或为空时不下发,仓方会返回所有服务商。</p>
*
* <p>真机(2026-11-16):仓 2 → 11 个承运商;不传仓 → 22 个;
* 只按国家 US → 10 个。{@code ownLogisticList} 实测是数组(文档写成对象)。</p>
*/
@Override
public List<WarehouseCarrier> carrierDirectory(WarehouseContext ctx) {
EdayunCarrierDtos.ListCarrierRequest body =
EdayunCarrierMapper.toRequest(ctx.providerWarehouseId(), null);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_CARRIERS, bodyJson,
"warehouse.directory.carriers.detail");
EdayunCarrierDtos.ListCarrierResponse parsed =
json.fromJson(resp.body(), EdayunCarrierDtos.ListCarrierResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.carriers.detail");
return EdayunCarrierMapper.toCarriers(parsed == null ? null : parsed.data);
}
// ------------------------------------------------------------------ internals // ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */ /** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) { private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {

83
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java

@ -0,0 +1,83 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 易达云承运商映射({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>响应 {@code ownLogisticList} 文档写成对象、真机返回数组,DTO 按 List 收。</p>
*/
public final class EdayunCarrierMapper {
private EdayunCarrierMapper() {
}
/** 查询请求。 */
public static EdayunCarrierDtos.ListCarrierRequest toRequest(String providerWarehouseId,
String countryCode) {
EdayunCarrierDtos.ListCarrierRequest req = new EdayunCarrierDtos.ListCarrierRequest();
req.warehouseId = warehouseIdOf(providerWarehouseId);
req.countryCode = hasText(countryCode) ? countryCode.trim() : null;
return req;
}
/** 响应 → 统一模型;{@code carrierId} 缺失的行跳过(模型要求非空)。 */
public static List<WarehouseCarrier> toCarriers(
List<EdayunCarrierDtos.Carrier> rows) {
if (rows == null || rows.isEmpty()) {
return Collections.emptyList();
}
List<WarehouseCarrier> out = new ArrayList<WarehouseCarrier>(rows.size());
for (EdayunCarrierDtos.Carrier row : rows) {
WarehouseCarrier carrier = toCarrier(row);
if (carrier != null) {
out.add(carrier);
}
}
return out;
}
static WarehouseCarrier toCarrier(EdayunCarrierDtos.Carrier row) {
if (row == null || !hasText(row.carrierId)) {
return null;
}
WarehouseCarrier.Builder b = WarehouseCarrier.builder()
.carrierId(row.carrierId.trim())
.nameEn(trimToNull(row.carrierNameEn))
.nameCn(trimToNull(row.carrierNameCn));
if (row.ownLogisticList != null) {
for (EdayunCarrierDtos.OwnLogistic l : row.ownLogisticList) {
if (l != null && hasText(l.logisticId)) {
b.logistic(new WarehouseCarrier.OwnLogistic(l.logisticId.trim(),
trimToNull(l.logisticName)));
}
}
}
return b.build();
}
/** 仓方仓 id 是数字;非数字/为空返回 null(不传 = 查所有服务商)。 */
static Long warehouseIdOf(String providerWarehouseId) {
if (!hasText(providerWarehouseId)) {
return null;
}
try {
return Long.valueOf(providerWarehouseId.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static String trimToNull(String v) {
return hasText(v) ? v.trim() : null;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

60
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java

@ -0,0 +1,60 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询客户自有物流服务(承运商)
* ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>一个文件对应一个接口。响应是「承运商 → 物流服务」两层:
* {@code carrierId / carrierNameEn / carrierNameCn} + 下属 {@code ownLogisticList}。</p>
*/
public final class EdayunCarrierDtos {
private EdayunCarrierDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListCarrierRequest {
/** 仓库 id;不传则查所有服务商。 */
public Long warehouseId;
/** 国家编码,如 {@code US}。 */
public String countryCode;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListCarrierResponse {
public Integer code;
public String msg;
public List<Carrier> data;
public String traceId;
}
/** 一个承运商。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Carrier {
/** 承运商 id。 */
public String carrierId;
/** 英文名,如 {@code FedEx}。 */
public String carrierNameEn;
/** 中文名。 */
public String carrierNameCn;
/**
* 下属物流服务。
*
* <p><b>文档写成对象,真机返回数组</b>——按 List 收,避免解析失败。</p>
*/
public List<OwnLogistic> ownLogisticList;
}
/** 承运商下的一个物流服务。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OwnLogistic {
public String logisticId;
public String logisticName;
}
}

160
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java

@ -0,0 +1,160 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 承运商清单({@code /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>重点:ownLogisticList 文档写成对象、真机是数组;carrierId 缺失的行跳过。</p>
*/
class EdayunCarrierTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx(String providerWarehouseId) {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, providerWarehouseId,
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-carrier", CLOCK);
}
private static RecordingTransport stub(String body) {
return RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_CARRIERS,
req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
@Test
void numericWarehouseIdIsSent() {
EdayunCarrierDtos.ListCarrierRequest req =
EdayunCarrierMapper.toRequest("2", null);
assertEquals(Long.valueOf(2L), req.warehouseId);
assertNull(req.countryCode);
}
/** 非数字仓 id 不下发——仓方会返回所有服务商。 */
@Test
void nonNumericWarehouseIdIsOmitted() {
assertNull(EdayunCarrierMapper.toRequest("USLA", null).warehouseId);
assertNull(EdayunCarrierMapper.toRequest(null, null).warehouseId);
}
@Test
void countryCodeIsTrimmed() {
assertEquals("US", EdayunCarrierMapper.toRequest("2", " US ").countryCode);
assertNull(EdayunCarrierMapper.toRequest("2", " ").countryCode);
}
// ------------------------------------------------------------ 响应
private static EdayunCarrierDtos.Carrier carrier() {
EdayunCarrierDtos.OwnLogistic l1 = new EdayunCarrierDtos.OwnLogistic();
l1.logisticId = "583";
l1.logisticName = "Collections by Tiktok - FedEx";
EdayunCarrierDtos.OwnLogistic l2 = new EdayunCarrierDtos.OwnLogistic();
l2.logisticId = "250";
l2.logisticName = "FedEx-express";
EdayunCarrierDtos.Carrier c = new EdayunCarrierDtos.Carrier();
c.carrierId = "1";
c.carrierNameEn = "FedEx";
c.carrierNameCn = "联邦快递";
c.ownLogisticList = java.util.Arrays.asList(l1, l2);
return c;
}
@Test
void mapsCarrierWithLogistics() {
WarehouseCarrier c = EdayunCarrierMapper.toCarrier(carrier());
assertEquals("1", c.carrierId());
assertEquals("FedEx", c.nameEn());
assertEquals("联邦快递", c.nameCn());
assertEquals("联邦快递", c.displayName());
assertEquals(2, c.logists().size());
assertEquals("583", c.logists().get(0).logisticId());
assertEquals("FedEx-express", c.logists().get(1).name());
}
/** 没有中文名时 displayName 退回英文名。 */
@Test
void displayNameFallsBackToEnglish() {
EdayunCarrierDtos.Carrier c = carrier();
c.carrierNameCn = null;
assertEquals("FedEx", EdayunCarrierMapper.toCarrier(c).displayName());
}
/** carrierId 缺失的行跳过——模型要求非空。 */
@Test
void carrierWithoutIdIsSkipped() {
EdayunCarrierDtos.Carrier bad = carrier();
bad.carrierId = " ";
List<WarehouseCarrier> list = EdayunCarrierMapper.toCarriers(
java.util.Arrays.asList(bad, carrier()));
assertEquals(1, list.size());
}
/** ownLogisticList 缺失或为空不抛异常。 */
@Test
void missingLogisticListYieldsEmpty() {
EdayunCarrierDtos.Carrier c = carrier();
c.ownLogisticList = null;
assertTrue(EdayunCarrierMapper.toCarrier(c).logists().isEmpty());
assertTrue(EdayunCarrierMapper.toCarriers(null).isEmpty());
assertTrue(EdayunCarrierMapper.toCarriers(
java.util.Collections.<EdayunCarrierDtos.Carrier>emptyList()).isEmpty());
}
@Test
void adapterQueriesCarriers() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\",\"data\":[{"
+ "\"carrierId\":\"1\",\"carrierNameEn\":\"FedEx\",\"carrierNameCn\":\"FedEx\","
+ "\"ownLogisticList\":[{\"logisticId\":\"250\",\"logisticName\":\"FedEx-express\"}]}]}");
List<WarehouseCarrier> list = new EdayunAdapter(transport, new JacksonJsonCodec())
.carrierDirectory(ctx("2"));
assertEquals(1, list.size());
assertEquals("FedEx", list.get(0).nameEn());
assertEquals(1, list.get(0).logists().size());
assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2"));
}
/** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */
@Test
void warehousesAreUnsupported() {
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec())
.warehouses(ctx("2")));
}
}

117
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java

@ -0,0 +1,117 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunCarrierMapper;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
import java.util.List;
import java.util.UUID;
/**
* 承运商清单联调探针:<b>只读</b>。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.carrier=true -Dtest=EdayunCarrierProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.carrier=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.country=US]
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.carrier", matches = "true")
class EdayunCarrierProbeTest {
private static final String BASE_URL = opt("edayun.probe.baseUrl", EdayunConstants.PR_BASE_URL);
private static final String CLIENT_ID = System.getProperty("edayun.probe.clientId", "");
private static final String CLIENT_SECRET = System.getProperty("edayun.probe.clientSecret", "");
private static final String APP_KEY = System.getProperty("edayun.probe.appKey", "");
private static final String APP_SECRET = System.getProperty("edayun.probe.appSecret", "");
private static final String WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final String COUNTRY = System.getProperty("edayun.probe.country", "");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeCarriers() {
EdayunCarrierDtos.ListCarrierRequest req = EdayunCarrierMapper.toRequest(
emptyToNull(WAREHOUSE_ID), emptyToNull(COUNTRY));
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_CARRIERS + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID) + " country=" + COUNTRY);
System.out.println("[request] " + new JacksonJsonCodec().toJson(req));
Assumptions.assumeTrue(CALL, "dry-run:未加 -Dedayun.probe.call=true,不实际调用");
Assumptions.assumeTrue(!CLIENT_ID.trim().isEmpty() && !CLIENT_SECRET.trim().isEmpty()
&& !APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(),
"真查需要 -Dedayun.probe.clientId / clientSecret / appKey / appSecret");
try {
WarehouseContext ctx = WarehouseContext.of("EDY-PROBE", WarehouseProvider.EDAYUN,
emptyToNull(WAREHOUSE_ID),
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder()
.appKey(APP_KEY).appSecret(APP_SECRET)
.clientId(CLIENT_ID).clientSecret(CLIENT_SECRET)
.build()),
"probe-" + UUID.randomUUID(), Clock.systemUTC());
EdayunAdapter adapter = new EdayunAdapter(
new OkHttpTransport("common-ecommerce/1.0.0 (edayun-probe)", 10_000, 60_000),
new JacksonJsonCodec());
List<WarehouseCarrier> carriers = adapter.carrierDirectory(ctx);
System.out.println("[OK] carriers=" + carriers.size());
for (WarehouseCarrier c : carriers) {
System.out.println(" " + c.carrierId() + " " + c.displayName()
+ " logistics=" + c.logists().size());
for (WarehouseCarrier.OwnLogistic l : c.logists()) {
System.out.println(" - " + l.logisticId() + " " + l.name());
}
}
} catch (RuntimeException e) {
String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": "
+ (msg.length() <= 800 ? msg : msg.substring(0, 800) + "…"));
if (e instanceof ChannelException) {
ChannelException ce = (ChannelException) e;
System.out.println(" platformCode=" + ce.platformCode()
+ " retryable=" + ce.retryable());
}
}
}
private static String opt(String name, String fallback) {
String value = System.getProperty(name, "");
String trimmed = value == null ? "" : value.trim();
return trimmed.isEmpty() ? fallback : trimmed;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}
Loading…
Cancel
Save