Browse Source

feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表

四个接口:
- 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回,
  另三种要退货人地址或亚马逊单号,标准模型没有)
- 退货单详情 POST /webApi/rma/info/v1/getOrderDetail
- 取消退货单 POST /webApi/rma/info/v1/cancel
- 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList

统一模型侧:
- WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」),
  目前只有易达云实现,改动安全
- queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery),
  新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号)
- 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo),
  cancel 走幂等守卫

关键口径:
- 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message)
- 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false
- 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒
- 列表只认单个 status,多状态本地拒绝并提示拆查询
- 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报)
- 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜

真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表;
详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、
valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组,
DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 5 days ago
parent
commit
9e06b5873e
  1. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  2. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java
  3. 173
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java
  4. 72
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  5. 24
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  6. 165
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  7. 175
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
  8. 143
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
  9. 249
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
  10. 38
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java
  11. 223
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java
  12. 122
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java
  13. 138
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java
  14. 103
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java
  15. 109
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java
  16. 227
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java
  17. 205
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
  18. 249
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
  19. 163
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java
  20. 141
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java
  21. 141
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java

17
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java

@ -4,6 +4,7 @@ import common.ecommerce.shared.support.Page; @@ -4,6 +4,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
@ -36,7 +37,7 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -36,7 +37,7 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo);
/** 分页查退货单;命名原因同 {@link #getReturn}。 */
Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor);
Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query);
/**
* 按明细行设置检验后处理方式。<b>写操作</b>,幂等键
@ -44,8 +45,18 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -44,8 +45,18 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
*/
void process(WarehouseContext ctx, ReturnProcessCommand cmd);
/** 取消退货单;仅部分仓支持。 */
default void cancel(WarehouseContext ctx, String returnRequestNo) {
/**
* 取消退货单;仅部分仓支持。
*
* <p>与 {@link #create} 的区别:这个只需要仓侧退货单号({@code providerReturnId}),
* 因为多数仓的取消接口只认自己的 RMA 号。</p>
*
* @param providerReturnNo 仓侧退货单号(创建时返回的 {@code providerReturnId})
* @return {@code true} 取消成功;返回 {@code false} 表示仓方接受请求但拒绝取消
* (如已收货),具体原因在 {@code msg} 里——由适配器抛异常还是返回 false
* 由各仓决定,不统一的调用方应同时处理两种情况
*/
default boolean cancel(WarehouseContext ctx, String providerReturnNo) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.RETURN);
}

38
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java

@ -0,0 +1,38 @@ @@ -0,0 +1,38 @@
package common.ecommerce.warehouse.enums;
/**
* 退货单查询时「单号」的类型。
*
* <p>易达云列表接口的 {@code orderNoSearchType}:1 退货单号 / 2 出库单号 / 3 平台订单号。
* 用统一枚举表达,适配器不支持的类型要<b>显式拒绝</b>——静默按别的口径查会让结果对不上。</p>
*
* <p>与 {@link FeeQueryNoType} 不是一套:那边是费用查询的「仓侧订单号 / 平台单号 / 追踪号」,
* 这里有「退货单号」,语义不同,不复用。</p>
*/
public enum ReturnQueryNoType {
/** 退货单号(仓侧 RMA 号)。 */
PROVIDER_RETURN_NO(10, "退货单号"),
/** 出库单号(原始发货单号)。 */
OUTBOUND_ORDER_NO(20, "出库单号"),
/** 平台订单号。 */
PLATFORM_ORDER_NO(30, "平台订单号");
private final int code;
private final String label;
ReturnQueryNoType(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
}

173
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java

@ -0,0 +1,173 @@ @@ -0,0 +1,173 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import java.time.Instant;
import java.util.Collections;
import java.util.List;
/**
* 退货单查询条件(单次查询,不推进水位线)。
*
* <p>各仓支持的维度不同:易达云支持时间窗 + 单号 + 仓库 + 状态 + SKU,
* 不支持的维度由适配器<b>显式拒绝</b>,不静默忽略——忽略一个过滤条件会让结果对不上。</p>
*/
public final class ReturnQuery {
private final Instant createdAfter;
private final Instant createdBefore;
private final String orderNo;
private final ReturnQueryNoType orderNoType;
private final String trackingNo;
private final String warehouseCode;
private final List<ReturnStatus> statuses;
private final String providerSku;
private final int pageSize;
private final String cursor;
private ReturnQuery(Builder b) {
if (b.createdAfter != null && b.createdBefore != null
&& !b.createdAfter.isBefore(b.createdBefore)) {
throw new IllegalArgumentException("createdAfter must be before createdBefore");
}
this.createdAfter = b.createdAfter;
this.createdBefore = b.createdBefore;
this.orderNo = b.orderNo;
this.orderNoType = b.orderNoType;
this.trackingNo = b.trackingNo;
this.warehouseCode = b.warehouseCode;
this.statuses = Collections.unmodifiableList(new java.util.ArrayList<ReturnStatus>(b.statuses));
this.providerSku = b.providerSku;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 创建时间窗起点(UTC);null 表示不限。 */
public Instant createdAfter() {
return createdAfter;
}
/** 创建时间窗终点(UTC)。 */
public Instant createdBefore() {
return createdBefore;
}
public boolean hasCreatedRange() {
return createdAfter != null && createdBefore != null;
}
/** 单号;配合 {@link #orderNoType()}。 */
public String orderNo() {
return orderNo;
}
/** 单号类型;null 由适配器按自己的默认口径解释。 */
public ReturnQueryNoType orderNoType() {
return orderNoType;
}
/** 跟踪号。 */
public String trackingNo() {
return trackingNo;
}
/** 仓编码;适配器优先用账户配置的仓方 id。 */
public String warehouseCode() {
return warehouseCode;
}
/** 状态过滤;空表示不过滤。 */
public List<ReturnStatus> statuses() {
return statuses;
}
/** 仓侧 SKU。 */
public String providerSku() {
return providerSku;
}
public int pageSize() {
return pageSize;
}
/** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
public static final class Builder {
private Instant createdAfter;
private Instant createdBefore;
private String orderNo;
private ReturnQueryNoType orderNoType;
private String trackingNo;
private String warehouseCode;
private final List<ReturnStatus> statuses = new java.util.ArrayList<ReturnStatus>();
private String providerSku;
private int pageSize = 100;
private String cursor;
public Builder createdAfter(Instant v) {
this.createdAfter = v;
return this;
}
public Builder createdBefore(Instant v) {
this.createdBefore = v;
return this;
}
/** 单号;配合 {@link #orderNoType}。 */
public Builder orderNo(String v) {
this.orderNo = v;
return this;
}
public Builder orderNoType(ReturnQueryNoType v) {
this.orderNoType = v;
return this;
}
public Builder trackingNo(String v) {
this.trackingNo = v;
return this;
}
public Builder warehouseCode(String v) {
this.warehouseCode = v;
return this;
}
public Builder status(ReturnStatus v) {
if (v != null) {
this.statuses.add(v);
}
return this;
}
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public ReturnQuery build() {
return new ReturnQuery(this);
}
}
}

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

@ -4,54 +4,53 @@ import common.ecommerce.shared.audit.CallObserver; @@ -4,54 +4,53 @@ import common.ecommerce.shared.audit.CallObserver;
import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.shared.idempotency.IdempotencyGuard;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.DestructionCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.ChannelRecommendQuery;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.model.DestructionCommand;
import common.ecommerce.warehouse.model.DestructionOrder;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.LabelPrintTask;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.SkuLabelCommand;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import java.time.Instant;
import java.util.List;
import java.util.Map;
/**
* 单个仓的操作入口:{@code sdk.warehouses(code, conn).outbound()} 等。
@ -324,6 +323,8 @@ public final class WarehouseOperations { @@ -324,6 +323,8 @@ public final class WarehouseOperations {
() -> ((LogisticsProductCapable) adapter).products(ctx, warehouseCode));
}
/** 费用视图。 */
public FeeView fees() {
return new FeeView();
@ -588,12 +589,21 @@ public final class WarehouseOperations { @@ -588,12 +589,21 @@ public final class WarehouseOperations {
() -> ((WarehouseReturnCapable) adapter).getReturn(ctx, returnRequestNo));
}
public Page<WarehouseReturn> query(String cursor) {
/**
* 分页查退货单。
*
* <p>各仓支持的过滤维度不同,不支持的由适配器显式拒绝;传空条件时
* 适配器要么用自己的默认窗口(如易达云默认近一个月),要么拒绝。</p>
*/
public Page<WarehouseReturn> query(ReturnQuery query) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.return.query",
CallSupport.params("cursor", cursor),
CallSupport.params("cursor", query.cursor(),
"orderNo", query.orderNo(),
"warehouseCode", query.warehouseCode(),
"statusCount", query.statuses().size()),
p -> p.size(),
() -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, cursor));
() -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, query));
}
/**
@ -622,6 +632,28 @@ public final class WarehouseOperations { @@ -622,6 +632,28 @@ public final class WarehouseOperations {
},
c -> null));
}
/**
* 取消退货单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + providerReturnNo + "cancel"}。
*
* <p>只传仓侧退货单号——多数仓的取消接口只认自己的 RMA 号。</p>
*
* @return {@code true} 取消成功
*/
public boolean cancel(final String providerReturnNo) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
if (guard == null) {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter;
common.ecommerce.shared.idempotency.WriteResult<Boolean> result = guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
providerReturnNo, "cancel"),
() -> capable.cancel(ctx, providerReturnNo),
ok -> Boolean.TRUE.equals(ok) ? "true" : null);
return result.alreadyCompleted() || Boolean.TRUE.equals(result.value());
}
}
/** 费用视图。 */

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

@ -79,6 +79,30 @@ public final class EdayunConstants { @@ -79,6 +79,30 @@ public final class EdayunConstants {
/** 费用试算 / 预估({@code POST /webApi/estimate/v1/trial})。 */
public static final String PATH_FEE_ESTIMATE = "/webApi/estimate/v1/trial";
/** 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。 */
public static final String PATH_RETURN_CREATE = "/webApi/rma/info/v1/saveAndPublish";
/** 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。 */
public static final String PATH_RETURN_DETAIL = "/webApi/rma/info/v1/getOrderDetail";
/** 取消退货单({@code POST /webApi/rma/info/v1/cancel})。 */
public static final String PATH_RETURN_CANCEL = "/webApi/rma/info/v1/cancel";
/** 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。 */
public static final String PATH_RETURN_LIST = "/webApi/rma/info/v1/selectRmaInfoList";
/** 查询 BOL 信息({@code POST /webApi/fbaOrder/v1/getOrderBolList})。 */
public static final String PATH_BOL_LIST = "/webApi/fbaOrder/v1/getOrderBolList";
/** 根据仓库查询物流产品列表({@code POST /webApi/order/listByLogisticProductHasPerm})。 */
public static final String PATH_LOGISTICS_PRODUCTS = "/webApi/order/listByLogisticProductHasPerm";
/** 查询订单物流轨迹({@code POST /webApi/track/getTrackInfoList})。 */
public static final String PATH_TRACK = "/webApi/track/getTrackInfoList";
/** 打印条码({@code POST /webApi/skuInfo/v2/printBarcode})。 */
public static final String PATH_BARCODE_PRINT = "/webApi/skuInfo/v2/printBarcode";
/** 物流增值:签收服务。 */
public static final String ADD_SERVICE_SIGNATURE = "is_signature";

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

@ -2,9 +2,10 @@ package common.ecommerce.edayun.adapter; @@ -2,9 +2,10 @@ package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunAccountFlowDtos;
import common.ecommerce.edayun.dto.EdayunCancelDtos;
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunCreateProductDtos;
import common.ecommerce.edayun.dto.EdayunFeeEstimateDtos;
import common.ecommerce.edayun.dto.EdayunGetOrderDtos;
@ -14,6 +15,9 @@ import common.ecommerce.edayun.dto.EdayunInboundQueryDtos; @@ -14,6 +15,9 @@ import common.ecommerce.edayun.dto.EdayunInboundQueryDtos;
import common.ecommerce.edayun.dto.EdayunInventoryDtos;
import common.ecommerce.edayun.dto.EdayunOrderCostDtos;
import common.ecommerce.edayun.dto.EdayunRentDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.edayun.enums.EdayunCancelStatus;
import common.ecommerce.edayun.http.EdayunRequestFactory;
import common.ecommerce.http.HttpRequest;
@ -33,6 +37,7 @@ import common.ecommerce.warehouse.capability.WarehouseFeeCapable; @@ -33,6 +37,7 @@ import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.LabelMode;
@ -40,8 +45,8 @@ import common.ecommerce.warehouse.enums.WarehouseCapability; @@ -40,8 +45,8 @@ import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
@ -57,6 +62,10 @@ import common.ecommerce.warehouse.model.OutboundQuery; @@ -57,6 +62,10 @@ import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -76,7 +85,7 @@ import java.util.List; @@ -76,7 +85,7 @@ import java.util.List;
*/
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable,
InboundCapable {
InboundCapable, WarehouseReturnCapable {
private final HttpTransport transport;
private final JacksonJsonCodec json;
@ -128,7 +137,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -128,7 +137,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND);
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND,
WarehouseCapability.RETURN);
}
/**
@ -686,6 +696,153 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -686,6 +696,153 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
EdayunFeeEstimateMapper.toResult(parsed, ctx.warehouseCode()));
}
// ------------------------------------------------------------------ 退货
/**
* 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>统一模型只对应「自行退回」({@code returnType=2}):它要求退货运单号,
* 正好是买家自己寄回的场景。未妥投 / 返邮 / FBA 退回要退货人地址或亚马逊单号,
* 标准模型没有——见 TODO。</p>
*
* <p>与运去哪不同,<b>响应 {@code data} 就是仓侧退货单号</b>,可直接落
* {@code providerReturnId};状态不回,只能后续人工或回调补。</p>
*/
@Override
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) {
EdayunReturnDtos.SaveReturnRequest body =
EdayunReturnMapper.toRequest(cmd, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CREATE, bodyJson,
"warehouse.return.create");
EdayunReturnDtos.SaveReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDtos.SaveReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.create");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun return create returned no return order no")
.operation("warehouse.return.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunReturnMapper.toCreated(cmd, parsed.data.trim(), ctx.warehouseCode());
}
/**
* 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>{@code returnRequestNo} 可以是 OMS 退货单号,也可以是仓方 RMA 号——
* 仓方只认 {@code rmaCode},所以<b>非 RMA 号要先有创建时拿到的
* {@code providerReturnId}</b>。这里原样传,查不到由仓方报错。</p>
*
* <p>明细行优先取仓的检验结果({@code checkList}),没有才退回预报
* ({@code skuList})——对账以实际收到为准。</p>
*/
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
EdayunReturnDetailDtos.GetReturnRequest body =
EdayunReturnDetailMapper.toRequest(returnRequestNo);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_DETAIL, bodyJson,
"warehouse.return.get");
EdayunReturnDetailDtos.GetReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDetailDtos.GetReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.get");
if (parsed.data == null) {
// 单号不存在时仓方可能回 code=200 + data=null,按「查不到」返回 null
return null;
}
return EdayunReturnDetailMapper.toReturn(parsed.data, ctx.warehouseCode(),
body.rmaCode);
}
/**
* 取消退货单({@code POST /webApi/rma/info/v1/cancel})。
*
* <p>只认仓方 {@code rmaCode},所以传的必须是创建时拿到的
* {@code providerReturnId}——用 OMS 单号会被仓方查不到。</p>
*
* <p>响应 {@code data=true} 才算成功。{@code code=200} + {@code data=false}
* 是仓方拒绝(如已收货),这里抛异常而不是静默返回 false——
* 取消退货是状态变更,调用方必须知道没成功。</p>
*/
@Override
public boolean cancel(WarehouseContext ctx, String providerReturnNo) {
if (!hasText(providerReturnNo)) {
throw new IllegalArgumentException(
"edayun return cancel needs the provider return no (rmaCode)");
}
EdayunCancelReturnDtos.CancelReturnRequest body =
new EdayunCancelReturnDtos.CancelReturnRequest();
body.rmaCode = providerReturnNo.trim();
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CANCEL, bodyJson,
"warehouse.return.cancel");
EdayunCancelReturnDtos.CancelReturnResponse parsed =
json.fromJson(resp.body(), EdayunCancelReturnDtos.CancelReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.cancel");
if (parsed.data == null || !parsed.data) {
throw WarehouseException.builder()
.message("edayun return cancel rejected: " + parsed.msg)
.operation("warehouse.return.cancel")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return true;
}
/**
* 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>只回单头,没有明细行与退货人地址;要明细请用 {@link #getReturn}。</p>
*
* <p>时间窗不传时仓方默认近一个月——这一点由仓方兜底,本地不补默认值,
* 免得「没给时间窗」和「显式要近一个月」两种情况被混掉。</p>
*/
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) {
int pageNum = EdayunRmaListMapper.pageNumber(query.cursor());
EdayunRmaListDtos.SelectRmaListRequest body = EdayunRmaListMapper.toRequest(
query, ctx.providerWarehouseId(), ctx.zone(), pageNum);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_LIST, bodyJson,
"warehouse.return.query");
EdayunRmaListDtos.SelectRmaListResponse parsed =
json.fromJson(resp.body(), EdayunRmaListDtos.SelectRmaListResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.query");
return EdayunRmaListMapper.toPage(parsed, ctx.warehouseCode(), pageNum, body.pageSize);
}
/**
* 按明细行设置检验后处理方式。
*
* <p>需要仓侧明细行 id,而查退货单的接口还没有——无法构造,显式拒绝。</p>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN_DISPOSITION);
}
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {

175
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java

@ -0,0 +1,175 @@ @@ -0,0 +1,175 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.enums.EdayunRmaStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseReturn;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单详情映射({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>响应七块,统一模型只承载前面几块:单头、明细行、检验 / 上架数量。
* 退货人地址、预报包裹尺寸、包裹状态这些只在 DTO 里——标准模型没有对应字段。</p>
*
* <p><b>明细行取 {@code checkList} 优先,回落 {@code skuList}</b>:
* {@code skuList} 是预报(买家要退什么),{@code checkList} 是仓实际收到的
* (含检验数量与异常原因)。对账要用实际收到的,没有检验记录才退回预报。</p>
*/
public final class EdayunReturnDetailMapper {
private EdayunReturnDetailMapper() {
}
/** 查询请求。 */
public static EdayunReturnDetailDtos.GetReturnRequest toRequest(String rmaCode) {
if (rmaCode == null || rmaCode.trim().isEmpty()) {
throw new IllegalArgumentException("edayun needs a rmaCode to query the return detail");
}
EdayunReturnDetailDtos.GetReturnRequest req =
new EdayunReturnDetailDtos.GetReturnRequest();
req.rmaCode = rmaCode.trim();
return req;
}
/** 详情 → 统一退货单;没有请求单号可兜底时用响应里的 RMA 号。 */
public static WarehouseReturn toReturn(EdayunReturnDetailDtos.ReturnDetail detail,
String warehouseCode) {
return toReturn(detail, warehouseCode, null);
}
/**
* 详情 → 统一退货单。
*
* @param warehouseCode 回退用的 OMS 仓编码(响应只有仓名与数字 id)
* @param requestedRmaCode 请求时用的退货单号;详情为空时用它兜底,
* 保证 {@code returnRequestNo} 不为空
*/
public static WarehouseReturn toReturn(EdayunReturnDetailDtos.ReturnDetail detail,
String warehouseCode, String requestedRmaCode) {
EdayunReturnDetailDtos.BasicInfo basic = detail == null ? null : detail.basicInfo;
WarehouseReturn.Builder builder = WarehouseReturn.builder()
// 没有预报单号时用 RMA 号兜底,returnRequestNo 不能为空
.returnRequestNo(basic == null ? trimToNull(requestedRmaCode)
: firstNonBlank(basic.relationNo, basic.rmaCode, requestedRmaCode))
.providerReturnId(basic == null ? trimToNull(requestedRmaCode) : basic.rmaCode)
.warehouseCode(firstNonBlank(
basic == null ? null : basic.warehouseName, warehouseCode))
.orderRef(basic == null ? null : basic.relationNo)
.type(basic == null ? null : basic.returnTypeName)
.status(EdayunRmaStatus.toCore(
basic == null ? null : basic.status,
basic == null ? null : basic.statusName))
// rawStatus 保留中文名:码表没给,码值单独进 type 之外没地方放
.rawStatus(basic == null ? null
: firstNonBlank(basic.statusName, basic.status == null ? null
: String.valueOf(basic.status)))
.createdAt(basic == null ? null : instantOf(basic.createTime))
.sourceProvider(WarehouseProvider.EDAYUN);
builder.lines(toLines(detail));
return builder.build();
}
/**
* 明细行:检验结果优先,没有检验记录时退回预报 SKU。
*
* <p>两边的字段名不同({@code skuNum} 在 skuList 是 string、在 checkList 是 number),
* 分开映射,不要合并成一个循环。</p>
*/
static List<WarehouseReturn.ReturnLine> toLines(EdayunReturnDetailDtos.ReturnDetail detail) {
List<WarehouseReturn.ReturnLine> out = new ArrayList<WarehouseReturn.ReturnLine>();
if (detail == null) {
return out;
}
if (detail.checkList != null && !detail.checkList.isEmpty()) {
for (EdayunReturnDetailDtos.CheckLine line : detail.checkList) {
if (line == null) {
continue;
}
WarehouseReturn.ReturnLine.Builder rb = WarehouseReturn.ReturnLine.builder()
.providerSku(trimToNull(line.skuCode))
.quantity(line.skuNum == null ? 0 : line.skuNum)
.suggestedDisposition(line.commandName)
.remark(joinNonBlank(line.exceptionReasonName, line.remark));
addPictures(rb, line.picUrls);
out.add(rb.build());
}
return out;
}
if (detail.skuList != null) {
for (EdayunReturnDetailDtos.SkuLine line : detail.skuList) {
if (line == null) {
continue;
}
WarehouseReturn.ReturnLine.Builder rb = WarehouseReturn.ReturnLine.builder()
.providerSku(trimToNull(line.skuCode))
.quantity(line.skuNum == null ? 0 : line.skuNum)
.suggestedDisposition(line.commandName)
.newSku(trimToNull(line.shelveSkuCode))
.remark(trimToNull(line.exceptionReasonName));
addPictures(rb, line.picUrls);
out.add(rb.build());
}
}
return out;
}
private static void addPictures(WarehouseReturn.ReturnLine.Builder builder,
List<String> urls) {
if (urls == null) {
return;
}
for (String raw : urls) {
for (String url : splitUrls(raw)) {
builder.pictureUrl(url);
}
}
}
/** 毫秒时间戳 → Instant;0 与 null 都当未给。 */
static Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
/** 图片地址可能是逗号拼接的多个 URL。 */
static List<String> splitUrls(String raw) {
List<String> out = new ArrayList<String>();
if (raw == null || raw.trim().isEmpty()) {
return out;
}
for (String part : raw.split(",")) {
String v = part.trim();
if (!v.isEmpty()) {
out.add(v);
}
}
return out;
}
private static String joinNonBlank(String a, String b) {
String first = trimToNull(a);
String second = trimToNull(b);
if (first == null) {
return second;
}
return second == null ? first : first + " " + second;
}
private static String trimToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String firstNonBlank(String... values) {
for (String v : values) {
String t = trimToNull(v);
if (t != null) {
return t;
}
}
return null;
}
}

143
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java

@ -0,0 +1,143 @@ @@ -0,0 +1,143 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单映射({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>统一模型只能表达「自行退回」这一种退货方式({@link ReturnCommand} 强制要求
* 退货运单号),所以 {@code returnType} 固定 2。未妥投退回 / 返邮退回 / FBA 退回
* 需要退货人地址或亚马逊单号,标准模型没有对应字段——见 docs-warehouse/edayun/TODO.md。</p>
*
* <p><b>响应 {@code data} 就是退货单号</b>(如 {@code RMA2411053149}),
* 与运去哪不同,这里能直接拿到仓侧单号。</p>
*/
public final class EdayunReturnMapper {
/**
* 退货方式:自行退回。
*
* <p>0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。统一模型有退货运单号,
* 正好对应「买家自己寄回」。</p>
*/
static final int RETURN_TYPE_SELF_SHIP = 2;
/** 处理指令:上架。 */
static final int COMMAND_PUT_AWAY = 1;
/** 处理指令:销毁。 */
static final int COMMAND_DESTROY = 2;
private EdayunReturnMapper() {
}
/**
* 统一命令 → 创建退货单请求。
*
* @param providerWarehouseId 仓方仓 id;数字进 {@code warehouseId},
* 非数字进 {@code warehouseCode}
*/
public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd,
String providerWarehouseId) {
EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest();
req.returnType = RETURN_TYPE_SELF_SHIP;
// 关联单号:仓方按它找原出库单,优先用销售订单号
req.relationNo = firstNonBlank(cmd.saleOrderNo(), cmd.returnRequestNo());
req.carrierName = cmd.carrierCode();
req.trackingNo = cmd.returnTrackingNo();
req.customerRemark = cmd.remark();
applyWarehouse(req, providerWarehouseId, cmd.warehouseId());
req.skus = toSkus(cmd.lines());
return req;
}
/**
* 仓:{@code warehouseId} 数字优先,否则 {@code warehouseCode}。
*
* <p>命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。</p>
*/
private static void applyWarehouse(EdayunReturnDtos.SaveReturnRequest req,
String providerWarehouseId, String cmdWarehouseId) {
String raw = firstNonBlank(cmdWarehouseId, providerWarehouseId);
if (raw == null) {
// 两者都不给时仓方会用关联单号的仓库,允许为空
return;
}
Long id = numericOrNull(raw);
if (id != null) {
req.warehouseId = id;
} else {
req.warehouseCode = raw;
}
}
private static List<EdayunReturnDtos.SkuItem> toSkus(
List<ReturnCommand.ReturnCommandLine> lines) {
List<EdayunReturnDtos.SkuItem> out =
new ArrayList<EdayunReturnDtos.SkuItem>(lines.size());
for (ReturnCommand.ReturnCommandLine line : lines) {
EdayunReturnDtos.SkuItem item = new EdayunReturnDtos.SkuItem();
item.skuCode = line.providerSku();
item.skuNum = line.quantity();
item.command = commandOf(line.dealMethod());
out.add(item);
}
return out;
}
/**
* 统一处理方式 → 易达云处理指令。
*
* <p><b>只有「销毁」能确定</b>({@code 2})。其余三种统一取值在易达云都归「上架」——
* 客户自提 / 拍照确认 / 仓库确认都要先入库再处理,所以下发上架。
* 易达云的完整码表未拿到,见 TODO。</p>
*/
static Integer commandOf(ReturnDealMethod method) {
if (method == null) {
return null;
}
return method == ReturnDealMethod.DESTROY ? COMMAND_DESTROY : COMMAND_PUT_AWAY;
}
/**
* 创建成功 → 统一退货单。
*
* <p>仓侧单号直接来自响应 {@code data};接口不回状态,所以 {@link ReturnStatus#UNKNOWN}。</p>
*/
public static WarehouseReturn toCreated(ReturnCommand cmd, String providerReturnNo,
String warehouseCode) {
return WarehouseReturn.builder()
.returnRequestNo(cmd.returnRequestNo())
.providerReturnId(providerReturnNo)
.warehouseCode(warehouseCode)
.orderRef(cmd.saleOrderNo())
.status(ReturnStatus.UNKNOWN)
.sourceProvider(WarehouseProvider.EDAYUN)
.build();
}
private static Long numericOrNull(String v) {
try {
return Long.valueOf(v.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
return b != null && !b.trim().isEmpty() ? b.trim() : null;
}
}

249
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java

@ -0,0 +1,249 @@ @@ -0,0 +1,249 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.edayun.enums.EdayunRmaStatus;
import common.ecommerce.warehouse.enums.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.shared.support.Page;
import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单列表映射
* ({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>与详情接口的区别:列表只回单头,没有明细行、没有退货人地址。
* 需要明细要走 {@code getOrderDetail}。</p>
*
* <p>时间参数是<b>字符串</b> {@code yyyy-MM-dd HH:mm:ss},且按仓方时区解释
* ({@code WarehouseContext.zone()}),不是毫秒时间戳。</p>
*/
public final class EdayunRmaListMapper {
/** 单页上限。 */
static final int MAX_PAGE_SIZE = 200;
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private EdayunRmaListMapper() {
}
/**
* 统一查询条件 → 列表请求。
*
* @param providerWarehouseId 仓方数字仓 id;数字进 {@code warehouseId}
* @param zone 解释时间窗的时区(仓方时区)
* @param pageNum 页码,从 1 开始
*/
public static EdayunRmaListDtos.SelectRmaListRequest toRequest(ReturnQuery query,
String providerWarehouseId,
ZoneId zone, int pageNum) {
EdayunRmaListDtos.SelectRmaListRequest req = new EdayunRmaListDtos.SelectRmaListRequest();
req.pageNum = pageNum;
req.pageSize = pageSize(query.pageSize());
if (query.hasCreatedRange()) {
ZoneId z = zone == null ? java.time.ZoneOffset.UTC : zone;
req.createTimeStart = TIME.format(query.createdAfter().atZone(z));
req.createTimeEnd = TIME.format(query.createdBefore().atZone(z));
}
if (hasText(query.orderNo())) {
// orderNos 必须配合 orderNoSearchType;不传类型时默认按退货单号查
req.orderNos = query.orderNo().trim();
req.orderNoSearchType = orderNoSearchTypeOf(query.orderNoType());
}
if (hasText(query.trackingNo())) {
req.trackingNos = query.trackingNo().trim();
}
Long warehouseId = warehouseIdOf(providerWarehouseId);
if (warehouseId != null) {
req.warehouseId = warehouseId;
} else if (hasText(query.warehouseCode())) {
req.warehouseCode = query.warehouseCode().trim();
}
if (hasText(query.providerSku())) {
req.skuCode = query.providerSku().trim();
}
// 接口只支持单个状态值,多状态由调用方拆成多次查询
if (query.statuses().size() > 1) {
throw new IllegalArgumentException(
"edayun return list accepts at most one status, got " + query.statuses().size()
+ "; split into multiple queries");
}
if (query.statuses().size() == 1) {
req.status = statusOf(query.statuses().get(0));
}
return req;
}
/**
* 单号类型 → 易达云 {@code orderNoSearchType}。
*
* <p>null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。</p>
*
* @throws IllegalArgumentException 不支持的类型
*/
static Integer orderNoSearchTypeOf(ReturnQueryNoType type) {
if (type == null) {
return 1;
}
switch (type) {
case PROVIDER_RETURN_NO:
return 1;
case OUTBOUND_ORDER_NO:
return 2;
case PLATFORM_ORDER_NO:
return 3;
default:
throw new IllegalArgumentException(
"edayun return list does not support orderNoType: " + type);
}
}
/**
* 统一状态 → 易达云 {@code status}。
*
* <p>码表来自文档原文:{@code 0 待发布 / 1 待仓库签收 / 2 搁置中 / 3 仓库签收 /
* 4 处理中-仓库处理 / 5 已处理 / 6 处理中-等待指令 / 7 物流签收 / -1 已取消}。</p>
*
* <p>统一枚举里没有「搁置中」「等待指令」这类细分,所以查询时<b>只能按大类取一个代表值</b>;
* 认不出的返回 null(不过滤),由调用方承担后果——见 TODO。</p>
*/
static Integer statusOf(ReturnStatus status) {
if (status == null) {
return null;
}
switch (status) {
case DRAFT:
return 0;
case PENDING_REVIEW:
// 仓方没有「待审核」,最接近的是「待发布」
return 0;
case RETURNING:
// 退货中:还没到仓,取「待仓库签收」
return 1;
case PENDING_RECEIPT:
return 1;
case COMPLETED:
// 已处理(含已上架)
return 5;
case CLOSED:
return -1;
default:
return null;
}
}
/** 一行 → 统一退货单(只有单头,没有明细)。 */
public static WarehouseReturn toReturn(EdayunRmaListDtos.RmaRow row, String fallbackWarehouseCode) {
if (row == null) {
return null;
}
return WarehouseReturn.builder()
// 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号
.returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode))
.providerReturnId(row.rmaCode)
// 文档响应示例没有 warehouseCode,但真机会返回,优先用它
.warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName,
fallbackWarehouseCode))
.orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode))
.type(row.returnTypeName)
.status(EdayunRmaStatus.toCore(row.status, row.statusName))
.rawStatus(firstNonBlank(row.statusName,
row.status == null ? null : String.valueOf(row.status)))
// 列表里签收时间比创建时间更能反映「退货进度」,但统一模型只留创建时间
.createdAt(instantOf(row.createTime))
.sourceProvider(WarehouseProvider.EDAYUN)
.build();
}
/** 响应 → 分页。 */
public static Page<WarehouseReturn> toPage(EdayunRmaListDtos.SelectRmaListResponse response,
String fallbackWarehouseCode,
int currentPage, int pageSize) {
if (response == null || response.rows == null || response.rows.isEmpty()) {
return Page.empty();
}
List<WarehouseReturn> out = new ArrayList<WarehouseReturn>(response.rows.size());
for (EdayunRmaListDtos.RmaRow row : response.rows) {
WarehouseReturn ret = toReturn(row, fallbackWarehouseCode);
if (ret != null) {
out.add(ret);
}
}
return Page.of(out, nextCursor(response.total, currentPage, pageSize, out.size()));
}
/**
* 有下一页时返回下一页页码。
*
* <p>文档写明 {@code total} 是总数据量(行数),优先用它判断;
* 缺失时退回「本页是否满页」。</p>
*/
static String nextCursor(Long total, int currentPage, int pageSize, int fetched) {
boolean more = total != null
? (long) currentPage * pageSize < total
: fetched >= pageSize;
return more ? String.valueOf(currentPage + 1) : null;
}
/** 游标是字符串化的页码。 */
static int pageNumber(String cursor) {
if (!hasText(cursor)) {
return 1;
}
try {
int v = Integer.parseInt(cursor.trim());
return v > 0 ? v : 1;
} catch (NumberFormatException e) {
return 1;
}
}
/** 每页条数:默认 100,上限 200。 */
static int pageSize(int requested) {
if (requested <= 0) {
return 100;
}
return Math.min(requested, MAX_PAGE_SIZE);
}
/** 仓方仓 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 Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
private static String firstNonBlank(String... values) {
for (String v : values) {
if (hasText(v)) {
return v.trim();
}
}
return null;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

38
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java

@ -0,0 +1,38 @@ @@ -0,0 +1,38 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 易达云报文结构:取消退货单
* ({@code POST /webApi/rma/info/v1/cancel})。
*
* <p>一个文件对应一个接口。请求只有一个 {@code rmaCode};响应 {@code data}
* 是<b>布尔值</b>({@code true} 成功),不是单号——与创建接口不同。</p>
*/
public final class EdayunCancelReturnDtos {
private EdayunCancelReturnDtos() {
}
/** 取消请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CancelReturnRequest {
/** 退货单号(易达云的 RMA 号)。必填。 */
public String rmaCode;
}
/** 取消响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CancelReturnResponse {
public Integer code;
public String msg;
/**
* 结果,{@code true} 表示取消成功。
*
* <p><b>注意</b>:仓方可能回 {@code code=200} + {@code data=false}
* (业务拒绝),所以两个都要判。</p>
*/
public Boolean data;
public String traceId;
}
}

223
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java

@ -0,0 +1,223 @@ @@ -0,0 +1,223 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:获取退货单详情
* ({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。</p>
*
* <p>响应按业务分组,七块内容:</p>
* <ul>
* <li>{@code basicInfo} —— 单头(状态、关联单号、仓库、退货方式、创建时间)</li>
* <li>{@code logisticsInfo} —— 退货人地址与返邮信息</li>
* <li>{@code shipmentParcelList} —— 预报的包裹尺寸重量</li>
* <li>{@code skuList} —— 预报的退货 SKU</li>
* <li>{@code packageList} —— 包裹 / 跟踪号及状态</li>
* <li>{@code checkList} —— 仓收货检验结果</li>
* <li>{@code shelfList} —— 实际上架结果</li>
* </ul>
*/
public final class EdayunReturnDetailDtos {
private EdayunReturnDetailDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetReturnRequest {
/** 退货单号(易达云的 RMA 号)。必填。 */
public String rmaCode;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetReturnResponse {
public Integer code;
public String msg;
public ReturnDetail data;
public String traceId;
}
/** 退货单详情。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ReturnDetail {
public BasicInfo basicInfo;
public LogisticsInfo logisticsInfo;
public List<ShipmentParcel> shipmentParcelList;
public List<SkuLine> skuList;
public List<PackageLine> packageList;
public List<CheckLine> checkList;
public List<ShelfLine> shelfList;
}
/** 单头。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BasicInfo {
/** 退货单号。 */
public String rmaCode;
/** 状态码;码表见 {@code EdayunRmaStatus}。 */
public Integer status;
/** 状态中文名。 */
public String statusName;
/** 关联单号(EDA 单号或客户单号)。 */
public String relationNo;
/** 预报品类数 / 实际品类数 / 预报商品数 / 实际商品数。 */
public Integer forecastCategoryNum;
public Integer productCategoryNum;
public Integer forecastProductNum;
public Integer productNum;
public Long warehouseId;
public String warehouseName;
/** 退货方式:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
public String returnTypeName;
/** 退货原因,字典 {@code wms_rma_return_reason}。 */
public Integer returnReason;
public String returnReasonName;
/** 创建时间(毫秒)。 */
public Long createTime;
public String carrierName;
/** 包裹状态,字典 {@code wms_rma_claim_package_status}。 */
public Integer packageStatus;
public String packageStatusName;
public String customerRemark;
}
/** 退货人 / 返邮信息。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class LogisticsInfo {
/** 是否返邮。 */
public Integer returnMailFlag;
/** 是否需要签收。 */
public Integer signatureFlag;
public Long logisticsProductId;
public String logisticsProduct;
public Integer returnLabelNum;
public String returnUserName;
public String returnCountryCode;
public String returnCountryName;
public String returnProvinceCode;
public String returnProvinceName;
public String returnCity;
public String returnAddress;
public String returnAddress2;
public String returnHouseNum;
public String returnZipCode;
public String returnPhone;
/** 返邮说明。 */
public String returnMailStr;
}
/** 预报包裹。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ShipmentParcel {
public String rmaParcelId;
public Double length;
public Double width;
public Double height;
/** 重量;单位文档未标。 */
public Double weight;
}
/** 预报退货 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SkuLine {
public String tempBarcode;
public String skuCode;
public String barcode;
public String extraBarcode;
/** 处理指令:1 上架 / 2 销毁(码表未给全)。 */
public Integer command;
public String commandName;
/**
* 增值服务。
*
* <p><b>文档标 number,真机返回字符串 {@code "0"}</b>——按 String 收,避免解析失败。</p>
*/
public String valueAddedServices;
/** 上架后的 SKU。 */
public String shelveSkuCode;
public String shelveSkuBarcode;
/** 数量;<b>文档标 string,真机返回 number</b>,用 Integer 两种都能收。 */
public Integer skuNum;
public String exceptionReason;
public String exceptionReasonName;
public Integer catalog;
public String catalogName;
/**
* 图片地址。
*
* <p>文档标 string(逗号拼接),真机返回 JSON 数组或 null。
* 用 {@code ACCEPT_SINGLE_VALUE_AS_ARRAY} 同时兼容两种。</p>
*/
@JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
public List<String> picUrls;
}
/** 包裹 / 跟踪号。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PackageLine {
public String trackingNo;
public Integer status;
public String statusName;
}
/** 收货检验结果。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CheckLine {
public String skuCode;
public String barcode;
public String tempBarcode;
public Integer skuNum;
public Double length;
public Double width;
public Double height;
public Double weight;
public Integer command;
public String commandName;
public Integer valueAddedService;
public Integer exceptionReason;
public String exceptionReasonName;
public String remark;
/**
* 图片地址。
*
* <p><b>文档标 string,真机返回 JSON 数组</b>(如 {@code []})。按 List 收。</p>
*/
@JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
public List<String> picUrls;
}
/** 实际上架结果。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ShelfLine {
public String skuCode;
public String barcode;
public String extraBarcode;
public String tempBarcode;
/** 文档标 string,真机返回 number——用 Integer 收。 */
public Integer command;
public String commandName;
public String valueAddedService;
public String shelveSkuCode;
public String shelveSkuBarcode;
/** 收货数量。 */
public Integer receiptQuantity;
/** 上架数量。 */
public Integer shelfQuantity;
/** 更新时间(毫秒)。 */
public Long updateTime;
/** 序列号集合。 */
public String snCodeList;
}
}

122
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java

@ -0,0 +1,122 @@ @@ -0,0 +1,122 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:创建退货单 / 退货预报
* ({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p>四种退货方式({@code returnType})的必填项各不相同:</p>
* <ul>
* <li>0 未妥投退回:{@code relationNo} 必填</li>
* <li>1 返邮退回:{@code relationNo} + 返邮标签 + 退货人姓名 / 城市 / 详细地址 / 邮编 必填;
* 物流产品不填则沿用关联单号的</li>
* <li>2 自行退回:{@code relationNo} + {@code trackingNo} 必填</li>
* <li>3 FBA 退回:{@code channelOrderNo}、退货仓库、承运商、物流信息、{@code trackingNo}、
* {@code returnLabelNum} 必填;{@code truckFlag=1}(卡车)时 {@code trackingNo} 传 BOL 号</li>
* </ul>
*
* <p>{@code warehouseId} 与 {@code warehouseCode} 传一个即可,<b>id 优先</b>。</p>
*/
public final class EdayunReturnDtos {
private EdayunReturnDtos() {
}
/** 创建退货单请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveReturnRequest {
/** 退货方式:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。<b>必填</b>。 */
public Integer returnType;
/** 关联单号(EDA 单号或客户单号)。 */
public String relationNo;
/** 退货原因,字典 {@code wms_rma_return_reason}(0 派送失败 / 1 客户退货)。 */
public Integer returnReason;
/** 包裹状态,字典 {@code wms_rma_claim_package_status}(0 已拆箱 / 1 未拆包 / 2 未知)。 */
public Integer packageStatus;
/** 承运商。 */
public String carrierName;
/** 客户内部备注。 */
public String customerRemark;
/** 退货单 SKU 列表。<b>必填</b>。 */
public List<SkuItem> skus;
/** 物流产品 id。 */
public Long logisticsProductId;
/** 退货人国家。 */
public String returnCountryCode;
/** 退货人省 / 州:支持英文全称 / 二字码 / EDA 区域编码(California / CA / US01)。 */
public String returnProvinceCode;
public String returnEmailAddress;
public String returnUserName;
public String returnCity;
public String returnAddress;
public String returnAddress2;
public String returnHouseNum;
public String returnZipCode;
public String returnPhone;
/** 发件人区县。 */
public String district;
/** 发件人街道。 */
public String subDistrict;
/** 退货标签数。 */
public Integer returnLabelNum;
/** 提货日期。 */
public String pickUpDate;
/** 跟踪号,多个用逗号分隔;默认用关联单号的。 */
public String trackingNo;
/** 物流方式:1 卡车 / 0 快递。 */
public Integer truckFlag;
/** 亚马逊单号(FBA 退货必填)。 */
public String channelOrderNo;
/** 仓库 id,优先级高于仓库编码。 */
public Long warehouseId;
/** 仓库编码;默认用关联单号的,FBA 退货必填。 */
public String warehouseCode;
}
/** 一条退货 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SkuItem {
/** SKU 编码。 */
public String skuCode;
/**
* 处理指令:1 上架 / 2 销毁(由 EDA 字典定义)。
*
* <p>文档未给码表,统一模型的 {@code ReturnDealMethod} 与它<b>不是一套码</b>,
* 映射关系待确认——见 TODO。</p>
*/
public Integer command;
/** 增值服务,逗号分隔({@code REPACKAGE} 重新包装 / {@code RELABEL} 重新贴标 等)。 */
public String valueAddedService;
/** 上架后的 SKU(换标上架时用)。 */
public String shelveSkuCode;
/** 数量。 */
public Integer skuNum;
/** 分类编码,由仓方字典定义。 */
public Integer catalog;
/** 图片地址。 */
public String picUrls;
}
/** 创建退货单响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveReturnResponse {
public Integer code;
public String msg;
/** 退货单号(如 {@code RMA2411053149})。 */
public String data;
public String traceId;
}
}

138
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java

@ -0,0 +1,138 @@ @@ -0,0 +1,138 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询退货单列表
* ({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。</p>
*
* <p>时间参数是<b>字符串</b>({@code yyyy-MM-dd HH:mm:ss}),不是毫秒时间戳——
* 与其它接口不一致,注意别按毫秒传。</p>
*/
public final class EdayunRmaListDtos {
private EdayunRmaListDtos() {
}
/** 列表查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SelectRmaListRequest {
/** 页码,从 1 开始。必填。 */
public Integer pageNum;
/** 每页条数,最大 200。必填。 */
public Integer pageSize;
/** 创建时间-开始,格式 {@code yyyy-MM-dd HH:mm:ss};缺省为近一个月。 */
public String createTimeStart;
/** 创建时间-结束,同上。 */
public String createTimeEnd;
/** 查询类型:1 退货单号 / 2 出库单号 / 3 平台订单号。配合 {@link #orderNos}。 */
public Integer orderNoSearchType;
/** 单号,多个用英文逗号分隔;配合 {@link #orderNoSearchType}。 */
public String orderNos;
/** 跟踪号,多个用英文逗号分隔。 */
public String trackingNos;
/** 仓库编码;{@link #warehouseId} 优先。 */
public String warehouseCode;
/** 仓库 id,优先级高于仓库编码。 */
public Long warehouseId;
/** 退货类型:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
/** SKU 编码。 */
public String skuCode;
/** 返邮标记:0 否 / 1 是。 */
public Integer returnMailFlag;
/** 是否上网:0 否 / 1 是。 */
public Integer onlineFlag;
/** 状态码,字典 {@code wms_rma_status}。 */
public Integer status;
/** 查询时间类型:0 创建 / 1 签收 / 2 查验 / 3 处理。 */
public Integer searchTimeType;
}
/** 列表查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SelectRmaListResponse {
/** 总行数。 */
public Long total;
public List<RmaRow> rows;
public Integer code;
public String msg;
public String traceId;
}
/** 列表里的一条退货单(只有单头,没有明细)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class RmaRow {
/** 退货单号。 */
public String rmaCode;
/** 平台订单号。 */
public String platformOrderCode;
/** 索赔单号。 */
public String claimOrderCode;
/** 出库单号(原始发货单)。 */
public String ordOrderCode;
/** 跟踪号。 */
public String trackingNo;
/** 预报品类数 / 实际品类数 / 预报商品数 / 实际商品数。 */
public Integer forecastCategoryNum;
public Integer productCategoryNum;
public Integer forecastProductNum;
public Integer productNum;
/** 增值服务标记。 */
public Integer valueAddedService;
public String warehouseName;
/** 仓名英文。 */
public String warehouseNameEn;
/**
* 仓编码。
*
* <p><b>文档响应示例里没有</b>,但真机(2026-11-13)会返回,如 {@code USLA}。
* 优先用它,而不是仓名。</p>
*/
public String warehouseCode;
public Long warehouseId;
/** 退货类型:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
public String returnTypeName;
/** 退货原因,字典 {@code wms_rma_return_reason}。 */
public Integer returnReason;
public String returnReasonName;
/** 状态码,字典 {@code wms_rma_status}。 */
public Integer status;
public String statusName;
/** 创建时间(毫秒)。 */
public Long createTime;
/** 创建时间(仓方时区的文本,如 {@code 2024-11-04 22:34:14})。 */
public String createTimeLocal;
/** 签收时间(毫秒)。 */
public Long signTime;
public String signTimeLocal;
/** 查验时间(毫秒)。 */
public Long checkTime;
public String checkTimeLocal;
/** 处理时间(毫秒)。 */
public Long handleTime;
public String handleTimeLocal;
/** 创建人。 */
public String createOperator;
}
}

103
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.edayun.enums;
import common.ecommerce.warehouse.enums.ReturnStatus;
/**
* 易达云退货单状态。
*
* <p>码表来自列表接口文档的 {@code status} 参数说明:</p>
* <pre>
* -1 已取消 0 待发布 1 待仓库签收 2 搁置中
* 3 仓库签收 4 处理中-仓库处理 5 已处理 6 处理中-等待指令
* 7 物流签收
* </pre>
*
* <p><b>注意</b>:详情接口({@code getOrderDetail})的 {@code basicInfo.status}
* 是否用同一套码表<b>没有确认</b>——列表文档明确给了字典,
* 详情文档只给了 {@code status: 1} 示例。两者都走本枚举,若日后发现不一致需拆开。</p>
*
* <p>认不出的码走 {@code statusName} 中文名兜底;都认不出归
* {@link ReturnStatus#UNKNOWN},原值保留在 {@code rawStatus}。</p>
*/
public enum EdayunRmaStatus {
/** -1 已取消。 */
CANCELLED(-1, ReturnStatus.CLOSED),
/** 0 待发布。 */
TO_PUBLISH(0, ReturnStatus.DRAFT),
/** 1 待仓库签收。 */
TO_SIGN(1, ReturnStatus.RETURNING),
/** 2 搁置中。 */
SUSPENDED(2, ReturnStatus.UNKNOWN),
/** 3 仓库签收。 */
SIGNED(3, ReturnStatus.PENDING_RECEIPT),
/** 4 处理中-仓库处理。 */
WAREHOUSE_HANDLING(4, ReturnStatus.PENDING_RECEIPT),
/** 5 已处理。 */
HANDLED(5, ReturnStatus.COMPLETED),
/** 6 处理中-等待指令。 */
WAITING_INSTRUCTION(6, ReturnStatus.PENDING_RECEIPT),
/** 7 物流签收。 */
LOGISTICS_SIGNED(7, ReturnStatus.RETURNING),
/** 无法识别。 */
UNKNOWN(null, ReturnStatus.UNKNOWN);
private final Integer rawCode;
private final ReturnStatus core;
EdayunRmaStatus(Integer rawCode, ReturnStatus core) {
this.rawCode = rawCode;
this.core = core;
}
/** 仓方状态码;null 表示无法识别。 */
public Integer rawCode() {
return rawCode;
}
public ReturnStatus toCore() {
return core;
}
/** 状态码 + 中文名 → 底层状态;码值优先,认不出码再看中文名。 */
public static ReturnStatus toCore(Integer status, String statusName) {
for (EdayunRmaStatus v : values()) {
if (v.rawCode != null && v.rawCode.equals(status)) {
return v.core;
}
}
return byName(statusName);
}
/** 按中文名推断;认不出返回 {@code UNKNOWN}。 */
static ReturnStatus byName(String statusName) {
if (statusName == null || statusName.trim().isEmpty()) {
return ReturnStatus.UNKNOWN;
}
String n = statusName.trim();
// 先判否定语义,避免「审核不通过」被「审核」命中
if (n.contains("驳回") || n.contains("拒绝") || n.contains("不通过")) {
return ReturnStatus.REJECTED;
}
if (n.contains("关闭") || n.contains("取消") || n.contains("作废")) {
return ReturnStatus.CLOSED;
}
if (n.contains("完成") || n.contains("已上架") || n.contains("结案")) {
return ReturnStatus.COMPLETED;
}
if (n.contains("审核")) {
return ReturnStatus.PENDING_REVIEW;
}
if (n.contains("收货") || n.contains("检验") || n.contains("清点")) {
return ReturnStatus.PENDING_RECEIPT;
}
if (n.contains("在途") || n.contains("退货中") || n.contains("运输")
|| n.contains("已发出") || n.contains("待收")) {
return ReturnStatus.RETURNING;
}
if (n.contains("草稿") || n.contains("预报")) {
return ReturnStatus.DRAFT;
}
return ReturnStatus.UNKNOWN;
}
}

109
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java

@ -0,0 +1,109 @@ @@ -0,0 +1,109 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
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.error.WarehouseException;
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 static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 取消退货单({@code /webApi/rma/info/v1/cancel})。
*
* <p>重点:响应 data 是布尔;{@code code=200 + data=false} 是仓方拒绝,要抛异常;
* 传的必须是仓侧 RMA 号。</p>
*/
class EdayunCancelReturnTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2",
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-return-cancel", 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_RETURN_CANCEL,
req -> Responses.ok(body));
}
@Test
void cancelSucceedsWhenDataIsTrue() {
RecordingTransport transport = stub(
"{\"code\":200,\"msg\":\"操作成功\",\"data\":true}");
boolean ok = new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA2411053149");
assertTrue(ok);
assertTrue(transport.lastDataRequest().body().contains("\"rmaCode\":\"RMA2411053149\""),
transport.lastDataRequest().body());
}
/**
* {@code code=200} 但 {@code data=false} 是仓方拒绝(如已收货)——
* 取消是状态变更,不能静默返回 false 让调用方以为没事。
*/
@Test
void dataFalseIsRejected() {
RecordingTransport transport = stub(
"{\"code\":200,\"msg\":\"退货单已收货,不允许取消\",\"data\":false}");
WarehouseException ex = assertThrows(WarehouseException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA1"));
assertTrue(ex.getMessage().contains("已收货"), ex.getMessage());
}
/** data 缺失同样视为失败——不能把「没返回结果」当成功。 */
@Test
void missingDataIsRejected() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\"}");
assertThrows(WarehouseException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA1"));
}
/** 业务码非 200 走 requireSuccess 的异常路径。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub("{\"code\":500,\"msg\":\"退货单不存在\"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA-NOT-EXIST"));
}
/** 空单号本地拒绝,不发请求。 */
@Test
void blankRmaCodeIsRejected() {
RecordingTransport transport = stub("{\"code\":200,\"data\":true}");
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec()).cancel(ctx(), " "));
assertTrue(ex.getMessage().contains("rmaCode"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
assertEquals(0, transport.dataRequests().size());
}
}

227
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java

@ -0,0 +1,227 @@ @@ -0,0 +1,227 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
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.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseReturn;
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 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/rma/info/v1/getOrderDetail})映射。
*
* <p>重点:明细行检验结果优先于预报、状态码表缺失只能按中文名推断、
* 响应只有仓名没有仓编码。</p>
*/
class EdayunReturnDetailTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2",
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-return-detail", CLOCK);
}
// ------------------------------------------------------------ 请求
@Test
void requiresRmaCode() {
assertThrows(IllegalArgumentException.class,
() -> EdayunReturnDetailMapper.toRequest(" "));
assertEquals("RMA1", EdayunReturnDetailMapper.toRequest(" RMA1 ").rmaCode);
}
// ------------------------------------------------------------ 响应
private static EdayunReturnDetailDtos.ReturnDetail detail() {
EdayunReturnDetailDtos.BasicInfo basic = new EdayunReturnDetailDtos.BasicInfo();
basic.rmaCode = "RMA2411053149";
basic.status = 3;
basic.statusName = "仓库签收";
basic.relationNo = "ORD599493019";
basic.warehouseId = 2L;
basic.warehouseName = "美西1仓";
basic.returnType = 2;
basic.returnTypeName = "自行退回";
basic.createTime = 1790568000000L;
EdayunReturnDetailDtos.SkuLine sku = new EdayunReturnDetailDtos.SkuLine();
sku.skuCode = "ybtest";
sku.skuNum = 2;
sku.command = 1;
sku.commandName = "上架";
sku.shelveSkuCode = "ybtest-NEW";
sku.picUrls = java.util.Arrays.asList("https://img/1.jpg", "https://img/2.jpg");
EdayunReturnDetailDtos.ReturnDetail detail = new EdayunReturnDetailDtos.ReturnDetail();
detail.basicInfo = basic;
detail.skuList = java.util.Collections.singletonList(sku);
return detail;
}
private static EdayunReturnDetailDtos.ReturnDetail checked() {
EdayunReturnDetailDtos.ReturnDetail detail = detail();
EdayunReturnDetailDtos.CheckLine check = new EdayunReturnDetailDtos.CheckLine();
check.skuCode = "ybtest";
check.skuNum = 1;
check.commandName = "上架";
check.exceptionReasonName = "外箱破损";
check.remark = "已拍照";
detail.checkList = java.util.Collections.singletonList(check);
return detail;
}
@Test
void mapsBasicInfo() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(detail(), "EDY-WH");
assertEquals("ORD599493019", ret.returnRequestNo());
assertEquals("RMA2411053149", ret.providerReturnId());
assertEquals("ORD599493019", ret.orderRef());
// 3 = 仓库签收 → 待收货
assertEquals("PENDING_RECEIPT", ret.status().name());
assertEquals("仓库签收", ret.rawStatus());
assertEquals(Instant.ofEpochMilli(1790568000000L), ret.createdAt());
assertEquals(WarehouseProvider.EDAYUN, ret.sourceProvider());
assertEquals("自行退回", ret.type());
}
/** 响应只有仓名与数字 id;warehouseCode 回退 OMS 仓编码。 */
@Test
void warehouseCodeFallsBackToOms() {
EdayunReturnDetailDtos.ReturnDetail noName = detail();
noName.basicInfo.warehouseName = null;
assertEquals("EDY-WH",
EdayunReturnDetailMapper.toReturn(noName, "EDY-WH").warehouseCode());
}
/** 明细优先取检验结果——对账以实际收到为准。 */
@Test
void checkListWinsOverSkuList() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(checked(), "W");
assertEquals(1, ret.lines().size());
WarehouseReturn.ReturnLine line = ret.lines().get(0);
assertEquals("ybtest", line.providerSku());
// 预报是 2,实际只收到 1
assertEquals(1, line.quantity());
assertEquals("外箱破损 已拍照", line.remark());
}
/** 没有检验记录时退回预报 SKU,skuNum 是 string 要解析。 */
@Test
void fallsBackToSkuList() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(detail(), "W");
assertEquals(1, ret.lines().size());
WarehouseReturn.ReturnLine line = ret.lines().get(0);
assertEquals(2, line.quantity());
assertEquals("ybtest-NEW", line.newSku());
assertEquals(2, line.pictureUrls().size());
assertEquals("https://img/2.jpg", line.pictureUrls().get(1));
}
/** 状态码表没给,只能按中文名推断;认不出归 UNKNOWN 并保留原文。 */
@Test
void statusInferredFromName() {
assertEquals(ReturnStatus.PENDING_RECEIPT, EdayunReturnDetailMapper.toReturn(
withStatus(9, "待收货"), "W").status());
assertEquals(ReturnStatus.REJECTED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "审核驳回"), "W").status());
assertEquals(ReturnStatus.COMPLETED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "已完成"), "W").status());
assertEquals(ReturnStatus.CLOSED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "已关闭"), "W").status());
WarehouseReturn unknown = EdayunReturnDetailMapper.toReturn(
withStatus(9, "某个新状态"), "W");
assertEquals(ReturnStatus.UNKNOWN, unknown.status());
assertEquals("某个新状态", unknown.rawStatus());
}
/** 「审核不通过」不能被「审核」命中成待审核。 */
@Test
void rejectedBeatsPendingReview() {
assertEquals(ReturnStatus.REJECTED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "审核不通过"), "W").status());
}
private static EdayunReturnDetailDtos.ReturnDetail withStatus(int code, String name) {
EdayunReturnDetailDtos.ReturnDetail d = detail();
d.basicInfo.status = code;
d.basicInfo.statusName = name;
return d;
}
/** createTime 为 0 或 null 时忽略,不要造出 1970 年。 */
@Test
void zeroCreateTimeIsNull() {
EdayunReturnDetailDtos.ReturnDetail d = detail();
d.basicInfo.createTime = 0L;
assertNull(EdayunReturnDetailMapper.toReturn(d, "W").createdAt());
}
/** 空/缺详情不抛异常:用请求单号兜底,返回空明细。 */
@Test
void nullDetailIsTolerated() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(null, "W", "RMA-X");
assertEquals("RMA-X", ret.returnRequestNo());
assertEquals("RMA-X", ret.providerReturnId());
assertTrue(ret.lines().isEmpty());
}
// ------------------------------------------------------------ 门面
@Test
void adapterQueriesReturnDetail() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_DETAIL,
req -> Responses.ok("{\"code\":200,\"msg\":\"操作成功\",\"data\":{"
+ "\"basicInfo\":{\"rmaCode\":\"RMA1\",\"status\":1,"
+ "\"statusName\":\"待收货\",\"relationNo\":\"ORD-1\","
+ "\"warehouseName\":\"美西1仓\",\"createTime\":1790568000000},"
+ "\"skuList\":[{\"skuCode\":\"ybtest\",\"skuNum\":\"2\"}]}}"));
WarehouseReturn ret = new EdayunAdapter(transport, new JacksonJsonCodec())
.getReturn(ctx(), "RMA1");
assertEquals("RMA1", ret.providerReturnId());
assertEquals("ORD-1", ret.returnRequestNo());
assertEquals(1, ret.lines().size());
assertTrue(transport.lastDataRequest().body().contains("\"rmaCode\":\"RMA1\""));
}
/** data=null 表示单号查不到,返回 null 而不是抛异常。 */
@Test
void missingDataReturnsNull() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_DETAIL,
req -> Responses.ok("{\"code\":200,\"msg\":\"操作成功\",\"data\":null}"));
assertNull(new EdayunAdapter(transport, new JacksonJsonCodec())
.getReturn(ctx(), "RMA-NOT-EXIST"));
}
}

205
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java

@ -0,0 +1,205 @@ @@ -0,0 +1,205 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
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.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
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 static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 创建退货单({@code /webApi/rma/info/v1/saveAndPublish})映射。
*
* <p>重点:统一模型只对应「自行退回」(returnType=2)、响应 data 就是退货单号、
* warehouseId 数字优先、只有「销毁」能确定码值。</p>
*/
class EdayunReturnTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00: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-return", CLOCK);
}
private static ReturnCommand command(ReturnDealMethod method) {
return ReturnCommand.builder()
.returnRequestNo("RT-001")
.saleOrderNo("ORD599493019")
.returnTrackingNo("1Z84V7X00397803717")
.carrierCode("Fedex")
.warehouseId("2")
.remark("客户寄回")
.line("ybtest", 2, method)
.build();
}
// ------------------------------------------------------------ 请求
@Test
void mapsSelfShipReturn() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.WAREHOUSE_CONFIRM), "2");
// 统一模型有退货运单号,只对得上「自行退回」
assertEquals(Integer.valueOf(2), req.returnType);
assertEquals("ORD599493019", req.relationNo);
assertEquals("1Z84V7X00397803717", req.trackingNo);
assertEquals("Fedex", req.carrierName);
assertEquals("客户寄回", req.customerRemark);
assertEquals(Long.valueOf(2L), req.warehouseId);
assertNull(req.warehouseCode);
}
/** 没有销售订单号时退回我们的退货单号,relationNo 不能为空。 */
@Test
void relationNoFallsBackToReturnRequestNo() {
ReturnCommand cmd = ReturnCommand.builder()
.returnRequestNo("RT-002")
.saleOrderNo("ORD-X")
.returnTrackingNo("1Z1")
.carrierCode("UPS")
.line("sku", 1, ReturnDealMethod.DESTROY)
.build();
assertEquals("ORD-X",
EdayunReturnMapper.toRequest(cmd, "2").relationNo);
}
@Test
void nonNumericWarehouseGoesToWarehouseCode() {
ReturnCommand noWarehouse = ReturnCommand.builder()
.returnRequestNo("RT-003")
.saleOrderNo("ORD-X")
.returnTrackingNo("1Z1")
.carrierCode("UPS")
.line("sku", 1, ReturnDealMethod.DESTROY)
.build();
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(noWarehouse, "USLA");
assertEquals("USLA", req.warehouseCode);
assertNull(req.warehouseId);
}
/** 命令上的仓优先于账户配置。 */
@Test
void commandWarehouseWins() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.DESTROY), "99");
assertEquals(Long.valueOf(2L), req.warehouseId);
}
@Test
void mapsSkuLines() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.DESTROY), "2");
assertEquals(1, req.skus.size());
EdayunReturnDtos.SkuItem sku = req.skus.get(0);
assertEquals("ybtest", sku.skuCode);
assertEquals(Integer.valueOf(2), sku.skuNum);
assertEquals(Integer.valueOf(EdayunReturnMapper.COMMAND_DESTROY), sku.command);
}
/** 只有「销毁」能确定;其余三种统一取值都归「上架」。 */
@Test
void commandMappingOnlyDestroysOnDestroy() {
assertEquals(Integer.valueOf(2),
EdayunReturnMapper.commandOf(ReturnDealMethod.DESTROY));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.CUSTOMER_PICKUP));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.PHOTO_CONFIRM));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.WAREHOUSE_CONFIRM));
assertNull(EdayunReturnMapper.commandOf(null));
}
// ------------------------------------------------------------ 响应
/** 每次业务调用前会先取 token,桩里要同时路由 /oauth/token。 */
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(EdayunConstants_path(), req -> Responses.ok(body));
}
private static String okBody(String rma) {
return "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"" + rma + "\","
+ "\"traceId\":\"11d8888e0c7e4827\"}";
}
/** 响应 data 是字符串(退货单号),不是对象——直接落 providerReturnId。 */
@Test
void responseDataIsReturnOrderNo() {
RecordingTransport transport = stub(okBody("RMA2411053149"));
WarehouseReturn result = new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
assertEquals("RT-001", result.returnRequestNo());
assertEquals("RMA2411053149", result.providerReturnId());
assertEquals("ORD599493019", result.orderRef());
assertEquals("EDY-WH", result.warehouseCode());
assertEquals(ReturnStatus.UNKNOWN, result.status());
assertEquals(WarehouseProvider.EDAYUN, result.sourceProvider());
}
/** 请求体按 poNumber 之外的字段落地:确认发出去的是退货报文。 */
@Test
void sendsReturnRequest() {
RecordingTransport transport = stub(okBody("RMA1"));
new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"returnType\":2"), body);
assertTrue(body.contains("\"relationNo\":\"ORD599493019\""), body);
assertTrue(body.contains("\"trackingNo\":\"1Z84V7X00397803717\""), body);
assertTrue(body.contains("\"warehouseId\":2"), body);
assertTrue(body.contains("\"command\":2"), body);
}
/** 业务码失败要抛异常,不能当成建单成功。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub(
"{\"code\":500,\"msg\":\"自行退回[关联单号|跟踪号]不能为空!\",\"data\":null}");
try {
new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
org.junit.jupiter.api.Assertions.fail("should have thrown");
} catch (RuntimeException e) {
assertTrue(e.getMessage().contains("关联单号"), e.getMessage());
}
}
/** 文档里的路径常量集中在一处,测试直接引用。 */
private static String EdayunConstants_path() {
return common.ecommerce.edayun.EdayunConstants.PATH_RETURN_CREATE;
}
}

249
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java

@ -0,0 +1,249 @@ @@ -0,0 +1,249 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
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 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/rma/info/v1/selectRmaInfoList})映射。
*
* <p>重点:时间是字符串不是毫秒、orderNos 要配 orderNoSearchType、只能传一个状态、
* total 判断翻页。</p>
*/
class EdayunRmaListTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2",
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-return-list", CLOCK);
}
private static ReturnQuery.Builder base() {
return ReturnQuery.builder();
}
// ------------------------------------------------------------ 请求
/** 时间是 {@code yyyy-MM-dd HH:mm:ss} 字符串,不是毫秒。 */
@Test
void timeWindowIsFormattedString() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().createdAfter(Instant.parse("2026-11-05T11:00:00Z"))
.createdBefore(Instant.parse("2026-11-06T11:00:00Z"))
.build(), "2", ZoneOffset.UTC, 1);
assertEquals("2026-11-05 11:00:00", req.createTimeStart);
assertEquals("2026-11-06 11:00:00", req.createTimeEnd);
}
/** 时间窗按仓方时区解释。 */
@Test
void timeWindowUsesWarehouseZone() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().createdAfter(Instant.parse("2026-11-05T11:00:00Z"))
.createdBefore(Instant.parse("2026-11-05T12:00:00Z"))
.build(), null, java.time.ZoneId.of("America/Los_Angeles"), 1);
// 2026-11-01 夏令时结束,11/05 洛杉矶是 PST(UTC-8):UTC 11:00 → 03:00
assertEquals("2026-11-05 03:00:00", req.createTimeStart);
}
/** 不传时间窗时不下发,由仓方默认近一个月。 */
@Test
void noTimeWindowIsOmitted() {
EdayunRmaListDtos.SelectRmaListRequest req =
EdayunRmaListMapper.toRequest(base().build(), "2", ZoneOffset.UTC, 1);
assertNull(req.createTimeStart);
assertNull(req.createTimeEnd);
}
/** orderNos 必须配 orderNoSearchType;不传类型默认按退货单号。 */
@Test
void orderNoDefaultsToRmaCodeSearch() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().orderNo("RMA1").build(), null, ZoneOffset.UTC, 1);
assertEquals("RMA1", req.orderNos);
assertEquals(Integer.valueOf(1), req.orderNoSearchType);
}
@Test
void orderNoTypesMap() {
assertEquals(Integer.valueOf(1),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PROVIDER_RETURN_NO));
assertEquals(Integer.valueOf(2),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.OUTBOUND_ORDER_NO));
assertEquals(Integer.valueOf(3),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO));
}
@Test
void warehouseIdGoesNumeric() {
EdayunRmaListDtos.SelectRmaListRequest numeric =
EdayunRmaListMapper.toRequest(base().build(), "2", ZoneOffset.UTC, 1);
assertEquals(Long.valueOf(2L), numeric.warehouseId);
assertNull(numeric.warehouseCode);
EdayunRmaListDtos.SelectRmaListRequest byCode = EdayunRmaListMapper.toRequest(
base().warehouseCode("USLA").build(), null, ZoneOffset.UTC, 1);
assertEquals("USLA", byCode.warehouseCode);
assertNull(byCode.warehouseId);
}
/** 接口只支持单个状态;多状态要拆查询。 */
@Test
void multipleStatusesAreRejected() {
ReturnQuery two = base().status(ReturnStatus.RETURNING).status(ReturnStatus.COMPLETED).build();
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> EdayunRmaListMapper.toRequest(two, "2", ZoneOffset.UTC, 1));
assertTrue(ex.getMessage().contains("at most one status"), ex.getMessage());
}
@Test
void statusMapsToRawCode() {
assertEquals(Integer.valueOf(0), EdayunRmaListMapper.statusOf(ReturnStatus.DRAFT));
assertEquals(Integer.valueOf(1), EdayunRmaListMapper.statusOf(ReturnStatus.RETURNING));
assertEquals(Integer.valueOf(1), EdayunRmaListMapper.statusOf(ReturnStatus.PENDING_RECEIPT));
assertEquals(Integer.valueOf(5), EdayunRmaListMapper.statusOf(ReturnStatus.COMPLETED));
assertEquals(Integer.valueOf(-1), EdayunRmaListMapper.statusOf(ReturnStatus.CLOSED));
assertNull(EdayunRmaListMapper.statusOf(ReturnStatus.UNKNOWN));
}
/** 每页上限 200。 */
@Test
void pageSizeCappedAt200() {
assertEquals(Integer.valueOf(200), EdayunRmaListMapper.toRequest(
base().pageSize(1000).build(), null, ZoneOffset.UTC, 1).pageSize);
assertEquals(Integer.valueOf(100), EdayunRmaListMapper.toRequest(
base().build(), null, ZoneOffset.UTC, 1).pageSize);
}
// ------------------------------------------------------------ 响应
private static EdayunRmaListDtos.RmaRow row() {
EdayunRmaListDtos.RmaRow row = new EdayunRmaListDtos.RmaRow();
row.rmaCode = "RMA2411058099";
row.platformOrderCode = "102002";
row.ordOrderCode = "ORD822935302";
row.trackingNo = "ORD822935302";
row.warehouseName = "美西1仓";
row.warehouseId = 2L;
row.returnType = 0;
row.returnTypeName = "未妥投退回";
row.status = 6;
row.statusName = "处理中-等待指令";
row.createTime = 1730788454000L;
return row;
}
@Test
void mapsRowToReturn() {
WarehouseReturn ret = EdayunRmaListMapper.toReturn(row(), "EDY-WH");
assertEquals("RMA2411058099", ret.returnRequestNo());
assertEquals("RMA2411058099", ret.providerReturnId());
assertEquals("美西1仓", ret.warehouseCode());
assertEquals("102002", ret.orderRef());
assertEquals("未妥投退回", ret.type());
// 6 = 处理中-等待指令 → 待收货
assertEquals(ReturnStatus.PENDING_RECEIPT, ret.status());
assertEquals("处理中-等待指令", ret.rawStatus());
assertEquals(Instant.ofEpochMilli(1730788454000L), ret.createdAt());
assertEquals(WarehouseProvider.EDAYUN, ret.sourceProvider());
// 列表没有明细
assertTrue(ret.lines().isEmpty());
}
/** 真机会返回 warehouseCode,优先用它而不是仓名。 */
@Test
void prefersWarehouseCodeFromResponse() {
EdayunRmaListDtos.RmaRow r = row();
r.warehouseCode = "USLA";
assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
/** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */
@Test
void warehouseCodeFallsBackToOms() {
EdayunRmaListDtos.RmaRow r = row();
r.warehouseName = null;
assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
/** 没有平台单号时 orderRef 用出库单号。 */
@Test
void orderRefFallsBackToOutboundOrderNo() {
EdayunRmaListDtos.RmaRow r = row();
r.platformOrderCode = null;
assertEquals("ORD822935302", EdayunRmaListMapper.toReturn(r, "W").orderRef());
}
@Test
void nextCursorUsesTotal() {
assertEquals("2", EdayunRmaListMapper.nextCursor(250L, 1, 100, 100));
assertNull(EdayunRmaListMapper.nextCursor(250L, 3, 100, 50));
// total 缺失时按满页判断
assertEquals("2", EdayunRmaListMapper.nextCursor(null, 1, 100, 100));
}
@Test
void emptyRowsYieldEmptyPage() {
EdayunRmaListDtos.SelectRmaListResponse resp = new EdayunRmaListDtos.SelectRmaListResponse();
resp.total = 0L;
resp.rows = java.util.Collections.emptyList();
assertTrue(EdayunRmaListMapper.toPage(resp, "W", 1, 100).items().isEmpty());
}
// ------------------------------------------------------------ 门面
@Test
void adapterQueriesList() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_LIST,
req -> Responses.ok("{\"total\":1,\"code\":200,\"msg\":\"success\","
+ "\"rows\":[{\"rmaCode\":\"RMA1\",\"status\":5,"
+ "\"statusName\":\"已处理\",\"warehouseName\":\"美西1仓\","
+ "\"createTime\":1730788454000}]}"));
Page<WarehouseReturn> page = new EdayunAdapter(transport, new JacksonJsonCodec())
.queryReturns(ctx(), ReturnQuery.builder().pageSize(100).build());
assertEquals(1, page.size());
assertEquals("RMA1", page.items().get(0).providerReturnId());
assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":1"));
}
}

163
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java

@ -0,0 +1,163 @@ @@ -0,0 +1,163 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunOrderMapper;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.ShipTo;
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.time.Instant;
import java.util.UUID;
/**
* 创建出库单探针:默认只打印报文,<b>不联网</b>。
*
* <p>创建出库单是<b>写操作</b>,会真实建单并向仓方下发发货任务,所以真跑要显式加
* {@code -Dedayun.probe.write=true};平台单号用 {@code PROBE-} 前缀的时间戳避免撞车。</p>
*
* <pre>
* # 只看报文(安全)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.order=true -Dtest=EdayunCreateOrderProbeTest test
*
* # 真发一次(会在测试仓建单)
* ... -Dedayun.probe.order=true -Dedayun.probe.write=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest
* </pre>
*
* <p>建单成功后记下响应里的 {@code orderNo},取消时要用它。
* 写操作不可逆,跑之前请确认这是测试仓。</p>
*/
@EnabledIfSystemProperty(named = "edayun.probe.order", matches = "true")
class EdayunCreateOrderProbeTest {
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 SKU = opt("edayun.probe.sku", "ybtest");
private static final boolean WRITE = Boolean.getBoolean("edayun.probe.write");
@Test
void probeCreateOrder() {
String poNumber = "PROBE-"
+ Long.toString(System.currentTimeMillis(), 36).toUpperCase();
OutboundCommand cmd = OutboundCommand.builder()
.outboundRequestNo("OB-" + poNumber)
.orderRef(poNumber)
.warehouseId(emptyToNull(WAREHOUSE_ID))
.labelMode(LabelMode.WAREHOUSE_LABEL)
.carrier("FedEx")
.salesPlatform(Platform.AMAZON_SC)
.currency("USD")
.declaredTotal(Money.of("19.99", "USD"))
.latestShipDate(Instant.now().plusSeconds(7 * 24 * 3600))
// 地址:易达云要州全称
.shipTo(ShipTo.builder()
.name("Probe Buyer")
.phone("+1-555-0100")
.email("probe@example.com")
.countryCode("US")
.stateOrProvince("California")
.city("Escondido")
.addressLine1("1308 E Washington Ave")
.postalCode("92027")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku(SKU)
.quantity(1)
.declareValue(Money.of("19.99", "USD"))
.insuredAmount(Money.of("19.99", "USD"))
.build())
.signatureRequired(Boolean.TRUE)
.build();
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(cmd, emptyToNull(WAREHOUSE_ID));
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_ORDER_CREATE + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID) + " sku=" + mask(SKU)
+ " poNumber=" + poNumber);
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
Assumptions.assumeTrue(WRITE, "dry-run:未加 -Dedayun.probe.write=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)"),
new JacksonJsonCodec());
OutboundReceipt receipt = adapter.create(ctx, cmd);
System.out.println("[OK] outboundRequestNo=" + receipt.outboundRequestNo()
+ " providerOrderId=" + receipt.providerOrderId());
} 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);
}
}

141
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java

@ -0,0 +1,141 @@ @@ -0,0 +1,141 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunReturnMapper;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
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.ReturnDealMethod;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.UUID;
/**
* 创建退货单探针:默认只打印报文,<b>不联网</b>。
*
* <p>创建退货单是<b>写操作</b>,会真实建 RMA 单,所以真跑要显式加
* {@code -Dedayun.probe.write=true},并且{@code relationNo} 必须是一个真实存在的
* 出库单号(仓方要按它找原单)。</p>
*
* <pre>
* # 只看报文(安全)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.return=true -Dtest=EdayunReturnProbeTest test
*
* # 真发一次(会在测试仓建退货单)
* ... -Dedayun.probe.return=true -Dedayun.probe.write=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \
* -Dedayun.probe.relationNo=ORD599493019 \
* -Dedayun.probe.trackingNo=1Z84V7X00397803717
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.return", matches = "true")
class EdayunReturnProbeTest {
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 SKU = opt("edayun.probe.sku", "ybtest");
private static final String RELATION_NO = opt("edayun.probe.relationNo", "ORD599493019");
private static final String TRACKING_NO =
opt("edayun.probe.trackingNo", "1Z84V7X00397803717");
private static final boolean WRITE = Boolean.getBoolean("edayun.probe.write");
@Test
void probeCreateReturn() {
String returnRequestNo = "PROBE-RT-"
+ Long.toString(System.currentTimeMillis(), 36).toUpperCase();
ReturnCommand cmd = ReturnCommand.builder()
.returnRequestNo(returnRequestNo)
.saleOrderNo(RELATION_NO)
.returnTrackingNo(TRACKING_NO)
.carrierCode("Fedex")
.warehouseId(emptyToNull(WAREHOUSE_ID))
.remark("probe")
.line(SKU, 1, ReturnDealMethod.WAREHOUSE_CONFIRM)
.build();
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(cmd, emptyToNull(WAREHOUSE_ID));
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_RETURN_CREATE + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID)
+ " relationNo=" + RELATION_NO + " trackingNo=" + mask(TRACKING_NO));
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
Assumptions.assumeTrue(WRITE, "dry-run:未加 -Dedayun.probe.write=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)"),
new JacksonJsonCodec());
WarehouseReturn result = adapter.create(ctx, cmd);
System.out.println("[OK] returnRequestNo=" + result.returnRequestNo()
+ " providerReturnId=" + result.providerReturnId()
+ " status=" + result.status());
} 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);
}
}

141
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java

@ -0,0 +1,141 @@ @@ -0,0 +1,141 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunRmaListMapper;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
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.shared.support.Page;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.time.Duration;
import java.time.Instant;
import java.util.UUID;
/**
* 退货单列表联调探针:<b>只读</b>,不会在仓侧产生任何数据。
*
* <p>默认跳过,用 {@code -Dedayun.probe.rmaList=true} 开启;凭据走系统属性,
* <b>真实值不入库</b>:</p>
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.rmaList=true -Dtest=EdayunRmaListProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.rmaList=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.days=30] [-Dedayun.probe.page=1]
* </pre>
*
* <p>异常只打印不抛出,便于一次跑完对照真实报文。</p>
*/
@EnabledIfSystemProperty(named = "edayun.probe.rmaList", matches = "true")
class EdayunRmaListProbeTest {
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 int DAYS = Integer.getInteger("edayun.probe.days", 30);
private static final int PAGE = Integer.getInteger("edayun.probe.page", 1);
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeRmaList() {
Instant end = Instant.now();
Instant begin = end.minus(Duration.ofDays(DAYS));
ReturnQuery query = ReturnQuery.builder()
.createdAfter(begin)
.createdBefore(end)
.cursor(PAGE <= 1 ? null : String.valueOf(PAGE))
.pageSize(100)
.build();
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
query, emptyToNull(WAREHOUSE_ID), java.time.ZoneOffset.UTC, PAGE);
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_RETURN_LIST + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID)
+ " days=" + DAYS + " page=" + PAGE);
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
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());
Page<WarehouseReturn> page = adapter.queryReturns(ctx, query);
System.out.println("[OK] rows=" + page.size() + " hasMore=" + page.hasMore()
+ " nextCursor=" + page.nextCursor());
for (WarehouseReturn r : page.items()) {
System.out.println(" " + r.providerReturnId() + " " + r.status()
+ " raw=" + r.rawStatus() + " warehouse=" + r.warehouseCode()
+ " orderRef=" + r.orderRef() + " createdAt=" + r.createdAt());
}
} 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