From 208b549c96b3b6473b47df3bb8233c5682fe45e9 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 11 Nov 2026 09:51:57 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8E=A5=E5=85=A5=E9=94=80?= =?UTF-8?q?=E5=94=AE=E9=80=80=E8=B4=A7=E8=AE=A1=E5=88=92=E6=9F=A5=E8=AF=A2?= =?UTF-8?q?=EF=BC=8C=E9=80=80=E8=B4=A7=E9=93=BE=E8=B7=AF=E9=97=AD=E7=8E=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 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 --- README.md | 4 +- .../ecommerce/warehouse/enums/ReturnStatus.java | 55 +++++ .../ecommerce/warehouse/model/WarehouseReturn.java | 240 ++++++++++++++++++++- .../java/common/ecommerce/yqn/YqnConstants.java | 2 + .../common/ecommerce/yqn/adapter/YqnAdapter.java | 43 +++- .../ecommerce/yqn/adapter/YqnReturnMapper.java | 94 +++++++- .../ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java | 106 +++++++++ .../ecommerce/yqn/enums/YqnReturnPlanStatus.java | 69 ++++++ .../ecommerce/yqn/adapter/YqnReturnQueryTest.java | 183 ++++++++++++++++ 9 files changed, 781 insertions(+), 15 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java diff --git a/README.md b/README.md index b16b0e7..6e2c118 100644 --- a/README.md +++ b/README.md @@ -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 │ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos / │ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos / │ │ YqnCreateInboundDtos / YqnInboundPlanDtos / YqnTransferDtos / -│ │ YqnCreateSaleReturnDtos / YqnReturnProcessDtos / +│ │ YqnCreateSaleReturnDtos / YqnSaleReturnPlanDtos / YqnReturnProcessDtos / │ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos / │ │ YqnBoxLabelDtos / YqnSkuLabelDtos / │ │ YqnLogisticsProductDtos / YqnWarehouseDtos / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java new file mode 100644 index 0000000..288b6be --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnStatus.java @@ -0,0 +1,55 @@ +package common.ecommerce.warehouse.enums; + +/** + * 退货单状态(底层枚举)。 + * + *

各仓的状态在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里; + * 本枚举不认识任何仓的码值。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java index 3c5936a..774c761 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java @@ -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 { 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 { private final ReturnProcessDisposition disposition; private final List 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 attachments; private WarehouseReturn(Builder b) { this.returnRequestNo = require(b.returnRequestNo, "returnRequestNo"); @@ -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(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(b.attachments)); } public static Builder builder() { @@ -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 { 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 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 { /** 退货明细行。 */ public static final class ReturnLine { + /** + * 仓侧明细行 id。 + * + *

退货条目处理(如运去哪 API 77)的操作键。取自退货查询接口的 + * {@code items[].id},只能从这里拿。

+ */ + 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 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(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 { 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 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 pictureUrls = new ArrayList(); + 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 { 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 lines = new ArrayList(); private Instant createdAt; + private Instant actualReceivedAt; + private Integer inspectedQuantity; + private String relatedProcessNo; + private String lineName; + private final List attachments = new ArrayList(); public Builder returnRequestNo(String v) { this.returnRequestNo = v; @@ -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 { 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); } 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 7c6c714..cf453f1 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 @@ -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)。 */ 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 e2dac0f..2a0fe47 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 @@ -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 * *

运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。

* - *

实际不可用:API 77 要求传仓侧明细行 {@code id},而运去哪没有退货 - * 查询接口、API 142 回调的 items 也不带 id,调用方拿不到这个值。 - * 运去哪的退货处理方式由仓侧决定并通过回调(API 142)通知, - * 不要让 OMS 主动调用本方法。

+ *

{@code lineId} 取自 {@link #getReturn}(API 83)的 + * {@code saleReturnOrderItems[].id}——回调(API 142)里不带这个值, + * 必须先用查询接口拿。典型用法:

+ *
+     * WarehouseReturn detail = returns().get(returnRequestNo);
+     * detail.lines().stream().filter(l -> ...)
+     *       .forEach(l -> returns().process(ReturnProcessCommand.builder()
+     *               .providerReturnNo(detail.providerReturnId())
+     *               .lineId(l.lineId())
+     *               .disposition(RETURN_REPLABEL)
+     *               .newSku(...)
+     *               .build()));
+     * 
*/ @Override public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { @@ -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)。 + * + *

响应里的 {@code saleReturnOrderItems[].id} 是退货条目处理(API 77)要求的 + * 明细行 id——这是唯一能拿到它的途径。宿主应当先查一次详情,再用其中的 + * 行 id 去调 {@link #process}。

+ * + * @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 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 index 396c44f..0f8b6be 100644 --- 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 @@ -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 { .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)。 + * + *

关键:{@code saleReturnOrderItems[].id} 是退货条目处理(API 77) + * 要求的明细行 id,映射到 {@link WarehouseReturn.ReturnLine#lineId()}。

+ */ + 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); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java new file mode 100644 index 0000000..61284f3 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnSaleReturnPlanDtos.java @@ -0,0 +1,106 @@ +package common.ecommerce.yqn.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 运去哪报文结构:销售退货计划查询(API 83,/v3/saleReturn/getInboundPlanInfo)。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构; + * 与其它接口共用的结构各自复制一份,避免跨接口耦合。

+ * + *

这是退货链路的关键补位:{@code saleReturnOrderItems[].id} 就是 + * 退货条目处理(API 77)要求传的明细行 id,只能从这里拿。

+ */ +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 planProductDetailParamList; + /** 退货入库执行单明细;{@code id} 即 API 77 的明细行 id。 */ + public List saleReturnOrderItems; + /** 附件信息。 */ + public List 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;API 77 的明细行 id。 */ + 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 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; + } + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java new file mode 100644 index 0000000..c621604 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnPlanStatus.java @@ -0,0 +1,69 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.ReturnStatus; + +/** + * 运去哪销售退货计划状态(API 83 的 {@code saleReturnPlanStatus})。 + * + *

这个字段给的是中文文本而不是数字码:草稿 / 待审核 / 退货中 / + * 审核拒回 / 待收货 / 已完成 / 已关闭。按完整值精确匹配。

+ */ +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(); + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java new file mode 100644 index 0000000..de548ef --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java @@ -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)。 + * + *

重点是 {@code saleReturnOrderItems[].id}:退货条目处理(API 77)的操作键, + * 只能从这里拿。

+ */ +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 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 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 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)); + } +}