From 17ef1c574a6e96280561ad84ba7b357dde22bff6 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 16 Nov 2026 17:37:09 +0800 Subject: [PATCH] =?UTF-8?q?feat(edayun):=20=E5=AF=B9=E6=8E=A5=E5=AE=A2?= =?UTF-8?q?=E6=88=B7=E8=87=AA=E6=9C=89=E7=89=A9=E6=B5=81=E6=9C=8D=E5=8A=A1?= =?UTF-8?q?=EF=BC=88=E6=89=BF=E8=BF=90=E5=95=86=EF=BC=89=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /webApi/carrier/v1/listCarrierByWarehouse → List 返回两层:承运商(carrierId / 名称中英文)→ 物流服务(logisticId / 名称)。 自提单下单时 carrierName 可以填承运商名,也可以用某个物流服务的名字。 统一模型新增 WarehouseCarrier;能力挂在 WarehouseDirectoryCapable.carrierDirectory(门面 carrierDirectory())。 原有的 carriers()(List,只有码)保留不动——carrierDirectory 的 默认实现会把码包装成无名条目,能给出结构的仓覆盖它。 ownLogisticList 文档写成对象、真机返回数组,DTO 按 List 收。 真机(2026-11-16):仓 2 返回 11 个承运商(FedEx 下 12 个物流服务); 不传仓 22 个;countryCode=US 10 个。 顺带:易达云没有仓库列表接口,warehouses() 显式抛不支持, 不返回空列表——空列表和「没有仓」调用方分不清。DIRECTORY 能力位 目前只覆盖承运商这一半。 Co-Authored-By: Claude --- docs-warehouse/edayun/README.md | 53 +++++++ docs-warehouse/edayun/TODO.md | 3 + .../capability/WarehouseDirectoryCapable.java | 25 ++++ .../warehouse/model/WarehouseCarrier.java | 116 +++++++++++++++ .../warehouse/sdk/WarehouseOperations.java | 14 ++ .../common/ecommerce/edayun/EdayunConstants.java | 3 + .../ecommerce/edayun/adapter/EdayunAdapter.java | 48 ++++++- .../edayun/adapter/EdayunCarrierMapper.java | 83 +++++++++++ .../ecommerce/edayun/dto/EdayunCarrierDtos.java | 60 ++++++++ .../edayun/adapter/EdayunCarrierTest.java | 160 +++++++++++++++++++++ .../edayun/probe/EdayunCarrierProbeTest.java | 117 +++++++++++++++ 11 files changed, 680 insertions(+), 2 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index e88b358..a434f4d 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -29,6 +29,7 @@ | 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | | 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | | 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** | +| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) | | 其它业务接口 | ⬜ 等文档 | | 回调 | ⬜ 等文档 | | 真机验证 | ⬜ 等测试环境 | @@ -1210,6 +1211,58 @@ POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel `madeInChina` 与 `separation` 是易达云特有语义,统一模型没有对应概念 → 默认关。 +## 承运商清单(客户自有物流服务) + +``` +POST /webApi/carrier/v1/listCarrierByWarehouse → List +``` + +客户自有物流(自有物流 + 客户上传面单)下单时要用:`carrierName` 可以填承运商名, +也可以用某个下属物流服务的名字。 + +### 两层结构 + +``` +承运商(carrierId / carrierNameEn / carrierNameCn) + └── 物流服务(logisticId / logisticName) +``` + +统一模型新增 `WarehouseCarrier`(带 `logists()`),挂到 +`WarehouseDirectoryCapable.carrierDirectory(ctx)`,门面 `carrierDirectory()`。 + +原有的 `carriers()` 返回 `List`(只有码),保留不动; +`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` 只覆盖承运商这一半。 + ## 待确认(问易达云) | # | 要确认 | diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 62e89c4..bce14be 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -71,6 +71,9 @@ | 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) | | 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 | | 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) | +| 74 | 易达云**没有仓库列表接口** | `warehouses()` 显式拒绝;`DIRECTORY` 只覆盖承运商 | 宿主不能从仓方拉仓库清单 | +| 75 | 承运商接口的 `countryCode` 过滤统一模型没有对应字段 | 不下发 | 宿主想按国家筛承运商得用扩展方法 | +| 76 | `ownLogisticList` 文档写成对象、真机是数组 | DTO 按 List 收 | 无(已兼容) | | 70 | 箱唛的 `madeInChina` / `separation` 统一模型没有语义 | 默认关 | 需要打「Made in China」时得走扩展重载 | | 71 | 箱唛选箱条件(系统箱号 / SKU / 箱序号 / 客户箱号)统一模型没有 | 提供 `CaseSelection` 扩展重载 | 宿主想要部分箱打印必须用易达云专有 API | |---|---|---|---| diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java index 195c124..cbdfa19 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java +++ b/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( common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY); } + + /** + * 客户自有的承运商及其下属物流服务(带名称与 id 的完整结构)。 + * + *

与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 → + * 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。

+ * + *

默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。

+ * + * @return 承运商列表;仓方返回空时为 empty list(不是错误) + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code DIRECTORY} 或没有承运商接口 + */ + default List carrierDirectory( + WarehouseContext ctx) { + List out = + new java.util.ArrayList(); + for (String code : carriers(ctx)) { + out.add(common.ecommerce.warehouse.model.WarehouseCarrier.builder() + .carrierId(code) + .nameEn(code) + .build()); + } + return out; + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java new file mode 100644 index 0000000..dae5f59 --- /dev/null +++ b/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; + +/** + * 客户自有的承运商(物流服务商)及其下属物流服务。 + * + *

用于「客户自有物流 + 客户上传面单」的自提单场景:下单时 + * {@code carrierName} 填 {@link #nameEn()} 或某个 {@link OwnLogistic#name()}。

+ * + *

这是主数据,不是状态:同一仓的承运商清单很少变,适合宿主缓存。

+ */ +public final class WarehouseCarrier { + + /** 承运商 id(仓方码)。 */ + private final String carrierId; + /** 承运商英文名,如 {@code FedEx}。 */ + private final String nameEn; + /** 承运商中文名。 */ + private final String nameCn; + /** 该承运商下的物流服务;仓方未给时为空列表。 */ + private final List 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(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 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 logists = new ArrayList(); + + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 958b7f9..494b2df 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -315,6 +315,20 @@ public final class WarehouseOperations { } /** + * 仓方基础资料:客户自有的承运商及其下属物流服务。 + * + *

只读主数据。与 {@link #carriers()} 的区别是带名称与两层结构, + * 宿主可直接渲染成「承运商 → 物流服务」两级下拉。

+ */ + public List 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 时用账户配置的仓 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 index 9bf95e4..f9512f5 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java +++ b/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 = "/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"; 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 index 9e4d51d..d270915 100644 --- 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 @@ -4,6 +4,7 @@ import common.ecommerce.edayun.EdayunConstants; import common.ecommerce.edayun.auth.EdayunTokenClient; import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; import common.ecommerce.edayun.dto.EdayunBolDtos; +import common.ecommerce.edayun.dto.EdayunCarrierDtos; import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCancelReturnDtos; 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.TrackEvent; 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.WarehouseReturn; import common.ecommerce.warehouse.sdk.WarehouseAdapter; @@ -102,7 +106,7 @@ import java.util.List; public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable, OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable, - TrackingCapable, CaseMarkPrintCapable { + TrackingCapable, CaseMarkPrintCapable, WarehouseDirectoryCapable { /** 物流产品查询的适用业务: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.RETURN, WarehouseCapability.BOL, 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()); } + // ------------------------------------------------------------------ 承运商 + + /** + * 客户名下的仓库列表。 + * + *

易达云文档没给仓库列表接口,显式拒绝而不是返回空列表—— + * 空列表和「不支持」调用方分不清。

+ */ + @Override + public List warehouses(WarehouseContext ctx) { + throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.DIRECTORY); + } + + + /** + * 客户自有物流服务(承运商)清单 + * ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 + * + *

返回「承运商 → 物流服务」两层。{@code warehouseId} 只认数字; + * 非数字或为空时不下发,仓方会返回所有服务商。

+ * + *

真机(2026-11-16):仓 2 → 11 个承运商;不传仓 → 22 个; + * 只按国家 US → 10 个。{@code ownLogisticList} 实测是数组(文档写成对象)。

+ */ + @Override + public List 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 /** 发业务请求(自动取 token、算签名)。 */ private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) { diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java new file mode 100644 index 0000000..a6f3364 --- /dev/null +++ b/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})。 + * + *

响应 {@code ownLogisticList} 文档写成对象、真机返回数组,DTO 按 List 收。

+ */ +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 toCarriers( + List rows) { + if (rows == null || rows.isEmpty()) { + return Collections.emptyList(); + } + List out = new ArrayList(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(); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java new file mode 100644 index 0000000..073d1b6 --- /dev/null +++ b/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})。 + * + *

一个文件对应一个接口。响应是「承运商 → 物流服务」两层: + * {@code carrierId / carrierNameEn / carrierNameCn} + 下属 {@code ownLogisticList}。

+ */ +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 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; + /** + * 下属物流服务。 + * + *

文档写成对象,真机返回数组——按 List 收,避免解析失败。

+ */ + public List ownLogisticList; + } + + /** 承运商下的一个物流服务。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class OwnLogistic { + public String logisticId; + public String logisticName; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java new file mode 100644 index 0000000..2080f8b --- /dev/null +++ b/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})。 + * + *

重点:ownLogisticList 文档写成对象、真机是数组;carrierId 缺失的行跳过。

+ */ +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 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.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 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"))); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java new file mode 100644 index 0000000..5c9af9c --- /dev/null +++ b/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; + +/** + * 承运商清单联调探针:只读。 + * + *
+ * # 只看报文(不联网)
+ * 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]
+ * 
+ */ +@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 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); + } +}