Browse Source

feat(yqn): 接入销售退货计划查询,退货链路闭环

新增 API 83(POST /v3/saleReturn/getInboundPlanInfo)。这个接口补上了
退货链路的关键缺口:saleReturnOrderItems[].id 就是退货条目处理(API 77)
要求的明细行 id,之前没有任何途径能拿到。

链路现在是:
  创建退货(API 81)
   → 退货入库完成回调(API 142,通知处理结果)
   → 退货计划查询(API 83,拿明细行 id)
   → 退货条目处理(API 77,按行设置处理方式)

模型变更:
- WarehouseReturn.status 从 String 改为 ReturnStatus 枚举(新增底层枚举:
  草稿/待审核/审核拒绝/退货中/待收货/已完成/已关闭/UNKNOWN);仓方原值仍在
  rawStatus。运去哪的状态是中文文本,按完整值精确匹配,未知归 UNKNOWN
- WarehouseReturn 补头级字段:actualReceivedAt / inspectedQuantity /
  relatedProcessNo / lineName / attachments
- ReturnLine 补:lineId(API 77 操作键)、inventoryType、processedQuantity、
  suggestedDisposition、newSku、pictureUrls、remark

顺带修正 toCreated:status 之前硬编码字符串 "SUBMITTED",现在为 UNKNOWN
——创建接口不回状态,真实状态要查 API 83 才知道。

新增 YqnReturnQueryTest(9 个):头级字段、明细行 id、行明细、附件、
状态枚举全量映射、未知状态、空 data、空单号拒绝。

全量 421 个测试通过。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
208b549c96
  1. 4
      README.md
  2. 55
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java
  3. 240
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java
  4. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  5. 43
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  6. 94
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
  7. 106
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java
  8. 69
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java
  9. 183
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java

4
README.md

@ -299,7 +299,7 @@ common.ecommerce @@ -299,7 +299,7 @@ common.ecommerce
│ │ WarehouseProvider / WarehouseCapability / OutboundStatus /
│ │ InboundStatus / TransferStatus / TransferType / LabelMode /
│ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType /
│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / WarehouseEventType /
│ │ ReturnDealMethod / ReturnProcessDisposition / ReturnStatus / AttachmentType / WarehouseEventType /
│ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType
│ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine /
│ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec /
@ -334,7 +334,7 @@ common.ecommerce @@ -334,7 +334,7 @@ common.ecommerce
│ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos /
│ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos /
│ │ YqnCreateInboundDtos / YqnInboundPlanDtos / YqnTransferDtos /
│ │ YqnCreateSaleReturnDtos / YqnReturnProcessDtos /
│ │ YqnCreateSaleReturnDtos / YqnSaleReturnPlanDtos / YqnReturnProcessDtos /
│ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos /
│ │ YqnBoxLabelDtos / YqnSkuLabelDtos /
│ │ YqnLogisticsProductDtos / YqnWarehouseDtos /

55
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java

@ -0,0 +1,55 @@ @@ -0,0 +1,55 @@
package common.ecommerce.warehouse.enums;
/**
* 退货单状态(底层枚举)。
*
* <p>各仓的状态在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里;
* 本枚举不认识任何仓的码值。</p>
*/
public enum ReturnStatus {
/** 草稿。 */
DRAFT(10, "草稿"),
/** 待审核。 */
PENDING_REVIEW(20, "待审核"),
/** 审核拒绝。 */
REJECTED(30, "审核拒绝"),
/** 退货中(在途 / 待收货)。 */
RETURNING(40, "退货中"),
/** 待收货。 */
PENDING_RECEIPT(50, "待收货"),
/** 已完成。 */
COMPLETED(60, "已完成"),
/** 已关闭。 */
CLOSED(70, "已关闭"),
/** 无法识别;原值见 {@code rawStatus}。 */
UNKNOWN(0, "未知");
private final int code;
private final String label;
ReturnStatus(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查。 */
public static ReturnStatus ofCode(int code) {
for (ReturnStatus s : values()) {
if (s.code == code) {
return s;
}
}
return UNKNOWN;
}
}

240
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java

@ -1,6 +1,7 @@ @@ -1,6 +1,7 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.shared.support.Money;
@ -19,8 +20,8 @@ public final class WarehouseReturn { @@ -19,8 +20,8 @@ public final class WarehouseReturn {
private final String orderRef;
/** 退货类型原值,由适配器解释。 */
private final String type;
/** 退货单状态;暂无统一枚举(运去哪查询接口未接入),先透传平台值。 */
private final String status;
/** 退货单状态,已归一化。 */
private final ReturnStatus status;
/** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */
private final String rawStatus;
/** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */
@ -29,6 +30,16 @@ public final class WarehouseReturn { @@ -29,6 +30,16 @@ public final class WarehouseReturn {
private final ReturnProcessDisposition disposition;
private final List<ReturnLine> lines;
private final Instant createdAt;
/** 实际收货时间(UTC);未收货为 null。 */
private final Instant actualReceivedAt;
/** 质检数量;仓方未给时为 null。 */
private final Integer inspectedQuantity;
/** 关联处理计划单号。 */
private final String relatedProcessNo;
/** 项目名称。 */
private final String lineName;
/** 附件。 */
private final List<Attachment> attachments;
private WarehouseReturn(Builder b) {
this.returnRequestNo = require(b.returnRequestNo, "returnRequestNo");
@ -36,12 +47,17 @@ public final class WarehouseReturn { @@ -36,12 +47,17 @@ public final class WarehouseReturn {
this.warehouseCode = require(b.warehouseCode, "warehouseCode");
this.orderRef = b.orderRef;
this.type = b.type;
this.status = b.status;
this.status = b.status == null ? ReturnStatus.UNKNOWN : b.status;
this.rawStatus = b.rawStatus;
this.sourceProvider = b.sourceProvider;
this.disposition = b.disposition == null ? ReturnProcessDisposition.UNKNOWN : b.disposition;
this.lines = Collections.unmodifiableList(new ArrayList<ReturnLine>(b.lines));
this.createdAt = b.createdAt;
this.actualReceivedAt = b.actualReceivedAt;
this.inspectedQuantity = b.inspectedQuantity;
this.relatedProcessNo = b.relatedProcessNo;
this.lineName = b.lineName;
this.attachments = Collections.unmodifiableList(new ArrayList<Attachment>(b.attachments));
}
public static Builder builder() {
@ -68,7 +84,7 @@ public final class WarehouseReturn { @@ -68,7 +84,7 @@ public final class WarehouseReturn {
return type;
}
public String status() {
public ReturnStatus status() {
return status;
}
@ -88,6 +104,87 @@ public final class WarehouseReturn { @@ -88,6 +104,87 @@ public final class WarehouseReturn {
return createdAt;
}
/** 实际收货时间;未收货为 null。 */
public Instant actualReceivedAt() {
return actualReceivedAt;
}
/** 质检数量;仓方未给时为 null。 */
public Integer inspectedQuantity() {
return inspectedQuantity;
}
/** 关联处理计划单号;仓方未给时为 null。 */
public String relatedProcessNo() {
return relatedProcessNo;
}
/** 项目名称;仓方未给时为 null。 */
public String lineName() {
return lineName;
}
/** 附件;不可变。 */
public List<Attachment> attachments() {
return attachments;
}
/** 退货单附件。 */
public static final class Attachment {
private final String name;
private final String type;
private final String url;
private Attachment(Builder b) {
this.name = b.name;
this.type = b.type;
this.url = b.url;
}
public static Builder builder() {
return new Builder();
}
public String name() {
return name;
}
/** 仓方附件类型原值。 */
public String type() {
return type;
}
public String url() {
return url;
}
public static final class Builder {
private String name;
private String type;
private String url;
public Builder name(String v) {
this.name = v;
return this;
}
public Builder type(String v) {
this.type = v;
return this;
}
public Builder url(String v) {
this.url = v;
return this;
}
public Attachment build() {
return new Attachment(this);
}
}
}
/** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() {
return sourceProvider;
@ -103,22 +200,52 @@ public final class WarehouseReturn { @@ -103,22 +200,52 @@ public final class WarehouseReturn {
/** 退货明细行。 */
public static final class ReturnLine {
/**
* 仓侧明细行 id。
*
* <p>退货条目处理(如运去哪 API 77)的操作键。取自退货查询接口的
* {@code items[].id},只能从这里拿。</p>
*/
private final Long lineId;
private final String omsSku;
private final String providerSku;
private final int quantity;
private final Money refundAmount;
/** 库存类型:0 可售 / 1 不可售;仓方未给时为 null。 */
private final Integer inventoryType;
/** 已处理数量;仓方未给时为 null。 */
private final Integer processedQuantity;
/** 仓方建议处理方式原值;语义由适配器的平台枚举解释。 */
private final String suggestedDisposition;
/** 换标 SKU(换标上架时)。 */
private final String newSku;
/** 仓方拍的照片地址。 */
private final List<String> pictureUrls;
private final String remark;
private ReturnLine(Builder b) {
this.lineId = b.lineId;
this.omsSku = b.omsSku;
this.providerSku = b.providerSku;
this.quantity = b.quantity;
this.refundAmount = b.refundAmount;
this.inventoryType = b.inventoryType;
this.processedQuantity = b.processedQuantity;
this.suggestedDisposition = b.suggestedDisposition;
this.newSku = b.newSku;
this.pictureUrls = Collections.unmodifiableList(new ArrayList<String>(b.pictureUrls));
this.remark = b.remark;
}
public static Builder builder() {
return new Builder();
}
/** 仓侧明细行 id;退货条目处理的操作键。 */
public Long lineId() {
return lineId;
}
public String omsSku() {
return omsSku;
}
@ -135,11 +262,82 @@ public final class WarehouseReturn { @@ -135,11 +262,82 @@ public final class WarehouseReturn {
return refundAmount;
}
/** 库存类型:0 可售 / 1 不可售;未给为 null。 */
public Integer inventoryType() {
return inventoryType;
}
/** 已处理数量;未给为 null。 */
public Integer processedQuantity() {
return processedQuantity;
}
/** 仓方建议处理方式原值。 */
public String suggestedDisposition() {
return suggestedDisposition;
}
/** 换标后的 SKU;仅换标上架时有值。 */
public String newSku() {
return newSku;
}
/** 仓方照片地址;不可变。 */
public List<String> pictureUrls() {
return pictureUrls;
}
public String remark() {
return remark;
}
public static final class Builder {
private Long lineId;
private String omsSku;
private String providerSku;
private int quantity;
private Money refundAmount;
private Integer inventoryType;
private Integer processedQuantity;
private String suggestedDisposition;
private String newSku;
private final List<String> pictureUrls = new ArrayList<String>();
private String remark;
public Builder lineId(Long v) {
this.lineId = v;
return this;
}
public Builder inventoryType(Integer v) {
this.inventoryType = v;
return this;
}
public Builder processedQuantity(Integer v) {
this.processedQuantity = v;
return this;
}
public Builder suggestedDisposition(String v) {
this.suggestedDisposition = v;
return this;
}
public Builder newSku(String v) {
this.newSku = v;
return this;
}
public Builder pictureUrl(String v) {
this.pictureUrls.add(v);
return this;
}
public Builder remark(String v) {
this.remark = v;
return this;
}
public Builder omsSku(String v) {
this.omsSku = v;
@ -173,12 +371,17 @@ public final class WarehouseReturn { @@ -173,12 +371,17 @@ public final class WarehouseReturn {
private String warehouseCode;
private String orderRef;
private String type;
private String status;
private ReturnStatus status;
private String rawStatus;
private WarehouseProvider sourceProvider;
private ReturnProcessDisposition disposition;
private final List<ReturnLine> lines = new ArrayList<ReturnLine>();
private Instant createdAt;
private Instant actualReceivedAt;
private Integer inspectedQuantity;
private String relatedProcessNo;
private String lineName;
private final List<Attachment> attachments = new ArrayList<Attachment>();
public Builder returnRequestNo(String v) {
this.returnRequestNo = v;
@ -205,7 +408,7 @@ public final class WarehouseReturn { @@ -205,7 +408,7 @@ public final class WarehouseReturn {
return this;
}
public Builder status(String v) {
public Builder status(ReturnStatus v) {
this.status = v;
return this;
}
@ -242,6 +445,31 @@ public final class WarehouseReturn { @@ -242,6 +445,31 @@ public final class WarehouseReturn {
return this;
}
public Builder actualReceivedAt(Instant v) {
this.actualReceivedAt = v;
return this;
}
public Builder inspectedQuantity(Integer v) {
this.inspectedQuantity = v;
return this;
}
public Builder relatedProcessNo(String v) {
this.relatedProcessNo = v;
return this;
}
public Builder lineName(String v) {
this.lineName = v;
return this;
}
public Builder attachment(Attachment v) {
this.attachments.add(v);
return this;
}
public WarehouseReturn build() {
return new WarehouseReturn(this);
}

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -46,6 +46,8 @@ public final class YqnConstants { @@ -46,6 +46,8 @@ public final class YqnConstants {
public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo";
/** 创建销售退货(API 81)。 */
public static final String PATH_RETURN_CREATE = "/v3/saleReturn/createSaleReturnPlan";
/** 销售退货计划查询(API 83):按退货单号取详情,含明细行 id。 */
public static final String PATH_RETURN_GET = "/v3/saleReturn/getInboundPlanInfo";
/** 退货条目处理(API 77):按明细行设置检验后处理方式。 */
public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode";
/** 创建销毁计划(API 88)。 */

43
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -14,6 +14,7 @@ import common.ecommerce.yqn.dto.YqnLogisticsProductDtos; @@ -14,6 +14,7 @@ import common.ecommerce.yqn.dto.YqnLogisticsProductDtos;
import common.ecommerce.yqn.dto.YqnOrderDetailDtos;
import common.ecommerce.yqn.dto.YqnProductDtos;
import common.ecommerce.yqn.dto.YqnReturnProcessDtos;
import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos;
import common.ecommerce.yqn.dto.YqnSkuLabelDtos;
import common.ecommerce.yqn.dto.YqnTrackingDtos;
import common.ecommerce.yqn.dto.YqnTransferDtos;
@ -517,10 +518,19 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -517,10 +518,19 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
*
* <p>运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。</p>
*
* <p><b>实际不可用</b>:API 77 要求传仓侧明细行 {@code id},而运去哪没有退货
* 查询接口、API 142 回调的 items 也不带 id,调用方拿不到这个值。
* 运去哪的退货处理方式由仓侧决定并通过回调(API 142)通知,
* 不要让 OMS 主动调用本方法。</p>
* <p>{@code lineId} 取自 {@link #getReturn}(API 83)的
* {@code saleReturnOrderItems[].id}——回调(API 142)里不带这个值,
* 必须先用查询接口拿。典型用法:</p>
* <pre>
* WarehouseReturn detail = returns().get(returnRequestNo);
* detail.lines().stream().filter(l -&gt; ...)
* .forEach(l -&gt; returns().process(ReturnProcessCommand.builder()
* .providerReturnNo(detail.providerReturnId())
* .lineId(l.lineId())
* .disposition(RETURN_REPLABEL)
* .newSku(...)
* .build()));
* </pre>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
@ -528,10 +538,31 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -528,10 +538,31 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
execute(ctx, YqnConstants.PATH_RETURN_PROCESS, body, "warehouse.return.process");
}
/** 退货查询未接入:文档只给了创建(81)与条目处理(77)。 */
/**
* 查询销售退货计划(API 83)。
*
* <p>响应里的 {@code saleReturnOrderItems[].id} 是退货条目处理(API 77)要求的
* 明细行 id——这是唯一能拿到它的途径。宿主应当先查一次详情,再用其中的
* 行 id 去调 {@link #process}。</p>
*
* @param returnRequestNo 退货单号(运去哪的 orderNo)
*/
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
if (returnRequestNo == null || returnRequestNo.trim().isEmpty()) {
throw new IllegalArgumentException("yqn needs a return order no to query");
}
YqnSaleReturnPlanDtos.GetSaleReturnPlanRequest body =
new YqnSaleReturnPlanDtos.GetSaleReturnPlanRequest();
body.orderNo = returnRequestNo.trim();
String raw = execute(ctx, YqnConstants.PATH_RETURN_GET, body, "warehouse.return.get");
com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
YqnSaleReturnPlanDtos.SaleReturnPlanInfo info =
json.fromJson(data.toString(), YqnSaleReturnPlanDtos.SaleReturnPlanInfo.class);
return YqnReturnMapper.toReturn(info, ctx.warehouseCode(), zoneOf(ctx));
}
@Override

94
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java

@ -1,12 +1,14 @@ @@ -1,12 +1,14 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.yqn.dto.YqnCreateSaleReturnDtos;
import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos;
import common.ecommerce.yqn.dto.YqnReturnProcessDtos;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.yqn.enums.YqnReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.yqn.enums.YqnReturnPlanStatus;
import common.ecommerce.yqn.enums.YqnReturnProcessDisposition;
import java.time.LocalDate;
@ -78,12 +80,102 @@ public final class YqnReturnMapper { @@ -78,12 +80,102 @@ public final class YqnReturnMapper {
.returnRequestNo(cmd.returnRequestNo())
.warehouseCode(warehouseCode)
.orderRef(cmd.saleOrderNo())
.status("SUBMITTED")
// API 81 只回 code/message,没有状态;仓侧状态要查询(API 83)才知道
.status(common.ecommerce.warehouse.enums.ReturnStatus.UNKNOWN)
.rawStatus(null)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build();
}
/**
* 查询响应 → 统一退货单(API 83)。
*
* <p><b>关键</b>:{@code saleReturnOrderItems[].id} 是退货条目处理(API 77)
* 要求的明细行 id,映射到 {@link WarehouseReturn.ReturnLine#lineId()}。</p>
*/
public static WarehouseReturn toReturn(YqnSaleReturnPlanDtos.SaleReturnPlanInfo info,
String warehouseCode, java.time.ZoneId zone) {
WarehouseReturn.Builder builder = WarehouseReturn.builder()
.returnRequestNo(firstNonBlank(info.sourceNo, info.saleReturnPlanNo))
.providerReturnId(info.saleReturnPlanNo)
.warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode))
.orderRef(info.saleOrderNo)
.lineName(info.lineName)
.status(YqnReturnPlanStatus.toCore(info.saleReturnPlanStatus))
.rawStatus(info.saleReturnPlanStatus)
.type(info.relProcessNo)
.inspectedQuantity(info.inspectQty)
.relatedProcessNo(info.relProcessNo)
.actualReceivedAt(parseTime(info.actualReceiveAt, zone))
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN);
if (info.saleReturnOrderItems != null) {
for (YqnSaleReturnPlanDtos.SaleReturnPlanInfo.SaleReturnOrderItem item
: info.saleReturnOrderItems) {
WarehouseReturn.ReturnLine.Builder line = WarehouseReturn.ReturnLine.builder()
.lineId(item.id)
.providerSku(item.sku)
.quantity(item.qty == null ? 0 : item.qty)
.inventoryType(item.inventoryType)
.processedQuantity(item.qtyDone)
.suggestedDisposition(item.goodsReturnType)
.newSku(item.newSku)
.remark(item.processRemark != null ? item.processRemark : item.remark);
if (item.picturesUrl != null) {
for (String url : item.picturesUrl) {
line.pictureUrl(url);
}
}
builder.line(line.build());
}
}
if (info.orderAttachesItems != null) {
for (YqnSaleReturnPlanDtos.SaleReturnPlanInfo.ReturnAttach attach
: info.orderAttachesItems) {
builder.attachment(WarehouseReturn.Attachment.builder()
.name(attach.filename)
.type(attach.attachType)
.url(attach.fileurl)
.build());
}
}
return builder.build();
}
/** 查询时间解析:兼容 {@code yyyy-MM-dd HH:mm:ss}、{@code yyyy-MM-dd} 与 ISO。 */
static java.time.Instant parseTime(String value, java.time.ZoneId zone) {
if (value == null || value.trim().isEmpty()) {
return null;
}
String v = value.trim();
java.time.ZoneId z = zone == null ? java.time.ZoneOffset.UTC : zone;
try {
return java.time.LocalDateTime.parse(v,
java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
.atZone(z).toInstant();
} catch (java.time.format.DateTimeParseException ignored) {
// 试下一种
}
try {
return LocalDate.parse(v, DATE).atStartOfDay(z).toInstant();
} catch (java.time.format.DateTimeParseException ignored) {
// 试下一种
}
try {
return java.time.Instant.parse(v);
} catch (java.time.format.DateTimeParseException ignored) {
return null;
}
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
return b == null ? null : b.trim();
}
static String formatDate(LocalDate date) {
return date == null ? null : DATE.format(date);
}

106
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java

@ -0,0 +1,106 @@ @@ -0,0 +1,106 @@
package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 运去哪报文结构:销售退货计划查询(API 83,/v3/saleReturn/getInboundPlanInfo)。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构;
* 与其它接口共用的结构各自复制一份,避免跨接口耦合。</p>
*
* <p>这是退货链路的<b>关键补位</b>:{@code saleReturnOrderItems[].id} 就是
* 退货条目处理(API 77)要求传的明细行 id,只能从这里拿。</p>
*/
public final class YqnSaleReturnPlanDtos {
private YqnSaleReturnPlanDtos() {
}
/** 查询请求:只按退货单号查。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetSaleReturnPlanRequest {
/** 退货单号。 */
public String orderNo;
}
/** 退货计划详情(API 83 {@code data})。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaleReturnPlanInfo {
public String orgWarehouseCode;
public String lineName;
/** 仓库退货计划单号。 */
public String saleReturnPlanNo;
public String sourceNo;
public String saleOrderNo;
/** 销售退货状态(中文文本):草稿 / 待审核 / 退货中 / 审核拒回 / 待收货 / 已完成 / 已关闭。 */
public String saleReturnPlanStatus;
public String returnTrackingNo;
public String carrierCode;
public String estimateReceiveDate;
public String actualReceiveAt;
public String returnReason;
public String remark;
/** 关联处理计划单 id。 */
public Integer relProcessId;
/** 关联处理计划单号。 */
public String relProcessNo;
/** 质检数。 */
public Integer inspectQty;
/** 相关产品信息(计划维度)。 */
public List<PlanProduct> planProductDetailParamList;
/** 退货入库执行单明细;{@code id} 即 API 77 的明细行 id。 */
public List<SaleReturnOrderItem> saleReturnOrderItems;
/** 附件信息。 */
public List<ReturnAttach> orderAttachesItems;
/** 计划维度产品行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PlanProduct {
public String sku;
/** 退货数量。 */
public Integer qty;
/** 仓库接收数量。 */
public Integer qtyReceived;
/** 退货处理方式(原值,字符串)。 */
public String goodsReturnType;
}
/** 退货入库执行单的一行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaleReturnOrderItem {
/** 退货入库执行单 ID;<b>API 77 的明细行 id</b>。 */
public Long id;
public String productId;
public String sku;
/** 计划数量。 */
public Integer qty;
/** 库存类型:0 可售 / 1 不可售。 */
public Integer inventoryType;
public String updatedAt;
/** 处理数量。 */
public Integer qtyDone;
/** 建议处理方式:-1 未定义 / 0 自提 / 1 拍照确认 / 2 销毁 / 3 上架良品 / 4 换标上架 / 5 仓库确认。 */
public String goodsReturnType;
/** 更换后 SKU(换标上架时)。 */
public String newSku;
public String remark;
public String processRemark;
public List<String> picturesUrl;
public Boolean isRequireSn;
}
/** 附件。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ReturnAttach {
public Long id;
public Long orderId;
public String filename;
/** 附件类型。 */
public String attachType;
public String fileurl;
}
}
}

69
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java

@ -0,0 +1,69 @@ @@ -0,0 +1,69 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.ReturnStatus;
/**
* 运去哪销售退货计划状态(API 83 的 {@code saleReturnPlanStatus})。
*
* <p>这个字段给的是<b>中文文本</b>而不是数字码:草稿 / 待审核 / 退货中 /
* 审核拒回 / 待收货 / 已完成 / 已关闭。按完整值精确匹配。</p>
*/
public enum YqnReturnPlanStatus {
/** 草稿。 */
DRAFT("草稿", ReturnStatus.DRAFT),
/** 待审核。 */
PENDING_REVIEW("待审核", ReturnStatus.PENDING_REVIEW),
/** 退货中。 */
RETURNING("退货中", ReturnStatus.RETURNING),
/** 审核拒回。 */
REJECTED("审核拒回", ReturnStatus.REJECTED),
/** 待收货。 */
PENDING_RECEIPT("待收货", ReturnStatus.PENDING_RECEIPT),
/** 已完成。 */
COMPLETED("已完成", ReturnStatus.COMPLETED),
/** 已关闭。 */
CLOSED("已关闭", ReturnStatus.CLOSED),
/** 无法识别。 */
UNKNOWN(null, ReturnStatus.UNKNOWN);
private final String rawValue;
private final ReturnStatus core;
YqnReturnPlanStatus(String rawValue, ReturnStatus core) {
this.rawValue = rawValue;
this.core = core;
}
/** 运去哪原值;null 表示无法识别。 */
public String rawValue() {
return rawValue;
}
/** 对应的底层状态。 */
public ReturnStatus toCore() {
return core;
}
/** 运去哪原值 → 平台枚举;精确匹配,未收录归 UNKNOWN。 */
public static YqnReturnPlanStatus of(String rawStatus) {
if (rawStatus == null) {
return UNKNOWN;
}
String s = rawStatus.trim();
if (s.isEmpty()) {
return UNKNOWN;
}
for (YqnReturnPlanStatus v : values()) {
if (v.rawValue != null && s.equals(v.rawValue)) {
return v;
}
}
return UNKNOWN;
}
/** 运去哪原值 → 底层状态。 */
public static ReturnStatus toCore(String rawStatus) {
return of(rawStatus).toCore();
}
}

183
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java

@ -0,0 +1,183 @@ @@ -0,0 +1,183 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.YqnConstants;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 销售退货计划查询(API 83)。
*
* <p>重点是 {@code saleReturnOrderItems[].id}:退货条目处理(API 77)的操作键,
* 只能从这里拿。</p>
*/
class YqnReturnQueryTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-11T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(YqnConstants.PR_BASE_URL,
ChannelSecret.builder().appSecret("key-1").build()),
"req-return-get", CLOCK);
}
private static final String FULL_BODY =
"{\"code\":\"200\",\"message\":\"ok\",\"data\":{"
+ "\"orgWarehouseCode\":\"RF_NY_US\",\"lineName\":\"默认项目\","
+ "\"saleReturnPlanNo\":\"SR20261111001\",\"sourceNo\":\"OMS-RT-001\","
+ "\"saleOrderNo\":\"OB-123\",\"saleReturnPlanStatus\":\"待收货\","
+ "\"returnTrackingNo\":\"1Z999\",\"carrierCode\":\"UPS\","
+ "\"estimateReceiveDate\":\"2026-11-20\","
+ "\"actualReceiveAt\":\"2026-11-21 08:30:00\","
+ "\"returnReason\":\"尺码不符\",\"remark\":\"备注\","
+ "\"relProcessId\":88,\"relProcessNo\":\"RP-88\",\"inspectQty\":4,"
+ "\"planProductDetailParamList\":["
+ "{\"sku\":\"DM00001\",\"qty\":3,\"qtyReceived\":3,\"goodsReturnType\":\"3\"}],"
+ "\"saleReturnOrderItems\":["
+ "{\"id\":1001,\"productId\":\"P1\",\"sku\":\"DM00001\",\"qty\":3,"
+ "\"inventoryType\":0,\"updatedAt\":\"2026-11-21 09:00:00\",\"qtyDone\":1,"
+ "\"goodsReturnType\":\"3\",\"newSku\":null,\"remark\":\"r1\","
+ "\"processRemark\":\"待上架\",\"picturesUrl\":[\"https://img/1.jpg\"],"
+ "\"isRequireSn\":false},"
+ "{\"id\":1002,\"productId\":\"P2\",\"sku\":\"DM00002\",\"qty\":1,"
+ "\"inventoryType\":1,\"qtyDone\":0,\"goodsReturnType\":\"2\","
+ "\"remark\":\"r2\",\"processRemark\":null,\"picturesUrl\":[]}],"
+ "\"orderAttachesItems\":[{\"id\":5,\"orderId\":88,\"filename\":\"凭证.pdf\","
+ "\"attachType\":\"BOL\",\"fileurl\":\"https://files/a.pdf\"}]}}";
private static WarehouseReturn query(String body) {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_RETURN_GET, req -> Responses.ok(body));
return new YqnAdapter(transport, new JacksonJsonCodec()).getReturn(ctx(), "OMS-RT-001");
}
@Test
void mapsHeader() {
WarehouseReturn ret = query(FULL_BODY);
assertEquals("OMS-RT-001", ret.returnRequestNo());
assertEquals("SR20261111001", ret.providerReturnId());
assertEquals("RF_NY_US", ret.warehouseCode());
assertEquals("OB-123", ret.orderRef());
assertEquals("默认项目", ret.lineName());
assertEquals(ReturnStatus.PENDING_RECEIPT, ret.status());
assertEquals("待收货", ret.rawStatus());
assertEquals(Integer.valueOf(4), ret.inspectedQuantity());
assertEquals("RP-88", ret.relatedProcessNo());
assertEquals(Instant.parse("2026-11-21T08:30:00Z"), ret.actualReceivedAt());
assertEquals(WarehouseProvider.YQN, ret.sourceProvider());
}
/** 明细行 id 是 API 77 的操作键,必须映射出来。 */
@Test
void mapsLineIds() {
List<WarehouseReturn.ReturnLine> lines = query(FULL_BODY).lines();
assertEquals(2, lines.size());
assertEquals(Long.valueOf(1001), lines.get(0).lineId());
assertEquals(Long.valueOf(1002), lines.get(1).lineId());
}
@Test
void mapsLineDetails() {
List<WarehouseReturn.ReturnLine> lines = query(FULL_BODY).lines();
WarehouseReturn.ReturnLine first = lines.get(0);
assertEquals("DM00001", first.providerSku());
assertEquals(3, first.quantity());
assertEquals(Integer.valueOf(0), first.inventoryType());
assertEquals(Integer.valueOf(1), first.processedQuantity());
assertEquals("3", first.suggestedDisposition());
assertEquals("待上架", first.remark());
assertEquals(1, first.pictureUrls().size());
assertEquals("https://img/1.jpg", first.pictureUrls().get(0));
// 换标场景的 newSku 为 null 是正常的
assertNull(first.newSku());
assertEquals(Integer.valueOf(1), lines.get(1).inventoryType());
}
@Test
void mapsAttachments() {
List<WarehouseReturn.Attachment> attachments = query(FULL_BODY).attachments();
assertEquals(1, attachments.size());
assertEquals("凭证.pdf", attachments.get(0).name());
assertEquals("BOL", attachments.get(0).type());
assertEquals("https://files/a.pdf", attachments.get(0).url());
}
@Test
void sendsOrderNo() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_RETURN_GET, req -> Responses.ok(FULL_BODY));
new YqnAdapter(transport, new JacksonJsonCodec()).getReturn(ctx(), "OMS-RT-001");
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"orderNo\":\"OMS-RT-001\""), body);
assertTrue(transport.lastDataRequest().url().endsWith("/v3/saleReturn/getInboundPlanInfo"));
}
/** 状态是中文文本,未知值归 UNKNOWN,不猜。 */
@Test
void unknownStatusIsUnknown() {
String body = "{\"code\":\"200\",\"data\":{\"orgWarehouseCode\":\"W\","
+ "\"saleReturnPlanNo\":\"SR1\",\"sourceNo\":\"S1\","
+ "\"saleReturnPlanStatus\":\"某个新状态\"}}";
WarehouseReturn ret = query(body);
assertEquals(ReturnStatus.UNKNOWN, ret.status());
assertEquals("某个新状态", ret.rawStatus());
}
@Test
void allDocumentedStatusesMap() {
assertStatus("草稿", ReturnStatus.DRAFT);
assertStatus("待审核", ReturnStatus.PENDING_REVIEW);
assertStatus("退货中", ReturnStatus.RETURNING);
assertStatus("审核拒回", ReturnStatus.REJECTED);
assertStatus("待收货", ReturnStatus.PENDING_RECEIPT);
assertStatus("已完成", ReturnStatus.COMPLETED);
assertStatus("已关闭", ReturnStatus.CLOSED);
}
private static void assertStatus(String raw, ReturnStatus expected) {
String body = "{\"code\":\"200\",\"data\":{\"orgWarehouseCode\":\"W\","
+ "\"saleReturnPlanNo\":\"SR1\",\"sourceNo\":\"S1\","
+ "\"saleReturnPlanStatus\":\"" + raw + "\"}}";
assertEquals(expected, query(body).status(), raw);
}
/** 查不到数据时返回 null,不是空对象。 */
@Test
void missingDataReturnsNull() {
assertNull(query("{\"code\":\"200\",\"message\":\"ok\"}"));
}
@Test
void blankOrderNoIsRejected() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertThrows(IllegalArgumentException.class, () -> adapter.getReturn(ctx(), " "));
assertThrows(IllegalArgumentException.class, () -> adapter.getReturn(ctx(), null));
}
}
Loading…
Cancel
Save