Browse Source
新增 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
9 changed files with 781 additions and 15 deletions
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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…
Reference in new issue