From eb98688c4b0bd7bdf389e82dddb875ae68c0b818 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Mon, 9 Nov 2026 17:45:28 +0800
Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=2081=20/=2077=20?=
=?UTF-8?q?=E5=AF=B9=E6=8E=A5=E5=88=9B=E5=BB=BA=E9=94=80=E5=94=AE=E9=80=80?=
=?UTF-8?q?=E8=B4=A7=E4=B8=8E=E9=80=80=E8=B4=A7=E6=9D=A1=E7=9B=AE=E5=A4=84?=
=?UTF-8?q?=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 路径 /salereturn/SalesReturnCreate → /v3/saleReturn/createSaleReturnPlan
- 路径 /salereturn/SaleReturnAddProcessMode → /v3/saleReturn/addProcessMode
两套「处理方式」不能混用,各建各的枚举:
- ReturnCommand.DealMethod(预约预报):0 客户自提 / 1 拍照确认 /
2 销毁 / 5 仓库确认
- ReturnProcessCommand.Disposition(检验后决定):0 客户自提 / 2 销毁 /
3 上架良品 / 4 换标上架
码值完全不同,共用一套会静默错处理。
接口层面的两个硬约束:
- API 81 响应只有 code/message,没有单号。providerReturnId 只能是 null,
按仓单号回查这条路走不通,只能用来源单号;已在 Javadoc 里写明
- API 77 按明细行 id 操作,所以幂等键是
warehouseCode + providerReturnNo + lineId + process,
而不是整单——一张退货单的多行可以分别上架/销毁
另外修了一处会导致编译失败的设计冲突:InboundCapable 与
WarehouseReturnCapable 原本都有 get(ctx, String) / query(ctx, String),
同一适配器实现两者时泛型擦除后签名冲突。退货侧改名为
getReturn / queryReturns。
ReturnView.setDisposition 换成 process(ReturnProcessCommand):
原方法只有整单 + 枚举,装不下「哪一行 + 换标新 SKU」。
Co-Authored-By: Claude
---
.../capability/WarehouseReturnCapable.java | 39 +++-
.../ecommerce/warehouse/model/ReturnCommand.java | 217 +++++++++++++++++++++
.../warehouse/model/ReturnProcessCommand.java | 124 ++++++++++++
.../warehouse/sdk/WarehouseOperations.java | 54 ++++-
.../java/common/ecommerce/yqn/YqnConstants.java | 8 +-
.../common/ecommerce/yqn/adapter/YqnAdapter.java | 50 ++++-
.../ecommerce/yqn/adapter/YqnReturnMapper.java | 84 ++++++++
.../java/common/ecommerce/yqn/dto/YqnDtos.java | 53 +++++
8 files changed, 609 insertions(+), 20 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java
create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
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;
/**
* 退货能力。信仓无此接口,整体不实现。
+ *
+ * 退货链路有两个不同的「处理方式」,别混:
+ *
+ * - {@link ReturnCommand.DealMethod} —— 创建退货预约时的预报
+ * - {@link ReturnProcessCommand.Disposition} —— 仓收货检验后按明细行最终决定
+ *
*/
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;
+ }
}