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 6d57d52..3667f70 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 @@ -1,27 +1,46 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.model.ReturnCommand; +import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; /** * 退货能力。信仓无此接口,整体不实现。 + * + *
退货链路有两个不同的「处理方式」,别混:
+ *方法名带 {@code Return} 后缀:{@code InboundCapable} 已有完全同签名的 + * {@code get(ctx, String)} / {@code query(ctx, String)},同一适配器实现两者时 + * 泛型擦除后无法区分。
+ */ + WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo); - /** 设置处理方式(二次上架 / 销毁);仅部分仓支持。 */ - default void setDisposition(WarehouseContext ctx, String returnRequestNo, - WarehouseReturn.Disposition disposition) { - throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.RETURN_DISPOSITION); - } + /** 分页查退货单;命名原因同 {@link #getReturn}。 */ + Page运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行; + * 每条商品行还必须给处理方式。
+ */ +public final class ReturnCommand { + + private final String returnRequestNo; + private final String warehouseId; + /** 关联的销售订单号(我们下发的 {@code orderNo})。 */ + private final String saleOrderNo; + /** 退货运单号。 */ + private final String returnTrackingNo; + /** 退货承运商 code。 */ + private final String carrierCode; + /** 预计到仓日期。 */ + private final LocalDate estimatedReceiveDate; + private final String returnReason; + private final String remark; + private final List{@link #dealMethod()} 是退货预约时的处理方式,与 + * {@code ReturnProcessCommand.Disposition}(检验后处理方式)不是一回事: + * 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。
+ */ + public static final class ReturnCommandLine { + + private final String providerSku; + private final int quantity; + private final DealMethod dealMethod; + + public ReturnCommandLine(String providerSku, int quantity, DealMethod dealMethod) { + if (providerSku == null || providerSku.trim().isEmpty()) { + throw new IllegalArgumentException("providerSku must not be blank"); + } + if (quantity <= 0) { + throw new IllegalArgumentException("quantity must be positive"); + } + this.providerSku = providerSku.trim(); + this.quantity = quantity; + this.dealMethod = java.util.Objects.requireNonNull(dealMethod, "dealMethod"); + } + + public String providerSku() { + return providerSku; + } + + public int quantity() { + return quantity; + } + + public DealMethod dealMethod() { + return dealMethod; + } + } + + /** + * 退货预约的处理方式(API 81):0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。 + * + *注意 API 77 的检验后处理方式码值完全不同(0 自提 / 2 销毁 / 3 上架 / 4 换标上架), + * 两者不能混用。
+ */ + public enum DealMethod { + CUSTOMER_PICKUP(0), + PHOTO_CONFIRM(1), + DESTROY(2), + WAREHOUSE_CONFIRM(5); + + private final int code; + + DealMethod(int code) { + this.code = code; + } + + public int code() { + return code; + } + } + + public static final class Builder { + + private String returnRequestNo; + private String warehouseId; + private String saleOrderNo; + private String returnTrackingNo; + private String carrierCode; + private LocalDate estimatedReceiveDate; + private String returnReason; + private String remark; + private final List与 {@code ReturnCommand.DealMethod}(预约时的预报)不是一回事: + * 这里是仓收货检验之后,逐条明细行最终决定怎么处理。
+ */ +public final class ReturnProcessCommand { + + private final String providerReturnNo; + /** 仓侧明细行 id;来自退货查询接口的 items[].id。 */ + private final long lineId; + private final Disposition disposition; + /** 换标上架时的新 SKU;其它处理方式必须为 null。 */ + private final String newSku; + private final String remark; + + private ReturnProcessCommand(Builder b) { + if (b.providerReturnNo == null || b.providerReturnNo.trim().isEmpty()) { + throw new IllegalArgumentException("providerReturnNo must not be blank"); + } + this.providerReturnNo = b.providerReturnNo.trim(); + if (b.lineId <= 0) { + throw new IllegalArgumentException("lineId must be positive"); + } + this.lineId = b.lineId; + this.disposition = java.util.Objects.requireNonNull(b.disposition, "disposition"); + boolean needsSku = b.disposition == Disposition.RESTOCK_RELABEL; + if (needsSku && (b.newSku == null || b.newSku.trim().isEmpty())) { + throw new IllegalArgumentException("newSku is required when disposition is RESTOCK_RELABEL"); + } + if (!needsSku && b.newSku != null && !b.newSku.trim().isEmpty()) { + throw new IllegalArgumentException("newSku is only valid when disposition is RESTOCK_RELABEL"); + } + this.newSku = b.newSku; + this.remark = b.remark; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓侧退货计划单号。 */ + public String providerReturnNo() { + return providerReturnNo; + } + + /** 仓侧明细行 id。 */ + public long lineId() { + return lineId; + } + + public Disposition disposition() { + return disposition; + } + + public String newSku() { + return newSku; + } + + public String remark() { + return remark; + } + + /** + * 检验后处理方式(API 77):0 客户自提 / 2 销毁 / 3 上架(良品) / 4 换标上架(良品)。 + * + *与预约时的处理方式码值不同,不能混用。
+ */ + public enum Disposition { + CUSTOMER_PICKUP(0), + DESTROY(2), + RESTOCK(3), + RESTOCK_RELABEL(4); + + private final int code; + + Disposition(int code) { + this.code = code; + } + + public int code() { + return code; + } + } + + public static final class Builder { + private String providerReturnNo; + private long lineId; + private Disposition disposition; + private String newSku; + private String remark; + + public Builder providerReturnNo(String v) { + this.providerReturnNo = v; + return this; + } + + public Builder lineId(long v) { + this.lineId = v; + return this; + } + + public Builder disposition(Disposition v) { + this.disposition = v; + return this; + } + + public Builder newSku(String v) { + this.newSku = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + public ReturnProcessCommand build() { + return new ReturnProcessCommand(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 ef76036..e482497 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 @@ -18,6 +18,8 @@ import common.ecommerce.warehouse.capability.WarehouseWebhookCapable; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.BillingDocument; 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; @@ -235,12 +237,38 @@ public final class WarehouseOperations { /** 退货视图。 */ public final class ReturnView { + /** + * 创建退货预约。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + returnRequestNo + create}。 + */ + public WarehouseReturn create(final ReturnCommand cmd) { + 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按明细行做键,而不是按整单:一张退货单的多行可以分别上架 / 销毁, + * 同一行重复下发才是重复。
+ */ + public void process(final ReturnProcessCommand cmd) { require(WarehouseCapability.RETURN_DISPOSITION, WarehouseReturnCapable.class); - ((WarehouseReturnCapable) adapter).setDisposition(ctx, returnRequestNo, disposition); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter; + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + cmd.providerReturnNo() + ':' + cmd.lineId(), "process"), + () -> { + capable.process(ctx, cmd); + return cmd; + }, + c -> null); } } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index 670eb3f..f22f270 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -40,10 +40,10 @@ public final class YqnConstants { public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; /** 查询入库计划(API 101)。 */ public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo"; - /** 退货发起。 */ - public static final String PATH_RETURN_CREATE = "/salereturn/SalesReturnCreate"; - /** 退货处理方式(二次上架 / 销毁)。 */ - public static final String PATH_RETURN_DISPOSITION = "/salereturn/SaleReturnAddProcessMode"; + /** 创建销售退货(API 81)。 */ + public static final String PATH_RETURN_CREATE = "/v3/saleReturn/createSaleReturnPlan"; + /** 退货条目处理(API 77):按明细行设置检验后处理方式。 */ + public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode"; /** 销毁计划。 */ public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; /** 物流轨迹。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 42fae0d..26d82c4 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -16,13 +16,17 @@ 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.ReturnCommand; +import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.InventorySyncStrategy; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; +import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; @@ -62,7 +66,8 @@ import java.util.Map; * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。 */ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, - WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable { + WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable, + WarehouseReturnCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -98,7 +103,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, - WarehouseCapability.TRANSFER); + WarehouseCapability.TRANSFER, + WarehouseCapability.RETURN, + WarehouseCapability.RETURN_DISPOSITION); } // ------------------------------------------------------------------ 商品 @@ -416,6 +423,45 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return YqnTransferMapper.toOrder(resp, cmd.type(), zoneOf(ctx)); } + // ------------------------------------------------------------------ 退货 + + /** + * 创建销售退货预约(API 81)。 + * + *响应只有 code/message,没有单号:所以返回的 + * {@code providerReturnId} 是 null。退货的仓侧单号只能靠后续查询或回调补。 + * 这会影响「按仓单号做幂等 / 回查」的用法——按文档我们只能用来源单号。
+ */ + @Override + public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) { + String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); + YqnDtos.CreateSaleReturnRequest body = YqnReturnMapper.toRequest(cmd, warehouseCode); + execute(ctx, YqnConstants.PATH_RETURN_CREATE, body, "warehouse.return.create"); + return YqnReturnMapper.toCreated(cmd, warehouseCode); + } + + /** + * 按明细行设置检验后处理方式(API 77)。 + * + *运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。
+ */ + @Override + public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { + YqnDtos.SaleReturnProcessRequest body = YqnReturnMapper.toProcessRequest(cmd); + execute(ctx, YqnConstants.PATH_RETURN_PROCESS, body, "warehouse.return.process"); + } + + /** 退货查询未接入:文档只给了创建(81)与条目处理(77)。 */ + @Override + public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) { + throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); + } + + @Override + public PageAPI 81 只回 code / message,没有单号。所以这里只能用输入单号, + * {@code providerReturnId} 留 null——仓侧单号要么等查询接口,要么靠回调。
+ */ + public static WarehouseReturn toCreated(ReturnCommand cmd, String warehouseCode) { + return WarehouseReturn.builder() + .returnRequestNo(cmd.returnRequestNo()) + .warehouseCode(warehouseCode) + .orderRef(cmd.saleOrderNo()) + .status("SUBMITTED") + .rawStatus(null) + .build(); + } + + static String formatDate(LocalDate date) { + return date == null ? null : DATE.format(date); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index f6f23f6..bab2cd2 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -828,4 +828,57 @@ public final class YqnDtos { public String trackingNo; public String remark; } + + /** 创建销售退货请求(API 81)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateSaleReturnRequest { + + /** 仓库 code,必填。 */ + public String warehouseCode; + /** 来源单号,必填。 */ + public String orderNo; + public String lineName; + /** 关联销售订单号,必填。 */ + public String saleOrderNo; + /** 退货运单号,必填。 */ + public String returnTrackingNo; + /** 退货承运商,必填。 */ + public String carrierCode; + /** 预计到仓日期 yyyy-MM-dd。 */ + public String estimateReceiveDate; + public String returnReason; + public String remark; + /** 退货产品明细,必填。 */ + public List文档把 {@code newSku} / {@code remark} 标成必填,但语义上只在换标上架时 + * 用 newSku;这里按「非换标时不传」处理,由服务端按 goodsReturnType 判断。
+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SaleReturnProcessRequest { + + /** 退货计划单号,必填。 */ + public String saleReturnPlanNo; + /** 明细行 id(来自退货查询的 saleReturnOrderItems[].id),必填。 */ + public Long id; + /** 0 客户自提 / 2 销毁 / 3 上架(良品) / 4 换标上架(良品)。 */ + public Integer goodsReturnType; + /** 仅 4 换标上架时使用。 */ + public String newSku; + public String remark; + } }