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; /** * 退货能力。信仓无此接口,整体不实现。 + * + *

退货链路有两个不同的「处理方式」,别混:

+ * */ public interface WarehouseReturnCapable extends WarehouseAdapter { - /** 按 OMS 退货单号查。 */ - WarehouseReturn get(WarehouseContext ctx, String returnRequestNo); + /** + * 创建退货预约。写操作,幂等键 + * {@code warehouseCode + returnRequestNo + "create"}。 + */ + WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd); - /** 分页查退货单。 */ - Page query(WarehouseContext ctx, String cursor); + /** + * 按 OMS 退货单号查。 + * + *

方法名带 {@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 queryReturns(WarehouseContext ctx, String cursor); + + /** + * 按明细行设置检验后处理方式。写操作,幂等键 + * {@code warehouseCode + providerReturnNo + lineId + "process"}。 + */ + void process(WarehouseContext ctx, ReturnProcessCommand cmd); /** 取消退货单;仅部分仓支持。 */ default void cancel(WarehouseContext ctx, String returnRequestNo) { diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java new file mode 100644 index 0000000..2e77980 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java @@ -0,0 +1,217 @@ +package common.ecommerce.warehouse.model; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 退货计划创建命令。写操作,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。 + * + *

运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行; + * 每条商品行还必须给处理方式。

+ */ +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 lines; + + private ReturnCommand(Builder b) { + this.returnRequestNo = require(b.returnRequestNo, "returnRequestNo"); + this.warehouseId = b.warehouseId; + this.saleOrderNo = require(b.saleOrderNo, "saleOrderNo"); + this.returnTrackingNo = require(b.returnTrackingNo, "returnTrackingNo"); + this.carrierCode = require(b.carrierCode, "carrierCode"); + this.estimatedReceiveDate = b.estimatedReceiveDate; + this.returnReason = b.returnReason; + this.remark = b.remark; + if (b.lines.isEmpty()) { + throw new IllegalArgumentException("lines must not be empty"); + } + this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); + } + + public static Builder builder() { + return new Builder(); + } + + /** OMS 退货单号;同时是仓方的来源单号与幂等键。 */ + public String returnRequestNo() { + return returnRequestNo; + } + + /** 仓 code;null 时用账户配置的仓。 */ + public String warehouseId() { + return warehouseId; + } + + /** 关联的销售订单号,必填。 */ + public String saleOrderNo() { + return saleOrderNo; + } + + public String returnTrackingNo() { + return returnTrackingNo; + } + + public String carrierCode() { + return carrierCode; + } + + public LocalDate estimatedReceiveDate() { + return estimatedReceiveDate; + } + + public String returnReason() { + return returnReason; + } + + public String remark() { + return remark; + } + + public List lines() { + return lines; + } + + private static String require(String v, String n) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(n + " must not be blank"); + } + return v.trim(); + } + + /** + * 退货商品行。 + * + *

{@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 lines = new ArrayList(); + + public Builder returnRequestNo(String v) { + this.returnRequestNo = v; + return this; + } + + public Builder warehouseId(String v) { + this.warehouseId = v; + return this; + } + + public Builder saleOrderNo(String v) { + this.saleOrderNo = v; + return this; + } + + public Builder returnTrackingNo(String v) { + this.returnTrackingNo = v; + return this; + } + + public Builder carrierCode(String v) { + this.carrierCode = v; + return this; + } + + public Builder estimatedReceiveDate(LocalDate v) { + this.estimatedReceiveDate = v; + return this; + } + + public Builder returnReason(String v) { + this.returnReason = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + public Builder line(String providerSku, int quantity, DealMethod dealMethod) { + this.lines.add(new ReturnCommandLine(providerSku, quantity, dealMethod)); + return this; + } + + public ReturnCommand build() { + return new ReturnCommand(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java new file mode 100644 index 0000000..2a67ebb --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java @@ -0,0 +1,124 @@ +package common.ecommerce.warehouse.model; + +/** + * 退货条目处理命令(API 77 / 检验后决定)。 + * + *

与 {@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 result = + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + cmd.returnRequestNo(), "create"), + () -> capable.create(ctx, cmd), + ret -> ret.providerReturnId()); + if (result.alreadyCompleted()) { + return WarehouseReturn.builder() + .returnRequestNo(cmd.returnRequestNo()) + .providerReturnId(result.resultRef()) + .warehouseCode(account.warehouseCode()) + .build(); + } + return result.value(); + } + public WarehouseReturn get(String returnRequestNo) { require(WarehouseCapability.RETURN, WarehouseReturnCapable.class); return CallSupport.observe(observer, ctx, "warehouse.return.get", CallSupport.params("returnRequestNo", returnRequestNo), r -> 1, - () -> ((WarehouseReturnCapable) adapter).get(ctx, returnRequestNo)); + () -> ((WarehouseReturnCapable) adapter).getReturn(ctx, returnRequestNo)); } public Page query(String cursor) { @@ -248,12 +276,30 @@ public final class WarehouseOperations { return CallSupport.observe(observer, ctx, "warehouse.return.query", CallSupport.params("cursor", cursor), p -> p.size(), - () -> ((WarehouseReturnCapable) adapter).query(ctx, cursor)); + () -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, cursor)); } - public void setDisposition(String returnRequestNo, WarehouseReturn.Disposition disposition) { + /** + * 按明细行设置检验后处理方式。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + providerReturnNo + lineId + process}。 + * + *

按明细行做键,而不是按整单:一张退货单的多行可以分别上架 / 销毁, + * 同一行重复下发才是重复。

+ */ + 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 Page queryReturns(WarehouseContext ctx, String cursor) { + throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); + } + // ------------------------------------------------------------------ internals /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java new file mode 100644 index 0000000..a27ae87 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java @@ -0,0 +1,84 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.warehouse.model.ReturnCommand; +import common.ecommerce.warehouse.model.ReturnProcessCommand; +import common.ecommerce.warehouse.model.WarehouseReturn; +import common.ecommerce.yqn.dto.YqnDtos; + +import java.time.LocalDate; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.List; + +/** + * 运去哪退货报文映射(API 81 创建 / API 77 条目处理)。 + */ +public final class YqnReturnMapper { + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + private YqnReturnMapper() { + } + + /** 统一命令 → 创建销售退货请求。 */ + public static YqnDtos.CreateSaleReturnRequest toRequest(ReturnCommand cmd, String warehouseCode) { + YqnDtos.CreateSaleReturnRequest req = new YqnDtos.CreateSaleReturnRequest(); + req.warehouseCode = warehouseCode; + req.orderNo = cmd.returnRequestNo(); + req.saleOrderNo = cmd.saleOrderNo(); + req.returnTrackingNo = cmd.returnTrackingNo(); + req.carrierCode = cmd.carrierCode(); + req.estimateReceiveDate = formatDate(cmd.estimatedReceiveDate()); + req.returnReason = cmd.returnReason(); + req.remark = cmd.remark(); + req.productItemRequests = toItems(cmd.lines()); + return req; + } + + private static List toItems( + List lines) { + List items = + new ArrayList(lines.size()); + for (ReturnCommand.ReturnCommandLine line : lines) { + YqnDtos.CreateSaleReturnRequest.SaleReturnItem item = + new YqnDtos.CreateSaleReturnRequest.SaleReturnItem(); + item.sku = line.providerSku(); + // 运去哪这个字段是 string;数量原样传字符串,不做格式化 + item.qty = String.valueOf(line.quantity()); + item.returnDealMethod = line.dealMethod().code(); + items.add(item); + } + return items; + } + + /** 统一命令 → 退货条目处理请求。 */ + public static YqnDtos.SaleReturnProcessRequest toProcessRequest(ReturnProcessCommand cmd) { + YqnDtos.SaleReturnProcessRequest req = new YqnDtos.SaleReturnProcessRequest(); + req.saleReturnPlanNo = cmd.providerReturnNo(); + req.id = cmd.lineId(); + req.goodsReturnType = cmd.disposition().code(); + req.newSku = cmd.newSku(); + req.remark = cmd.remark(); + return req; + } + + /** + * 创建退货的响应 → 统一退货单。 + * + *

API 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 productItemRequests; + + /** 退货商品行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SaleReturnItem { + public String sku; + /** 数量;文档标为 string。 */ + public String qty; + /** 0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。 */ + public Integer returnDealMethod; + } + } + + /** + * 退货条目处理请求(API 77)。 + * + *

文档把 {@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; + } }