Browse Source

fix(yqn): 入库批次区分计划/上架;退货回调补批次字段

入库查询(getInboundPlanInfo):
仓方分两段给批次——planBatchItems 是预报装箱、inboundBatchItems 是实际
上架。原来合并进同一个列表且不标来源,同一 SKU/箱会出现两条数量不同的
记录(计划 60 / 实收 58),宿主无法判断哪条是计划、短少核对失真。
InboundOrderBatch 增加 Phase 枚举(PLANNED / INBOUNDED)。

退货入库回调(API 142):
items[].batchParamNo(批次号)与 batchParam(批次属性)之前完全丢弃,
退回货品的批次/效期无法回填库存。ReturnLinePayload 增加 batchNo 与
batchParams。换标上架场景仓方不传 batchParam,为空列表属正常。

测试:入库批次阶段断言、退货回调批次字段断言。
全量 412 个测试通过。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
1805bbdf94
  1. 27
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java
  2. 51
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java
  3. 9
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  4. 21
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java
  5. 3
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java
  6. 17
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java

27
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java

@ -12,6 +12,21 @@ import java.util.List;
*/ */
public final class InboundOrderBatch { public final class InboundOrderBatch {
/**
* 批次阶段:计划批次 / 上架批次。
*
* <p>仓方分两段给:{@code planBatchItems} 是预报装箱的批次,
* {@code inboundBatchItems} 是实际收货上架的批次。两者数量可能不同
* (计划 60 / 实收 58),不区分就无法做短少核对。</p>
*/
public enum Phase {
/** 计划批次(预报)。 */
PLANNED,
/** 上架批次(实收)。 */
INBOUNDED
}
private final Phase phase;
private final String providerSku; private final String providerSku;
private final int quantity; private final int quantity;
/** 箱唛号。 */ /** 箱唛号。 */
@ -21,6 +36,7 @@ public final class InboundOrderBatch {
private final List<Param> params; private final List<Param> params;
private InboundOrderBatch(Builder b) { private InboundOrderBatch(Builder b) {
this.phase = b.phase;
this.providerSku = b.providerSku; this.providerSku = b.providerSku;
this.quantity = b.quantity; this.quantity = b.quantity;
this.cartonNo = b.cartonNo; this.cartonNo = b.cartonNo;
@ -32,6 +48,11 @@ public final class InboundOrderBatch {
return new Builder(); return new Builder();
} }
/** 批次阶段;仓方未标明时为 null。 */
public Phase phase() {
return phase;
}
public String providerSku() { public String providerSku() {
return providerSku; return providerSku;
} }
@ -74,12 +95,18 @@ public final class InboundOrderBatch {
} }
public static final class Builder { public static final class Builder {
private Phase phase;
private String providerSku; private String providerSku;
private int quantity; private int quantity;
private String cartonNo; private String cartonNo;
private Integer inventoryType; private Integer inventoryType;
private final List<Param> params = new ArrayList<Param>(); private final List<Param> params = new ArrayList<Param>();
public Builder phase(Phase v) {
this.phase = v;
return this;
}
public Builder providerSku(String v) { public Builder providerSku(String v) {
this.providerSku = v; this.providerSku = v;
return this; return this;

51
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 { public static final class ReturnLinePayload {
private final Long lineId; private final Long lineId;
/** 仓方 SKU;换标上架场景下是<b>换标后</b>的 SKU。 */
private final String providerSku; private final String providerSku;
private final Integer quantity; private final Integer quantity;
/** 仓方处理方式原值;语义解释由适配器对应的平台枚举负责。 */ /** 仓方处理方式原值;语义解释由适配器对应的平台枚举负责。 */
private final String disposition; private final String disposition;
/** 批次号(如运去哪的 PC 开头批次号)。 */
private final String batchNo;
/** 批次属性键值;换标上架场景下仓方不传。 */
private final java.util.List<BatchParam> batchParams;
private ReturnLinePayload(Builder b) { private ReturnLinePayload(Builder b) {
this.lineId = b.lineId; this.lineId = b.lineId;
this.providerSku = b.providerSku; this.providerSku = b.providerSku;
this.quantity = b.quantity; this.quantity = b.quantity;
this.disposition = b.disposition; this.disposition = b.disposition;
this.batchNo = b.batchNo;
this.batchParams = java.util.Collections.unmodifiableList(
new java.util.ArrayList<BatchParam>(b.batchParams));
} }
public static Builder builder() { public static Builder builder() {
@ -291,11 +299,44 @@ public final class WarehouseCallback {
return disposition; return disposition;
} }
/** 批次号;仓方未给时为 null。 */
public String batchNo() {
return batchNo;
}
/** 批次属性;换标上架时为空列表。 */
public java.util.List<BatchParam> 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 { public static final class Builder {
private Long lineId; private Long lineId;
private String providerSku; private String providerSku;
private Integer quantity; private Integer quantity;
private String disposition; private String disposition;
private String batchNo;
private final java.util.List<BatchParam> batchParams =
new java.util.ArrayList<BatchParam>();
public Builder lineId(Long v) { public Builder lineId(Long v) {
this.lineId = v; this.lineId = v;
@ -317,6 +358,16 @@ public final class WarehouseCallback {
return this; 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() { public ReturnLinePayload build() {
return new ReturnLinePayload(this); return new ReturnLinePayload(this);
} }

9
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.InboundCommand;
import common.ecommerce.warehouse.model.InboundLine; import common.ecommerce.warehouse.model.InboundLine;
import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundOrderBatch;
import common.ecommerce.warehouse.model.InboundOrderLine; import common.ecommerce.warehouse.model.InboundOrderLine;
import common.ecommerce.yqn.enums.YqnInboundStatus; import common.ecommerce.yqn.enums.YqnInboundStatus;
@ -204,19 +205,21 @@ public final class YqnInboundMapper {
if (batchInfo == null) { if (batchInfo == null) {
return out; return out;
} }
addBatches(out, batchInfo.planBatchItems); addBatches(out, batchInfo.planBatchItems, InboundOrderBatch.Phase.PLANNED);
addBatches(out, batchInfo.inboundBatchItems); addBatches(out, batchInfo.inboundBatchItems, InboundOrderBatch.Phase.INBOUNDED);
return out; return out;
} }
private static void addBatches(List<common.ecommerce.warehouse.model.InboundOrderBatch> out, private static void addBatches(List<common.ecommerce.warehouse.model.InboundOrderBatch> out,
List<YqnInboundPlanDtos.InboundPlanInfo.BatchItem> items) { List<YqnInboundPlanDtos.InboundPlanInfo.BatchItem> items,
common.ecommerce.warehouse.model.InboundOrderBatch.Phase phase) {
if (items == null) { if (items == null) {
return; return;
} }
for (YqnInboundPlanDtos.InboundPlanInfo.BatchItem item : items) { for (YqnInboundPlanDtos.InboundPlanInfo.BatchItem item : items) {
common.ecommerce.warehouse.model.InboundOrderBatch.Builder b = common.ecommerce.warehouse.model.InboundOrderBatch.Builder b =
common.ecommerce.warehouse.model.InboundOrderBatch.builder() common.ecommerce.warehouse.model.InboundOrderBatch.builder()
.phase(phase)
.providerSku(item.sku) .providerSku(item.sku)
.quantity(intOf(item.qty)) .quantity(intOf(item.qty))
.cartonNo(item.cartonNo) .cartonNo(item.cartonNo)

21
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(); WarehouseCallback.ReturnPayload.Builder payload = WarehouseCallback.ReturnPayload.builder();
if (body.items != null) { if (body.items != null) {
for (YqnReturnInboundCallbackDtos.ReturnInboundPushed.ReturnItem item : body.items) { for (YqnReturnInboundCallbackDtos.ReturnInboundPushed.ReturnItem item : body.items) {
payload.line(WarehouseCallback.ReturnLinePayload.builder() WarehouseCallback.ReturnLinePayload.Builder line =
.providerSku(item.sku) WarehouseCallback.ReturnLinePayload.builder()
.quantity(item.shelfQuantity) .providerSku(item.sku)
// 回调不带明细行 id;API 77 的操作键只能从别处拿 .quantity(item.shelfQuantity)
.lineId(null) // 回调不带明细行 id;API 77 的操作键只能从别处拿
.disposition(processModeLabel(body.processMode)) .lineId(null)
.build()); .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() WarehouseCallback callback = WarehouseCallback.builder()

3
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("ProductionDateNumber", batches.get(0).params().get(0).key());
assertEquals("LotCode", batches.get(1).params().get(0).key()); assertEquals("LotCode", batches.get(1).params().get(0).key());
assertEquals(58, batches.get(1).quantity()); 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 @Test

17
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()); 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 @Test
void inventoryDirectionUnknownIsNull() { void inventoryDirectionUnknownIsNull() {
// 缺 opLabel 或出现新码值:不能默认出库 // 缺 opLabel 或出现新码值:不能默认出库

Loading…
Cancel
Save