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退货条目处理(如运去哪 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运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。
* - *实际不可用: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这个字段给的是中文文本而不是数字码:草稿 / 待审核 / 退货中 / + * 审核拒回 / 待收货 / 已完成 / 已关闭。按完整值精确匹配。
+ */ +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