Browse Source

feat(yqn): 按 API 81 / 77 对接创建销售退货与退货条目处理

- 路径 /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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
eb98688c4b
  1. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  2. 217
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java
  3. 124
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java
  4. 54
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  5. 8
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  6. 50
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  7. 84
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
  8. 53
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

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

@ -1,27 +1,46 @@
package common.ecommerce.warehouse.capability; package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Page; 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.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
/** /**
* 退货能力。信仓无此接口,整体不实现。 * 退货能力。信仓无此接口,整体不实现。
*
* <p>退货链路有两个不同的「处理方式」,别混:</p>
* <ul>
* <li>{@link ReturnCommand.DealMethod} —— 创建退货预约时的预报</li>
* <li>{@link ReturnProcessCommand.Disposition} —— 仓收货检验后按明细行最终决定</li>
* </ul>
*/ */
public interface WarehouseReturnCapable extends WarehouseAdapter { public interface WarehouseReturnCapable extends WarehouseAdapter {
/** 按 OMS 退货单号查。 */ /**
WarehouseReturn get(WarehouseContext ctx, String returnRequestNo); * 创建退货预约。<b>写操作</b>,幂等键
* {@code warehouseCode + returnRequestNo + "create"}。
*/
WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd);
/** 分页查退货单。 */ /**
Page<WarehouseReturn> query(WarehouseContext ctx, String cursor); * 按 OMS 退货单号查。
*
* <p>方法名带 {@code Return} 后缀:{@code InboundCapable} 已有完全同签名的
* {@code get(ctx, String)} / {@code query(ctx, String)},同一适配器实现两者时
* 泛型擦除后无法区分。</p>
*/
WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo);
/** 设置处理方式(二次上架 / 销毁);仅部分仓支持。 */ /** 分页查退货单;命名原因同 {@link #getReturn}。 */
default void setDisposition(WarehouseContext ctx, String returnRequestNo, Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor);
WarehouseReturn.Disposition disposition) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( /**
common.ecommerce.warehouse.WarehouseCapability.RETURN_DISPOSITION); * 按明细行设置检验后处理方式。<b>写操作</b>,幂等键
} * {@code warehouseCode + providerReturnNo + lineId + "process"}。
*/
void process(WarehouseContext ctx, ReturnProcessCommand cmd);
/** 取消退货单;仅部分仓支持。 */ /** 取消退货单;仅部分仓支持。 */
default void cancel(WarehouseContext ctx, String returnRequestNo) { default void cancel(WarehouseContext ctx, String returnRequestNo) {

217
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;
/**
* 退货计划创建命令。<b>写操作</b>,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。
*
* <p>运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行;
* 每条商品行还必须给处理方式。</p>
*/
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<ReturnCommandLine> 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<ReturnCommandLine>(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<ReturnCommandLine> 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();
}
/**
* 退货商品行。
*
* <p>{@link #dealMethod()} 是<b>退货预约时的处理方式</b>,与
* {@code ReturnProcessCommand.Disposition}(检验后处理方式)不是一回事:
* 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。</p>
*/
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 仓库确认。
*
* <p>注意 API 77 的检验后处理方式码值完全不同(0 自提 / 2 销毁 / 3 上架 / 4 换标上架),
* 两者不能混用。</p>
*/
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<ReturnCommandLine> lines = new ArrayList<ReturnCommandLine>();
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);
}
}
}

124
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java

@ -0,0 +1,124 @@
package common.ecommerce.warehouse.model;
/**
* 退货条目处理命令(API 77 / 检验后决定)。
*
* <p>与 {@code ReturnCommand.DealMethod}(预约时的预报)不是一回事:
* 这里是仓收货检验之后,逐条明细行最终决定怎么处理。</p>
*/
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 换标上架(良品)。
*
* <p>与预约时的处理方式码值不同,不能混用。</p>
*/
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);
}
}
}

54
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.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery; 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.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.TransferCapable;
@ -235,12 +237,38 @@ public final class WarehouseOperations {
/** 退货视图。 */ /** 退货视图。 */
public final class ReturnView { public final class ReturnView {
/**
* 创建退货预约。<b>写操作</b>:强制经幂等守卫,幂等键
* {@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<WarehouseReturn> 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) { public WarehouseReturn get(String returnRequestNo) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class); require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.return.get", return CallSupport.observe(observer, ctx, "warehouse.return.get",
CallSupport.params("returnRequestNo", returnRequestNo), CallSupport.params("returnRequestNo", returnRequestNo),
r -> 1, r -> 1,
() -> ((WarehouseReturnCapable) adapter).get(ctx, returnRequestNo)); () -> ((WarehouseReturnCapable) adapter).getReturn(ctx, returnRequestNo));
} }
public Page<WarehouseReturn> query(String cursor) { public Page<WarehouseReturn> query(String cursor) {
@ -248,12 +276,30 @@ public final class WarehouseOperations {
return CallSupport.observe(observer, ctx, "warehouse.return.query", return CallSupport.observe(observer, ctx, "warehouse.return.query",
CallSupport.params("cursor", cursor), CallSupport.params("cursor", cursor),
p -> p.size(), p -> p.size(),
() -> ((WarehouseReturnCapable) adapter).query(ctx, cursor)); () -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, cursor));
} }
public void setDisposition(String returnRequestNo, WarehouseReturn.Disposition disposition) { /**
* 按明细行设置检验后处理方式。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + providerReturnNo + lineId + process}。
*
* <p>按明细行做键,而不是按整单:一张退货单的多行可以分别上架 / 销毁,
* 同一行重复下发才是重复。</p>
*/
public void process(final ReturnProcessCommand cmd) {
require(WarehouseCapability.RETURN_DISPOSITION, WarehouseReturnCapable.class); 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);
} }
} }

8
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"; public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
/** 查询入库计划(API 101)。 */ /** 查询入库计划(API 101)。 */
public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo"; public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo";
/** 退货发起。 */ /** 创建销售退货(API 81)。 */
public static final String PATH_RETURN_CREATE = "/salereturn/SalesReturnCreate"; public static final String PATH_RETURN_CREATE = "/v3/saleReturn/createSaleReturnPlan";
/** 退货处理方式(二次上架 / 销毁)。 */ /** 退货条目处理(API 77):按明细行设置检验后处理方式。 */
public static final String PATH_RETURN_DISPOSITION = "/salereturn/SaleReturnAddProcessMode"; public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode";
/** 销毁计划。 */ /** 销毁计划。 */
public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate";
/** 物流轨迹。 */ /** 物流轨迹。 */

50
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.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery; 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.TransferCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.InventorySyncStrategy; import common.ecommerce.warehouse.model.InventorySyncStrategy;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
@ -62,7 +66,8 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p> * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/ */
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, 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"); 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.FEE_SETTLEMENT,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.INBOUND, 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)); return YqnTransferMapper.toOrder(resp, cmd.type(), zoneOf(ctx));
} }
// ------------------------------------------------------------------ 退货
/**
* 创建销售退货预约(API 81)。
*
* <p><b>响应只有 code/message,没有单号</b>:所以返回的
* {@code providerReturnId} 是 null。退货的仓侧单号只能靠后续查询或回调补。
* 这会影响「按仓单号做幂等 / 回查」的用法——按文档我们只能用来源单号。</p>
*/
@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)。
*
* <p>运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。</p>
*/
@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<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ internals // ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */

84
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<YqnDtos.CreateSaleReturnRequest.SaleReturnItem> toItems(
List<ReturnCommand.ReturnCommandLine> lines) {
List<YqnDtos.CreateSaleReturnRequest.SaleReturnItem> items =
new ArrayList<YqnDtos.CreateSaleReturnRequest.SaleReturnItem>(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;
}
/**
* 创建退货的响应 → 统一退货单。
*
* <p>API 81 <b>只回 code / message</b>,没有单号。所以这里只能用输入单号,
* {@code providerReturnId} 留 null——仓侧单号要么等查询接口,要么靠回调。</p>
*/
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);
}
}

53
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 trackingNo;
public String remark; 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<SaleReturnItem> 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)。
*
* <p>文档把 {@code newSku} / {@code remark} 标成必填,但语义上只在换标上架时
* 用 newSku;这里按「非换标时不传」处理,由服务端按 goodsReturnType 判断。</p>
*/
@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;
}
} }

Loading…
Cancel
Save