diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java
index 5a66e0f..aed3c9a 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java
@@ -12,6 +12,21 @@ import java.util.List;
*/
public final class InboundOrderBatch {
+ /**
+ * 批次阶段:计划批次 / 上架批次。
+ *
+ *
仓方分两段给:{@code planBatchItems} 是预报装箱的批次,
+ * {@code inboundBatchItems} 是实际收货上架的批次。两者数量可能不同
+ * (计划 60 / 实收 58),不区分就无法做短少核对。
+ */
+ public enum Phase {
+ /** 计划批次(预报)。 */
+ PLANNED,
+ /** 上架批次(实收)。 */
+ INBOUNDED
+ }
+
+ private final Phase phase;
private final String providerSku;
private final int quantity;
/** 箱唛号。 */
@@ -21,6 +36,7 @@ public final class InboundOrderBatch {
private final List params;
private InboundOrderBatch(Builder b) {
+ this.phase = b.phase;
this.providerSku = b.providerSku;
this.quantity = b.quantity;
this.cartonNo = b.cartonNo;
@@ -32,6 +48,11 @@ public final class InboundOrderBatch {
return new Builder();
}
+ /** 批次阶段;仓方未标明时为 null。 */
+ public Phase phase() {
+ return phase;
+ }
+
public String providerSku() {
return providerSku;
}
@@ -74,12 +95,18 @@ public final class InboundOrderBatch {
}
public static final class Builder {
+ private Phase phase;
private String providerSku;
private int quantity;
private String cartonNo;
private Integer inventoryType;
private final List params = new ArrayList();
+ public Builder phase(Phase v) {
+ this.phase = v;
+ return this;
+ }
+
public Builder providerSku(String v) {
this.providerSku = v;
return this;
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java
index 45b20c4..409033b 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java
@@ -259,16 +259,24 @@ public final class WarehouseCallback {
public static final class ReturnLinePayload {
private final Long lineId;
+ /** 仓方 SKU;换标上架场景下是换标后的 SKU。 */
private final String providerSku;
private final Integer quantity;
/** 仓方处理方式原值;语义解释由适配器对应的平台枚举负责。 */
private final String disposition;
+ /** 批次号(如运去哪的 PC 开头批次号)。 */
+ private final String batchNo;
+ /** 批次属性键值;换标上架场景下仓方不传。 */
+ private final java.util.List batchParams;
private ReturnLinePayload(Builder b) {
this.lineId = b.lineId;
this.providerSku = b.providerSku;
this.quantity = b.quantity;
this.disposition = b.disposition;
+ this.batchNo = b.batchNo;
+ this.batchParams = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.batchParams));
}
public static Builder builder() {
@@ -291,11 +299,44 @@ public final class WarehouseCallback {
return disposition;
}
+ /** 批次号;仓方未给时为 null。 */
+ public String batchNo() {
+ return batchNo;
+ }
+
+ /** 批次属性;换标上架时为空列表。 */
+ public java.util.List batchParams() {
+ return batchParams;
+ }
+
+ /** 一条批次属性。 */
+ public static final class BatchParam {
+
+ private final String key;
+ private final String value;
+
+ public BatchParam(String key, String value) {
+ this.key = key;
+ this.value = value;
+ }
+
+ public String key() {
+ return key;
+ }
+
+ public String value() {
+ return value;
+ }
+ }
+
public static final class Builder {
private Long lineId;
private String providerSku;
private Integer quantity;
private String disposition;
+ private String batchNo;
+ private final java.util.List batchParams =
+ new java.util.ArrayList();
public Builder lineId(Long v) {
this.lineId = v;
@@ -317,6 +358,16 @@ public final class WarehouseCallback {
return this;
}
+ public Builder batchNo(String v) {
+ this.batchNo = v;
+ return this;
+ }
+
+ public Builder batchParam(String key, String value) {
+ this.batchParams.add(new BatchParam(key, value));
+ return this;
+ }
+
public ReturnLinePayload build() {
return new ReturnLinePayload(this);
}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
index 5b00039..3038852 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
@@ -8,6 +8,7 @@ import common.ecommerce.warehouse.model.InboundCarton;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundLine;
import common.ecommerce.warehouse.model.InboundOrder;
+import common.ecommerce.warehouse.model.InboundOrderBatch;
import common.ecommerce.warehouse.model.InboundOrderLine;
import common.ecommerce.yqn.enums.YqnInboundStatus;
@@ -204,19 +205,21 @@ public final class YqnInboundMapper {
if (batchInfo == null) {
return out;
}
- addBatches(out, batchInfo.planBatchItems);
- addBatches(out, batchInfo.inboundBatchItems);
+ addBatches(out, batchInfo.planBatchItems, InboundOrderBatch.Phase.PLANNED);
+ addBatches(out, batchInfo.inboundBatchItems, InboundOrderBatch.Phase.INBOUNDED);
return out;
}
private static void addBatches(List out,
- List items) {
+ List items,
+ common.ecommerce.warehouse.model.InboundOrderBatch.Phase phase) {
if (items == null) {
return;
}
for (YqnInboundPlanDtos.InboundPlanInfo.BatchItem item : items) {
common.ecommerce.warehouse.model.InboundOrderBatch.Builder b =
common.ecommerce.warehouse.model.InboundOrderBatch.builder()
+ .phase(phase)
.providerSku(item.sku)
.quantity(intOf(item.qty))
.cartonNo(item.cartonNo)
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java
index 7fc74ed..41378d0 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java
@@ -68,13 +68,20 @@ public final class YqnOrderCallbackParser {
WarehouseCallback.ReturnPayload.Builder payload = WarehouseCallback.ReturnPayload.builder();
if (body.items != null) {
for (YqnReturnInboundCallbackDtos.ReturnInboundPushed.ReturnItem item : body.items) {
- payload.line(WarehouseCallback.ReturnLinePayload.builder()
- .providerSku(item.sku)
- .quantity(item.shelfQuantity)
- // 回调不带明细行 id;API 77 的操作键只能从别处拿
- .lineId(null)
- .disposition(processModeLabel(body.processMode))
- .build());
+ WarehouseCallback.ReturnLinePayload.Builder line =
+ WarehouseCallback.ReturnLinePayload.builder()
+ .providerSku(item.sku)
+ .quantity(item.shelfQuantity)
+ // 回调不带明细行 id;API 77 的操作键只能从别处拿
+ .lineId(null)
+ .disposition(processModeLabel(body.processMode))
+ .batchNo(item.batchParamNo);
+ if (item.batchParam != null) {
+ for (YqnReturnInboundCallbackDtos.ReturnInboundPushed.BatchParam p : item.batchParam) {
+ line.batchParam(p.batchAttriKey, p.batchAttriValue);
+ }
+ }
+ payload.line(line.build());
}
}
WarehouseCallback callback = WarehouseCallback.builder()
diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java
index 684da4f..590e68c 100644
--- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java
@@ -123,6 +123,9 @@ class YqnInboundPlanTest {
assertEquals("ProductionDateNumber", batches.get(0).params().get(0).key());
assertEquals("LotCode", batches.get(1).params().get(0).key());
assertEquals(58, batches.get(1).quantity());
+ // 阶段必须区分:计划 60 / 上架 58,混在一起就做不了短少核对
+ assertEquals(InboundOrderBatch.Phase.PLANNED, batches.get(0).phase());
+ assertEquals(InboundOrderBatch.Phase.INBOUNDED, batches.get(1).phase());
}
@Test
diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java
index 5e1d7c6..b48deb7 100644
--- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java
@@ -136,6 +136,23 @@ class YqnCallbackParsersTest {
assertEquals(Instant.parse("2026-11-10T06:00:00Z"), cb.occurredAt());
}
+ /** 退货明细的批次号与批次属性要带出去,否则无法回填库存批次。 */
+ @Test
+ void returnLineCarriesBatch() {
+ String body = "{\"orderNo\":\"RT1\",\"orderNoType\":3,\"orderNoStatus\":5,"
+ + "\"changeTime\":\"2026-11-10 05:00:00\",\"processMode\":5,"
+ + "\"items\":[{\"sku\":\"S1\",\"shelfQuantity\":2,\"batchParamNo\":\"PC001\","
+ + "\"batchParam\":[{\"batchAttriKey\":\"LotCode\",\"batchAttriValue\":\"L1\"}]}]}";
+
+ WarehouseCallback.ReturnLinePayload line =
+ YqnOrderCallbackParser.parseReturnInbound(body).get(0).returns().lines().get(0);
+
+ assertEquals("PC001", line.batchNo());
+ assertEquals(1, line.batchParams().size());
+ assertEquals("LotCode", line.batchParams().get(0).key());
+ assertEquals("L1", line.batchParams().get(0).value());
+ }
+
@Test
void inventoryDirectionUnknownIsNull() {
// 缺 opLabel 或出现新码值:不能默认出库