diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java index 93c1a26..ff61d4e 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java @@ -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 { WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo); /** 分页查退货单;命名原因同 {@link #getReturn}。 */ - Page queryReturns(WarehouseContext ctx, String cursor); + Page queryReturns(WarehouseContext ctx, ReturnQuery query); /** * 按明细行设置检验后处理方式。写操作,幂等键 @@ -44,8 +45,18 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { */ void process(WarehouseContext ctx, ReturnProcessCommand cmd); - /** 取消退货单;仅部分仓支持。 */ - default void cancel(WarehouseContext ctx, String returnRequestNo) { + /** + * 取消退货单;仅部分仓支持。 + * + *

与 {@link #create} 的区别:这个只需要仓侧退货单号({@code providerReturnId}), + * 因为多数仓的取消接口只认自己的 RMA 号。

+ * + * @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); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java new file mode 100644 index 0000000..ec26f11 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java @@ -0,0 +1,38 @@ +package common.ecommerce.warehouse.enums; + +/** + * 退货单查询时「单号」的类型。 + * + *

易达云列表接口的 {@code orderNoSearchType}:1 退货单号 / 2 出库单号 / 3 平台订单号。 + * 用统一枚举表达,适配器不支持的类型要显式拒绝——静默按别的口径查会让结果对不上。

+ * + *

与 {@link FeeQueryNoType} 不是一套:那边是费用查询的「仓侧订单号 / 平台单号 / 追踪号」, + * 这里有「退货单号」,语义不同,不复用。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java new file mode 100644 index 0000000..1c3d3cb --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java @@ -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; + +/** + * 退货单查询条件(单次查询,不推进水位线)。 + * + *

各仓支持的维度不同:易达云支持时间窗 + 单号 + 仓库 + 状态 + SKU, + * 不支持的维度由适配器显式拒绝,不静默忽略——忽略一个过滤条件会让结果对不上。

+ */ +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 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(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 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 statuses = new java.util.ArrayList(); + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 22bf510..4afdb7f 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -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 { () -> ((LogisticsProductCapable) adapter).products(ctx, warehouseCode)); } + + /** 费用视图。 */ public FeeView fees() { return new FeeView(); @@ -588,12 +589,21 @@ public final class WarehouseOperations { () -> ((WarehouseReturnCapable) adapter).getReturn(ctx, returnRequestNo)); } - public Page query(String cursor) { + /** + * 分页查退货单。 + * + *

各仓支持的过滤维度不同,不支持的由适配器显式拒绝;传空条件时 + * 适配器要么用自己的默认窗口(如易达云默认近一个月),要么拒绝。

+ */ + public Page 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 { }, c -> null)); } + + /** + * 取消退货单。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + providerReturnNo + "cancel"}。 + * + *

只传仓侧退货单号——多数仓的取消接口只认自己的 RMA 号。

+ * + * @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 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()); + } } /** 费用视图。 */ diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java index 263eaca..a025184 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java @@ -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"; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index f411e99..87719d7 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -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; 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; 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; 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; 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; */ 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 public EnumSet 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 EdayunFeeEstimateMapper.toResult(parsed, ctx.warehouseCode())); } + // ------------------------------------------------------------------ 退货 + + /** + * 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。 + * + *

统一模型只对应「自行退回」({@code returnType=2}):它要求退货运单号, + * 正好是买家自己寄回的场景。未妥投 / 返邮 / FBA 退回要退货人地址或亚马逊单号, + * 标准模型没有——见 TODO。

+ * + *

与运去哪不同,响应 {@code data} 就是仓侧退货单号,可直接落 + * {@code providerReturnId};状态不回,只能后续人工或回调补。

+ */ + @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})。 + * + *

{@code returnRequestNo} 可以是 OMS 退货单号,也可以是仓方 RMA 号—— + * 仓方只认 {@code rmaCode},所以非 RMA 号要先有创建时拿到的 + * {@code providerReturnId}。这里原样传,查不到由仓方报错。

+ * + *

明细行优先取仓的检验结果({@code checkList}),没有才退回预报 + * ({@code skuList})——对账以实际收到为准。

+ */ + @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})。 + * + *

只认仓方 {@code rmaCode},所以传的必须是创建时拿到的 + * {@code providerReturnId}——用 OMS 单号会被仓方查不到。

+ * + *

响应 {@code data=true} 才算成功。{@code code=200} + {@code data=false} + * 是仓方拒绝(如已收货),这里抛异常而不是静默返回 false—— + * 取消退货是状态变更,调用方必须知道没成功。

+ */ + @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})。 + * + *

只回单头,没有明细行与退货人地址;要明细请用 {@link #getReturn}。

+ * + *

时间窗不传时仓方默认近一个月——这一点由仓方兜底,本地不补默认值, + * 免得「没给时间窗」和「显式要近一个月」两种情况被混掉。

+ */ + @Override + public Page 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); + } + + /** + * 按明细行设置检验后处理方式。 + * + *

需要仓侧明细行 id,而查退货单的接口还没有——无法构造,显式拒绝。

+ */ + @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) { diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java new file mode 100644 index 0000000..9c420fc --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java @@ -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})。 + * + *

响应七块,统一模型只承载前面几块:单头、明细行、检验 / 上架数量。 + * 退货人地址、预报包裹尺寸、包裹状态这些只在 DTO 里——标准模型没有对应字段。

+ * + *

明细行取 {@code checkList} 优先,回落 {@code skuList}: + * {@code skuList} 是预报(买家要退什么),{@code checkList} 是仓实际收到的 + * (含检验数量与异常原因)。对账要用实际收到的,没有检验记录才退回预报。

+ */ +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。 + * + *

两边的字段名不同({@code skuNum} 在 skuList 是 string、在 checkList 是 number), + * 分开映射,不要合并成一个循环。

+ */ + static List toLines(EdayunReturnDetailDtos.ReturnDetail detail) { + List out = new ArrayList(); + 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 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 splitUrls(String raw) { + List out = new ArrayList(); + 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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java new file mode 100644 index 0000000..168556a --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java @@ -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})。 + * + *

统一模型只能表达「自行退回」这一种退货方式({@link ReturnCommand} 强制要求 + * 退货运单号),所以 {@code returnType} 固定 2。未妥投退回 / 返邮退回 / FBA 退回 + * 需要退货人地址或亚马逊单号,标准模型没有对应字段——见 docs-warehouse/edayun/TODO.md。

+ * + *

响应 {@code data} 就是退货单号(如 {@code RMA2411053149}), + * 与运去哪不同,这里能直接拿到仓侧单号。

+ */ +public final class EdayunReturnMapper { + + /** + * 退货方式:自行退回。 + * + *

0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。统一模型有退货运单号, + * 正好对应「买家自己寄回」。

+ */ + 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}。 + * + *

命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。

+ */ + 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 toSkus( + List lines) { + List out = + new ArrayList(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; + } + + /** + * 统一处理方式 → 易达云处理指令。 + * + *

只有「销毁」能确定({@code 2})。其余三种统一取值在易达云都归「上架」—— + * 客户自提 / 拍照确认 / 仓库确认都要先入库再处理,所以下发上架。 + * 易达云的完整码表未拿到,见 TODO。

+ */ + static Integer commandOf(ReturnDealMethod method) { + if (method == null) { + return null; + } + return method == ReturnDealMethod.DESTROY ? COMMAND_DESTROY : COMMAND_PUT_AWAY; + } + + /** + * 创建成功 → 统一退货单。 + * + *

仓侧单号直接来自响应 {@code data};接口不回状态,所以 {@link ReturnStatus#UNKNOWN}。

+ */ + 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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java new file mode 100644 index 0000000..235181e --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java @@ -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})。 + * + *

与详情接口的区别:列表只回单头,没有明细行、没有退货人地址。 + * 需要明细要走 {@code getOrderDetail}。

+ * + *

时间参数是字符串 {@code yyyy-MM-dd HH:mm:ss},且按仓方时区解释 + * ({@code WarehouseContext.zone()}),不是毫秒时间戳。

+ */ +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}。 + * + *

null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。

+ * + * @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}。 + * + *

码表来自文档原文:{@code 0 待发布 / 1 待仓库签收 / 2 搁置中 / 3 仓库签收 / + * 4 处理中-仓库处理 / 5 已处理 / 6 处理中-等待指令 / 7 物流签收 / -1 已取消}。

+ * + *

统一枚举里没有「搁置中」「等待指令」这类细分,所以查询时只能按大类取一个代表值; + * 认不出的返回 null(不过滤),由调用方承担后果——见 TODO。

+ */ + 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 toPage(EdayunRmaListDtos.SelectRmaListResponse response, + String fallbackWarehouseCode, + int currentPage, int pageSize) { + if (response == null || response.rows == null || response.rows.isEmpty()) { + return Page.empty(); + } + List out = new ArrayList(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())); + } + + /** + * 有下一页时返回下一页页码。 + * + *

文档写明 {@code total} 是总数据量(行数),优先用它判断; + * 缺失时退回「本页是否满页」。

+ */ + 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(); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java new file mode 100644 index 0000000..b502c74 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java @@ -0,0 +1,38 @@ +package common.ecommerce.edayun.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * 易达云报文结构:取消退货单 + * ({@code POST /webApi/rma/info/v1/cancel})。 + * + *

一个文件对应一个接口。请求只有一个 {@code rmaCode};响应 {@code data} + * 是布尔值({@code true} 成功),不是单号——与创建接口不同。

+ */ +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} 表示取消成功。 + * + *

注意:仓方可能回 {@code code=200} + {@code data=false} + * (业务拒绝),所以两个都要判。

+ */ + public Boolean data; + public String traceId; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java new file mode 100644 index 0000000..d41345b --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java @@ -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})。 + * + *

一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。

+ * + *

响应按业务分组,七块内容:

+ *
    + *
  • {@code basicInfo} —— 单头(状态、关联单号、仓库、退货方式、创建时间)
  • + *
  • {@code logisticsInfo} —— 退货人地址与返邮信息
  • + *
  • {@code shipmentParcelList} —— 预报的包裹尺寸重量
  • + *
  • {@code skuList} —— 预报的退货 SKU
  • + *
  • {@code packageList} —— 包裹 / 跟踪号及状态
  • + *
  • {@code checkList} —— 仓收货检验结果
  • + *
  • {@code shelfList} —— 实际上架结果
  • + *
+ */ +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 shipmentParcelList; + public List skuList; + public List packageList; + public List checkList; + public List 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; + /** + * 增值服务。 + * + *

文档标 number,真机返回字符串 {@code "0"}——按 String 收,避免解析失败。

+ */ + public String valueAddedServices; + /** 上架后的 SKU。 */ + public String shelveSkuCode; + public String shelveSkuBarcode; + /** 数量;文档标 string,真机返回 number,用 Integer 两种都能收。 */ + public Integer skuNum; + public String exceptionReason; + public String exceptionReasonName; + public Integer catalog; + public String catalogName; + /** + * 图片地址。 + * + *

文档标 string(逗号拼接),真机返回 JSON 数组或 null。 + * 用 {@code ACCEPT_SINGLE_VALUE_AS_ARRAY} 同时兼容两种。

+ */ + @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY) + public List 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; + /** + * 图片地址。 + * + *

文档标 string,真机返回 JSON 数组(如 {@code []})。按 List 收。

+ */ + @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY) + public List 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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java new file mode 100644 index 0000000..f4f216c --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java @@ -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})。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。

+ * + *

四种退货方式({@code returnType})的必填项各不相同:

+ *
    + *
  • 0 未妥投退回:{@code relationNo} 必填
  • + *
  • 1 返邮退回:{@code relationNo} + 返邮标签 + 退货人姓名 / 城市 / 详细地址 / 邮编 必填; + * 物流产品不填则沿用关联单号的
  • + *
  • 2 自行退回:{@code relationNo} + {@code trackingNo} 必填
  • + *
  • 3 FBA 退回:{@code channelOrderNo}、退货仓库、承运商、物流信息、{@code trackingNo}、 + * {@code returnLabelNum} 必填;{@code truckFlag=1}(卡车)时 {@code trackingNo} 传 BOL 号
  • + *
+ * + *

{@code warehouseId} 与 {@code warehouseCode} 传一个即可,id 优先。

+ */ +public final class EdayunReturnDtos { + + private EdayunReturnDtos() { + } + + /** 创建退货单请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SaveReturnRequest { + + /** 退货方式:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。必填。 */ + 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 列表。必填。 */ + public List 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 字典定义)。 + * + *

文档未给码表,统一模型的 {@code ReturnDealMethod} 与它不是一套码, + * 映射关系待确认——见 TODO。

+ */ + 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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java new file mode 100644 index 0000000..817591c --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java @@ -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})。 + * + *

一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。

+ * + *

时间参数是字符串({@code yyyy-MM-dd HH:mm:ss}),不是毫秒时间戳—— + * 与其它接口不一致,注意别按毫秒传。

+ */ +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 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; + /** + * 仓编码。 + * + *

文档响应示例里没有,但真机(2026-11-13)会返回,如 {@code USLA}。 + * 优先用它,而不是仓名。

+ */ + 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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java new file mode 100644 index 0000000..d235a9e --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java @@ -0,0 +1,103 @@ +package common.ecommerce.edayun.enums; + +import common.ecommerce.warehouse.enums.ReturnStatus; + +/** + * 易达云退货单状态。 + * + *

码表来自列表接口文档的 {@code status} 参数说明:

+ *
+ * -1 已取消      0 待发布        1 待仓库签收    2 搁置中
+ *  3 仓库签收    4 处理中-仓库处理  5 已处理      6 处理中-等待指令
+ *  7 物流签收
+ * 
+ * + *

注意:详情接口({@code getOrderDetail})的 {@code basicInfo.status} + * 是否用同一套码表没有确认——列表文档明确给了字典, + * 详情文档只给了 {@code status: 1} 示例。两者都走本枚举,若日后发现不一致需拆开。

+ * + *

认不出的码走 {@code statusName} 中文名兜底;都认不出归 + * {@link ReturnStatus#UNKNOWN},原值保留在 {@code rawStatus}。

+ */ +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; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java new file mode 100644 index 0000000..986be35 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java @@ -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})。 + * + *

重点:响应 data 是布尔;{@code code=200 + data=false} 是仓方拒绝,要抛异常; + * 传的必须是仓侧 RMA 号。

+ */ +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()); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java new file mode 100644 index 0000000..7ddf730 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java @@ -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})映射。 + * + *

重点:明细行检验结果优先于预报、状态码表缺失只能按中文名推断、 + * 响应只有仓名没有仓编码。

+ */ +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")); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java new file mode 100644 index 0000000..19f5921 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java @@ -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})映射。 + * + *

重点:统一模型只对应「自行退回」(returnType=2)、响应 data 就是退货单号、 + * warehouseId 数字优先、只有「销毁」能确定码值。

+ */ +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; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java new file mode 100644 index 0000000..3496789 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java @@ -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})映射。 + * + *

重点:时间是字符串不是毫秒、orderNos 要配 orderNoSearchType、只能传一个状态、 + * total 判断翻页。

+ */ +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 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")); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java new file mode 100644 index 0000000..e32a981 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java @@ -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; + +/** + * 创建出库单探针:默认只打印报文,不联网。 + * + *

创建出库单是写操作,会真实建单并向仓方下发发货任务,所以真跑要显式加 + * {@code -Dedayun.probe.write=true};平台单号用 {@code PROBE-} 前缀的时间戳避免撞车。

+ * + *
+ * # 只看报文(安全)
+ * 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
+ * 
+ * + *

建单成功后记下响应里的 {@code orderNo},取消时要用它。 + * 写操作不可逆,跑之前请确认这是测试仓。

+ */ +@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); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java new file mode 100644 index 0000000..25a2b5e --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java @@ -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; + +/** + * 创建退货单探针:默认只打印报文,不联网。 + * + *

创建退货单是写操作,会真实建 RMA 单,所以真跑要显式加 + * {@code -Dedayun.probe.write=true},并且{@code relationNo} 必须是一个真实存在的 + * 出库单号(仓方要按它找原单)。

+ * + *
+ * # 只看报文(安全)
+ * 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
+ * 
+ */ +@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); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java new file mode 100644 index 0000000..d7030de --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java @@ -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; + +/** + * 退货单列表联调探针:只读,不会在仓侧产生任何数据。 + * + *

默认跳过,用 {@code -Dedayun.probe.rmaList=true} 开启;凭据走系统属性, + * 真实值不入库:

+ * + *
+ * # 只看报文(不联网)
+ * 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]
+ * 
+ * + *

异常只打印不抛出,便于一次跑完对照真实报文。

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