Browse Source
- 路径 /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
8 changed files with 609 additions and 20 deletions
@ -0,0 +1,217 @@
@@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,124 @@
@@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,84 @@
@@ -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); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue