Browse Source

feat(yqn): 补全 API 101 入库计划响应 + 补测试

按你提供的完整文档核对出入参,补齐之前缺的部分:

API 101 响应侧(之前只映射了 22/40 个字段):
- 头级三层数量 planQty / packedQty / receivedQty → InboundOrder 新增
  plannedQuantity / packedQuantity / receivedQuantity。之前只有行级,
  头-行交叉校验(短少 / 溢装定位)做不了
- batchInfo(计划批次 + 上架批次)→ 新增 InboundOrderBatch,含箱唛号与
  库存类型。注意与下发的 InboundBatch 不是一回事:那个是请求侧、
  这个是回查侧
- boxInfo(每箱装了哪些 SKU、计划量与上架量)→ 新增 InboundOrderBox
- packingLabelUrl → 原样带出,Javadoc 注明仓方称将改为异步箱标任务

createdAt 确认运去哪不提供(文档无该字段),维持 null 并已标注。

测试补充:
- YqnInboundPlanTest(9 个):完整响应逐字段断言、可选段缺失、未知状态
 归 UNKNOWN、按单号查、空单号拒绝
- WarehouseWebhookSdkTest(9 个)+ FakeWebhookAdapter:门面 sdk.webhook
  按 provider 分派、不依赖仓账户、验签失败不进 parse、未注册 provider、
  无 WEBHOOK 能力、解析结果透传

顺带修:sdk.webhook 传 null secret 时 WarehouseConnection 构造抛 NPE,
改为给空凭据,是否可用由适配器验签决定。

全量 395 个测试通过。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
1f5e6334c6
  1. 2
      README.md
  2. 84
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  3. 112
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java
  4. 110
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBox.java
  5. 9
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java
  6. 103
      warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWebhookAdapter.java
  7. 169
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseWebhookSdkTest.java
  8. 75
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  9. 57
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java
  10. 212
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java

2
README.md

@ -306,7 +306,7 @@ common.ecommerce @@ -306,7 +306,7 @@ common.ecommerce
│ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult /
│ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine /
│ │ InboundCommand / InboundLine / InboundCarton / InboundBatch /
│ │ InboundReceipt / ReturnCommand / ReturnProcessCommand /
│ │ InboundReceipt / InboundOrderBatch / InboundOrderBox / ReturnCommand / ReturnProcessCommand /
│ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/
│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult /
│ │ TrackEvent / TrackingInfo / WarehouseCallback / DestructionCommand / DestructionOrder /

84
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java

@ -30,6 +30,18 @@ public final class InboundOrder { @@ -30,6 +30,18 @@ public final class InboundOrder {
/** 库存类型:0 可售 / 1 不可售。 */
private final int inventoryType;
private final int boxCount;
/** 头级计划数量;等于各行计划数量之和,仓方直接给时不重算。 */
private final int plannedQuantity;
/** 头级已装箱数量。 */
private final int packedQuantity;
/** 头级实收数量。 */
private final int receivedQuantity;
/** 计划 / 上架批次明细。 */
private final List<InboundOrderBatch> batches;
/** 箱明细:每箱装了哪些 SKU。 */
private final List<InboundOrderBox> boxes;
/** 纸箱 Label 文件地址;仓方文档称将改为异步任务,可能为 null。 */
private final String packingLabelUrl;
/**
* 创建时间(UTC)。
*
@ -63,6 +75,12 @@ public final class InboundOrder { @@ -63,6 +75,12 @@ public final class InboundOrder {
this.sourceProvider = b.sourceProvider;
this.inventoryType = b.inventoryType;
this.boxCount = b.boxCount;
this.plannedQuantity = b.plannedQuantity;
this.packedQuantity = b.packedQuantity;
this.receivedQuantity = b.receivedQuantity;
this.batches = Collections.unmodifiableList(new ArrayList<InboundOrderBatch>(b.batches));
this.boxes = Collections.unmodifiableList(new ArrayList<InboundOrderBox>(b.boxes));
this.packingLabelUrl = b.packingLabelUrl;
this.createdAt = b.createdAt;
this.receivedAt = b.receivedAt;
this.estimatedArrivalAt = b.estimatedArrivalAt;
@ -110,6 +128,36 @@ public final class InboundOrder { @@ -110,6 +128,36 @@ public final class InboundOrder {
return boxCount;
}
/** 头级计划数量。 */
public int plannedQuantity() {
return plannedQuantity;
}
/** 头级已装箱数量。 */
public int packedQuantity() {
return packedQuantity;
}
/** 头级实收数量。 */
public int receivedQuantity() {
return receivedQuantity;
}
/** 计划 / 上架批次明细;不可变。 */
public List<InboundOrderBatch> batches() {
return batches;
}
/** 箱明细;不可变。 */
public List<InboundOrderBox> boxes() {
return boxes;
}
/** 纸箱 Label 地址;仓方可能不再返回。 */
public String packingLabelUrl() {
return packingLabelUrl;
}
public Instant createdAt() {
return createdAt;
}
@ -187,6 +235,12 @@ public final class InboundOrder { @@ -187,6 +235,12 @@ public final class InboundOrder {
private WarehouseProvider sourceProvider;
private int inventoryType;
private int boxCount;
private int plannedQuantity;
private int packedQuantity;
private int receivedQuantity;
private final List<InboundOrderBatch> batches = new ArrayList<InboundOrderBatch>();
private final List<InboundOrderBox> boxes = new ArrayList<InboundOrderBox>();
private String packingLabelUrl;
private Instant createdAt;
private Instant receivedAt;
private Instant estimatedArrivalAt;
@ -240,6 +294,36 @@ public final class InboundOrder { @@ -240,6 +294,36 @@ public final class InboundOrder {
return this;
}
public Builder plannedQuantity(int v) {
this.plannedQuantity = v;
return this;
}
public Builder packedQuantity(int v) {
this.packedQuantity = v;
return this;
}
public Builder receivedQuantity(int v) {
this.receivedQuantity = v;
return this;
}
public Builder batch(InboundOrderBatch v) {
this.batches.add(v);
return this;
}
public Builder box(InboundOrderBox v) {
this.boxes.add(v);
return this;
}
public Builder packingLabelUrl(String v) {
this.packingLabelUrl = v;
return this;
}
public Builder createdAt(Instant v) {
this.createdAt = v;
return this;

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

@ -0,0 +1,112 @@ @@ -0,0 +1,112 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 入库单的批次明细(计划或上架)。
*
* <p>与 {@link InboundBatch}(<b>下发</b>时的批次)不是一回事:这个是仓方
* <b>回查</b>时给的批次分布,多了箱唛号与库存类型。</p>
*/
public final class InboundOrderBatch {
private final String providerSku;
private final int quantity;
/** 箱唛号。 */
private final String cartonNo;
/** 库存类型:0 可售 / 1 不可售;仓方标为「历史未知」时为 null。 */
private final Integer inventoryType;
private final List<Param> params;
private InboundOrderBatch(Builder b) {
this.providerSku = b.providerSku;
this.quantity = b.quantity;
this.cartonNo = b.cartonNo;
this.inventoryType = b.inventoryType;
this.params = Collections.unmodifiableList(new ArrayList<Param>(b.params));
}
public static Builder builder() {
return new Builder();
}
public String providerSku() {
return providerSku;
}
public int quantity() {
return quantity;
}
public String cartonNo() {
return cartonNo;
}
/** 库存类型:0 可售 / 1 不可售 / null 历史未知。 */
public Integer inventoryType() {
return inventoryType;
}
public List<Param> params() {
return params;
}
/** 批次属性键值。 */
public static final class Param {
private final String key;
private final String value;
public Param(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 String providerSku;
private int quantity;
private String cartonNo;
private Integer inventoryType;
private final List<Param> params = new ArrayList<Param>();
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder quantity(int v) {
this.quantity = v;
return this;
}
public Builder cartonNo(String v) {
this.cartonNo = v;
return this;
}
public Builder inventoryType(Integer v) {
this.inventoryType = v;
return this;
}
public Builder param(String key, String value) {
this.params.add(new Param(key, value));
return this;
}
public InboundOrderBatch build() {
return new InboundOrderBatch(this);
}
}
}

110
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBox.java

@ -0,0 +1,110 @@ @@ -0,0 +1,110 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 入库单的箱明细:一箱装了哪些 SKU 的计划量与上架量。
*
* <p>用于核对「这箱货到底收了多少」——头级汇总只能看总数,
* 短少 / 溢装要落到箱和 SKU 才定位得到。</p>
*/
public final class InboundOrderBox {
/** 箱唛号。 */
private final String cartonNo;
private final List<BoxLine> lines;
private InboundOrderBox(Builder b) {
this.cartonNo = b.cartonNo;
this.lines = Collections.unmodifiableList(new ArrayList<BoxLine>(b.lines));
}
public static Builder builder() {
return new Builder();
}
public String cartonNo() {
return cartonNo;
}
public List<BoxLine> lines() {
return lines;
}
/** 箱内一条 SKU。 */
public static final class BoxLine {
private final String providerSku;
private final int plannedQuantity;
private final int inboundQuantity;
private BoxLine(Builder b) {
this.providerSku = b.providerSku;
this.plannedQuantity = b.plannedQuantity;
this.inboundQuantity = b.inboundQuantity;
}
public static Builder builder() {
return new Builder();
}
public String providerSku() {
return providerSku;
}
public int plannedQuantity() {
return plannedQuantity;
}
/** 上架数量。 */
public int inboundQuantity() {
return inboundQuantity;
}
public static final class Builder {
private String providerSku;
private int plannedQuantity;
private int inboundQuantity;
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder plannedQuantity(int v) {
this.plannedQuantity = v;
return this;
}
public Builder inboundQuantity(int v) {
this.inboundQuantity = v;
return this;
}
public BoxLine build() {
return new BoxLine(this);
}
}
}
public static final class Builder {
private String cartonNo;
private final List<BoxLine> lines = new ArrayList<BoxLine>();
public Builder cartonNo(String v) {
this.cartonNo = v;
return this;
}
public Builder line(BoxLine v) {
this.lines.add(v);
return this;
}
public InboundOrderBox build() {
return new InboundOrderBox(this);
}
}
}

9
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java

@ -156,10 +156,13 @@ public final class WarehouseSdk { @@ -156,10 +156,13 @@ public final class WarehouseSdk {
if (id == null || id.trim().isEmpty()) {
throw new IllegalStateException("requestIdSupplier returned blank id");
}
// 端点与凭据来自调用方;回调侧没有真实端点,用占位符避免 NPE
// 回调侧没有真实端点,用占位符;WarehouseConnection 要求 secret 非空,
// 所以缺 secret 时给一个空凭据——是否真的能用由适配器验签时决定
ChannelSecret effective = secret != null ? secret
: ChannelSecret.builder().build();
WarehouseConnection connection = WarehouseConnection.of(
secret != null && secret.endpointBaseUrl() != null && !secret.endpointBaseUrl().isEmpty()
? secret.endpointBaseUrl() : "https://callback.local", secret);
effective.endpointBaseUrl() != null && !effective.endpointBaseUrl().isEmpty()
? effective.endpointBaseUrl() : "https://callback.local", effective);
return WarehouseContext.of(
// 回调可能多仓共用入口,warehouseCode 未知;用 provider 名占位,业务字段以报文为准
"CALLBACK-" + provider.name(), provider, null, connection, id, clock);

103
warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWebhookAdapter.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.warehouse.testkit;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.capability.WarehouseWebhookCapable;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseWebhookVerificationException;
import common.ecommerce.warehouse.model.WarehouseCallback;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.warehouse.sdk.WebhookSignatures;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
import java.util.Map;
/**
* 假回调适配器:只实现回调能力,用于验证门面 {@code sdk.webhook(...)} 的分派、
* 验签失败传播与解析结果透传。
*
* <p>不做真实签名:只要请求头里带 {@code X-Signature} 且等于构造时给的值就算通过,
* 便于测试「验签失败 → 异常」这条路径而不必实现某家仓的算法。</p>
*/
public final class FakeWebhookAdapter implements WarehouseWebhookCapable {
/** 通过验签所需的签名值。 */
private final String expectedSignature;
/** 解析出的回调;默认一条面单事件。 */
private List<WarehouseCallback> parsed;
private int verifyCalls;
private int parseCalls;
/** 置 true 时 verify 抛异常,模拟验签失败。 */
private boolean failVerify;
public FakeWebhookAdapter(String expectedSignature) {
this.expectedSignature = expectedSignature;
this.parsed = new ArrayList<WarehouseCallback>();
this.parsed.add(WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.CUSTOM)
.eventType(WarehouseEventType.LABEL_PURCHASED)
.rawEventType("FAKE")
.providerOrderNo("WH-1")
.build());
}
public FakeWebhookAdapter parsed(List<WarehouseCallback> callbacks) {
this.parsed = callbacks;
return this;
}
public FakeWebhookAdapter failVerify() {
this.failVerify = true;
return this;
}
public int verifyCalls() {
return verifyCalls;
}
public int parseCalls() {
return parseCalls;
}
@Override
public String adapterId() {
return "fake-webhook";
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.CUSTOM;
}
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.WEBHOOK);
}
@Override
public void verify(ChannelSecret secret, Map<String, String> headers, String rawBody,
long nowMillis) {
verifyCalls++;
if (failVerify) {
throw WebhookSignatures.verificationFailure(WarehouseProvider.CUSTOM, "forced failure");
}
String actual = WebhookSignatures.header(headers, "X-Signature");
if (!WebhookSignatures.constantTimeEquals(expectedSignature, actual)) {
throw new WarehouseWebhookVerificationException(
common.ecommerce.warehouse.error.WarehouseException.builder()
.message("fake signature mismatch")
.operation("warehouse.webhook.verify")
.retryable(false));
}
}
@Override
public List<WarehouseCallback> parse(WarehouseContext ctx, ChannelSecret secret,
Map<String, String> headers, String rawBody) {
parseCalls++;
return parsed;
}
}

169
warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseWebhookSdkTest.java

@ -0,0 +1,169 @@ @@ -0,0 +1,169 @@
package common.ecommerce.warehouse.sdk;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.error.WarehouseWebhookVerificationException;
import common.ecommerce.warehouse.model.WarehouseCallback;
import common.ecommerce.warehouse.testkit.FakeWarehouseAdapter;
import common.ecommerce.warehouse.testkit.FakeWebhookAdapter;
import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 门面 {@code sdk.webhook(...)}:按 provider 分派、验签失败传播、解析结果透传。
*
* <p>回调进来时只有 provider,没有 warehouseCode——这个入口不能依赖仓账户,
* 所以用不配置任何账户的 SDK 也能跑通。</p>
*/
class WarehouseWebhookSdkTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC);
private static final long NOW = Instant.parse("2026-11-10T00:00:00Z").toEpochMilli();
private static final String SIGNATURE = "sig-xyz";
private static final String BODY = "{\"any\":\"body\"}";
private FakeWebhookAdapter adapter;
private WarehouseSdk sdk;
@BeforeEach
void setUp() {
adapter = new FakeWebhookAdapter(SIGNATURE);
// 不配置账户:验证回调入口不依赖 warehouseRepository
sdk = WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses())
.clock(CLOCK)
.register(adapter)
.build();
}
private static Map<String, String> headers(String signature) {
Map<String, String> h = new LinkedHashMap<String, String>();
h.put("X-Signature", signature);
return h;
}
private static ChannelSecret secret() {
return ChannelSecret.builder().appKey("ak").appSecret("sk").build();
}
@Test
void dispatchesByProviderWithoutWarehouseAccount() {
List<WarehouseCallback> callbacks = sdk.webhook(WarehouseProvider.CUSTOM, secret(),
headers(SIGNATURE), BODY, NOW);
assertEquals(1, callbacks.size());
assertEquals(WarehouseProvider.CUSTOM, callbacks.get(0).sourceProvider());
assertEquals(WarehouseEventType.LABEL_PURCHASED, callbacks.get(0).eventType());
assertEquals(1, adapter.verifyCalls());
assertEquals(1, adapter.parseCalls());
}
/** 验签失败必须直接抛出,不能继续解析。 */
@Test
void verificationFailureStopsBeforeParse() {
assertThrows(WarehouseWebhookVerificationException.class,
() -> sdk.webhook(WarehouseProvider.CUSTOM, secret(),
headers("wrong"), BODY, NOW));
assertEquals(1, adapter.verifyCalls());
assertEquals(0, adapter.parseCalls(), "验签失败不应调用 parse");
}
@Test
void verificationExceptionFromAdapterIsPropagated() {
adapter.failVerify();
assertThrows(WarehouseWebhookVerificationException.class,
() -> sdk.webhook(WarehouseProvider.CUSTOM, secret(),
headers(SIGNATURE), BODY, NOW));
assertEquals(0, adapter.parseCalls());
}
/** 未注册的 provider 要报清楚,而不是 NPE。 */
@Test
void unregisteredProviderFails() {
IllegalStateException ex = assertThrows(IllegalStateException.class,
() -> sdk.webhook(WarehouseProvider.YQN, secret(), headers(SIGNATURE), BODY, NOW));
assertTrue(ex.getMessage().contains("no warehouse adapter registered"), ex.getMessage());
}
/** 适配器不支持 WEBHOOK 时抛能力异常,而不是静默返回空。 */
@Test
void adapterWithoutWebhookCapabilityIsRejected() {
WarehouseSdk withoutWebhook = WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses())
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
.build();
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> withoutWebhook.webhook(WarehouseProvider.CUSTOM, secret(),
headers(SIGNATURE), BODY, NOW));
}
/** 解析结果原样透传,不做二次加工。 */
@Test
void passesParsedCallbacksThrough() {
WarehouseCallback custom = WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.CUSTOM)
.eventType(WarehouseEventType.INVENTORY_CHANGED)
.providerOrderNo("O-9")
.build();
adapter.parsed(java.util.Collections.singletonList(custom));
List<WarehouseCallback> out = sdk.webhook(WarehouseProvider.CUSTOM, secret(),
headers(SIGNATURE), BODY, NOW);
assertEquals(1, out.size());
assertEquals(WarehouseEventType.INVENTORY_CHANGED, out.get(0).eventType());
assertEquals("O-9", out.get(0).providerOrderNo());
}
/** 上下文只为回调构造,不应带出仓编码。 */
@Test
void contextHasNoWarehouseCodeLeak() {
WarehouseCallback captured = WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.CUSTOM)
.eventType(WarehouseEventType.ORDER_STATUS_CHANGED)
.providerWarehouseCode("WH-FROM-BODY")
.build();
adapter.parsed(java.util.Collections.singletonList(captured));
List<WarehouseCallback> out = sdk.webhook(WarehouseProvider.CUSTOM, secret(),
headers(SIGNATURE), BODY, NOW);
// 仓编码只能来自报文
assertEquals("WH-FROM-BODY", out.get(0).providerWarehouseCode());
}
/** 能力矩阵里能看到 WEBHOOK。 */
@Test
void capabilityIsVisible() {
assertTrue(adapter.capabilities().contains(WarehouseCapability.WEBHOOK));
}
/** secret 缺失时由适配器决定如何报错;门面不拦截。 */
@Test
void nullSecretIsHandedToAdapter() {
List<WarehouseCallback> out = sdk.webhook(WarehouseProvider.CUSTOM, null,
headers(SIGNATURE), BODY, NOW);
assertEquals(1, out.size());
}
}

75
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java

@ -160,7 +160,7 @@ public final class YqnInboundMapper { @@ -160,7 +160,7 @@ public final class YqnInboundMapper {
/** 入库计划详情 → 统一入库单(API 101)。 */
public static InboundOrder toOrder(YqnInboundPlanDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) {
return InboundOrder.builder()
InboundOrder.Builder builder = InboundOrder.builder()
.inboundRequestNo(firstNonBlank(info.sourceNo, info.inboundPlanOrderNo))
.providerInboundId(info.inboundPlanOrderNo)
.warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode))
@ -180,8 +180,77 @@ public final class YqnInboundMapper { @@ -180,8 +180,77 @@ public final class YqnInboundMapper {
.totalVolumeCbm(info.totalVolume)
.remark(info.remark)
.lines(toOrderLines(info.planProductDetailParamList, zone))
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build();
.plannedQuantity(intOf(info.planQty))
.packedQuantity(intOf(info.packedQty))
.receivedQuantity(intOf(info.receivedQty))
.packingLabelUrl(info.packingLabelUrl)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN);
for (common.ecommerce.warehouse.model.InboundOrderBatch batch : toOrderBatches(info.batchInfo)) {
builder.batch(batch);
}
for (common.ecommerce.warehouse.model.InboundOrderBox box : toOrderBoxes(info.boxInfo)) {
builder.box(box);
}
return builder.build();
}
/** 计划批次 + 上架批次合并成一个列表;两者用途不同,但结构相同。 */
private static List<common.ecommerce.warehouse.model.InboundOrderBatch> toOrderBatches(
YqnInboundPlanDtos.InboundPlanInfo.BatchInfo batchInfo) {
List<common.ecommerce.warehouse.model.InboundOrderBatch> out =
new ArrayList<common.ecommerce.warehouse.model.InboundOrderBatch>();
if (batchInfo == null) {
return out;
}
addBatches(out, batchInfo.planBatchItems);
addBatches(out, batchInfo.inboundBatchItems);
return out;
}
private static void addBatches(List<common.ecommerce.warehouse.model.InboundOrderBatch> out,
List<YqnInboundPlanDtos.InboundPlanInfo.BatchItem> items) {
if (items == null) {
return;
}
for (YqnInboundPlanDtos.InboundPlanInfo.BatchItem item : items) {
common.ecommerce.warehouse.model.InboundOrderBatch.Builder b =
common.ecommerce.warehouse.model.InboundOrderBatch.builder()
.providerSku(item.sku)
.quantity(intOf(item.qty))
.cartonNo(item.cartonNo)
.inventoryType(item.inventoryType);
if (item.batchParam != null) {
for (YqnInboundPlanDtos.InboundPlanInfo.BatchAttr attr : item.batchParam) {
b.param(attr.batchAttriKey, attr.batchAttriValue);
}
}
out.add(b.build());
}
}
private static List<common.ecommerce.warehouse.model.InboundOrderBox> toOrderBoxes(
List<YqnInboundPlanDtos.InboundPlanInfo.BoxInfo> boxes) {
List<common.ecommerce.warehouse.model.InboundOrderBox> out =
new ArrayList<common.ecommerce.warehouse.model.InboundOrderBox>();
if (boxes == null) {
return out;
}
for (YqnInboundPlanDtos.InboundPlanInfo.BoxInfo box : boxes) {
common.ecommerce.warehouse.model.InboundOrderBox.Builder b =
common.ecommerce.warehouse.model.InboundOrderBox.builder().cartonNo(box.cartonNo);
if (box.productInfo != null) {
for (YqnInboundPlanDtos.InboundPlanInfo.BoxProduct product : box.productInfo) {
b.line(common.ecommerce.warehouse.model.InboundOrderBox.BoxLine.builder()
.providerSku(product.sku)
.plannedQuantity(intOf(product.planQty))
.inboundQuantity(intOf(product.inboundQty))
.build());
}
}
out.add(b.build());
}
return out;
}
private static List<InboundOrderLine> toOrderLines(

57
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java

@ -69,6 +69,63 @@ public final class YqnInboundPlanDtos { @@ -69,6 +69,63 @@ public final class YqnInboundPlanDtos {
public String remark;
/** 产品详情(计划 / 装箱 / 实收)。 */
public List<PlanProductDetail> planProductDetailParamList;
/** 批次明细:计划批次与上架批次。 */
public BatchInfo batchInfo;
/** 箱明细:每箱装了哪些 SKU、各多少。 */
public List<BoxInfo> boxInfo;
/**
* 纸箱 Label 文件地址。
*
* <p>文档已标注「现在应该通过打印箱标接口异步生成箱标,通过任务编号查询任务中心
* 接口获取箱标地址」——这个字段可能逐渐废弃,取不到属正常。</p>
*/
public String packingLabelUrl;
/** 批次明细。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BatchInfo {
/** 计划批次。 */
public List<BatchItem> planBatchItems;
/** 上架批次。 */
public List<BatchItem> inboundBatchItems;
}
/** 一条批次明细。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BatchItem {
public String sku;
public Integer qty;
/** 箱唛号。 */
public String cartonNo;
public List<BatchAttr> batchParam;
/** 库存类型:0 可售 / 1 不可售 / null 历史未知。 */
public Integer inventoryType;
}
/** 批次属性键值。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BatchAttr {
public String batchAttriKey;
public String batchAttriValue;
}
/** 箱明细。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BoxInfo {
/** 箱唛号。 */
public String cartonNo;
/** 上架产品明细行。 */
public List<BoxProduct> productInfo;
}
/** 箱内一条产品。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BoxProduct {
public String sku;
public Integer planQty;
/** 上架数量。 */
public Integer inboundQty;
}
/** 产品行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)

212
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java

@ -0,0 +1,212 @@ @@ -0,0 +1,212 @@
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.InboundStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundOrderBatch;
import common.ecommerce.warehouse.model.InboundOrderBox;
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.assertTrue;
/**
* 查询入库计划(API 101)契约测试,覆盖完整响应结构。
*/
class YqnInboundPlanTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00: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-inbound-plan", CLOCK);
}
/** 按文档 API 101 的完整响应构造。 */
private static final String FULL_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":\"200\",\"message\":\"ok\",\"data\":{"
+ "\"orgWarehouseCode\":\"RF_NY_US\",\"lineName\":\"默认项目\","
+ "\"inventoryType\":\"0\",\"inboundPlanOrderNo\":\"IP20261110001\","
+ "\"inboundPlanOrderStatus\":\"25\",\"sourceNo\":\"OMS-IN-001\","
+ "\"shipmentId\":\"FBA15ABC\",\"referenceId\":\"REF1\",\"shipmentNo\":\"1Z999\","
+ "\"estimateArriveTime\":\"2026-11-20\",\"actualArriveTime\":\"2026-11-21\","
+ "\"firstReceptionDate\":\"2026-11-21 09:00:00\","
+ "\"shipperName\":\"张三\",\"shipperAddress\":\"1 Main St\","
+ "\"shipperContact\":\"张三\",\"shipperPhone\":\"+1-555-0100\","
+ "\"goodsType\":\"普货\",\"cartonQty\":\"8\","
+ "\"planQty\":100,\"packedQty\":98,\"receivedQty\":95,"
+ "\"totalWeight\":120.5,\"totalVolume\":1.8,"
+ "\"actualShipDate\":\"2026-11-12 10:00:00\","
+ "\"cartonTotalWeight\":118.0,\"cartonTotalVolume\":1.75,"
+ "\"remark\":\"备注\","
+ "\"planProductDetailParamList\":["
+ "{\"sku\":\"DM00001\",\"qty\":60,\"qtyPacked\":60,"
+ "\"qtyReceived\":58,\"qtyReceivedSaleable\":55,"
+ "\"qtyReceivedUnsaleable\":3,\"receivedTime\":\"2026-11-21 10:00:00\"},"
+ "{\"sku\":\"DM00002\",\"qty\":40,\"qtyPacked\":38,"
+ "\"qtyReceived\":37,\"qtyReceivedSaleable\":37,"
+ "\"qtyReceivedUnsaleable\":0,\"receivedTime\":\"2026-11-21 10:30:00\"}],"
+ "\"batchInfo\":{"
+ "\"planBatchItems\":[{\"sku\":\"DM00001\",\"qty\":60,\"cartonNo\":\"C001\","
+ "\"batchParam\":[{\"batchAttriKey\":\"ProductionDateNumber\","
+ "\"batchAttriValue\":\"20261101\"}],\"inventoryType\":0}],"
+ "\"inboundBatchItems\":[{\"sku\":\"DM00001\",\"qty\":58,\"cartonNo\":\"C001\","
+ "\"batchParam\":[{\"batchAttriKey\":\"LotCode\","
+ "\"batchAttriValue\":\"L2026\"}],\"inventoryType\":0}]},"
+ "\"boxInfo\":[{\"cartonNo\":\"C001\",\"productInfo\":["
+ "{\"sku\":\"DM00001\",\"planQty\":60,\"inboundQty\":58}]}],"
+ "\"packingLabelUrl\":\"https://files.example/box-label.pdf\"}}";
@Test
void mapsHeaderLevelSummary() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
InboundOrder order = adapter.get(ctx(), "OMS-IN-001");
assertEquals("OMS-IN-001", order.inboundRequestNo());
assertEquals("IP20261110001", order.providerInboundId());
assertEquals("RF_NY_US", order.warehouseCode());
assertEquals(InboundStatus.STORING, order.status());
assertEquals("25", order.rawStatus());
assertEquals(8, order.boxCount());
// 头级三层数量:之前全丢,现在必须映射
assertEquals(100, order.plannedQuantity());
assertEquals(98, order.packedQuantity());
assertEquals(95, order.receivedQuantity());
assertEquals(WarehouseProvider.YQN, order.sourceProvider());
}
@Test
void mapsLineLevelQuantities() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec())
.get(ctx(), "OMS-IN-001");
assertEquals(2, order.lines().size());
assertEquals("DM00001", order.lines().get(0).providerSku());
assertEquals(60, order.lines().get(0).plannedQuantity());
assertEquals(58, order.lines().get(0).receivedQuantity());
}
@Test
void mapsBatchesFromBothLists() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec())
.get(ctx(), "OMS-IN-001");
List<InboundOrderBatch> batches = order.batches();
assertEquals(2, batches.size());
// 计划批次 + 上架批次各一条
assertEquals("C001", batches.get(0).cartonNo());
assertEquals(60, batches.get(0).quantity());
assertEquals(Integer.valueOf(0), batches.get(0).inventoryType());
assertEquals(1, batches.get(0).params().size());
assertEquals("ProductionDateNumber", batches.get(0).params().get(0).key());
assertEquals("LotCode", batches.get(1).params().get(0).key());
assertEquals(58, batches.get(1).quantity());
}
@Test
void mapsBoxes() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec())
.get(ctx(), "OMS-IN-001");
assertEquals(1, order.boxes().size());
InboundOrderBox box = order.boxes().get(0);
assertEquals("C001", box.cartonNo());
assertEquals(1, box.lines().size());
assertEquals("DM00001", box.lines().get(0).providerSku());
assertEquals(60, box.lines().get(0).plannedQuantity());
assertEquals(58, box.lines().get(0).inboundQuantity());
}
@Test
void mapsPackingLabelUrl() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec())
.get(ctx(), "OMS-IN-001");
assertEquals("https://files.example/box-label.pdf", order.packingLabelUrl());
}
/** 可选字段全缺时不应抛异常,列表为空、数值为 0。 */
@Test
void missingOptionalSectionsAreSafe() {
String minimal = "{\"statusCode\":200,\"status\":0,\"code\":\"200\","
+ "\"data\":{\"orgWarehouseCode\":\"W\",\"inventoryType\":\"0\","
+ "\"inboundPlanOrderNo\":\"IP1\",\"inboundPlanOrderStatus\":\"0\","
+ "\"sourceNo\":\"S1\"}}";
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(minimal));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec()).get(ctx(), "S1");
assertEquals(0, order.plannedQuantity());
assertTrue(order.batches().isEmpty());
assertTrue(order.boxes().isEmpty());
assertNull(order.packingLabelUrl());
assertNull(order.createdAt());
}
/** 未知状态不猜。 */
@Test
void unknownStatusIsNotGuessed() {
String body = "{\"statusCode\":200,\"status\":0,\"code\":\"200\","
+ "\"data\":{\"orgWarehouseCode\":\"W\",\"inventoryType\":\"0\","
+ "\"inboundPlanOrderNo\":\"IP1\",\"inboundPlanOrderStatus\":\"999\","
+ "\"sourceNo\":\"S1\"}}";
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(body));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec()).get(ctx(), "S1");
assertEquals(InboundStatus.UNKNOWN, order.status());
assertEquals("999", order.rawStatus());
}
/** 查单必须带单号:运去哪没有列表接口。 */
@Test
void queryRequiresOrderNo() {
RecordingTransport transport = RecordingTransport.create();
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertThrows(RuntimeException.class, () -> adapter.query(ctx(), (String) null));
assertThrows(RuntimeException.class, () -> adapter.query(ctx(), " "));
assertTrue(transport.recorded().isEmpty());
}
@Test
void queryByOrderNoReturnsSinglePage() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(FULL_BODY));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertEquals(1, adapter.query(ctx(), "OMS-IN-001").size());
}
private static void assertThrows(Class<? extends Throwable> type, Runnable r) {
org.junit.jupiter.api.Assertions.assertThrows(type, r::run);
}
}
Loading…
Cancel
Save