diff --git a/README.md b/README.md index 17a0a47..b16b0e7 100644 --- a/README.md +++ b/README.md @@ -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 / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java index 8b86999..23f692c 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java @@ -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 batches; + /** 箱明细:每箱装了哪些 SKU。 */ + private final List boxes; + /** 纸箱 Label 文件地址;仓方文档称将改为异步任务,可能为 null。 */ + private final String packingLabelUrl; /** * 创建时间(UTC)。 * @@ -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(b.batches)); + this.boxes = Collections.unmodifiableList(new ArrayList(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 { return boxCount; } + /** 头级计划数量。 */ + public int plannedQuantity() { + return plannedQuantity; + } + + /** 头级已装箱数量。 */ + public int packedQuantity() { + return packedQuantity; + } + + /** 头级实收数量。 */ + public int receivedQuantity() { + return receivedQuantity; + } + + /** 计划 / 上架批次明细;不可变。 */ + public List batches() { + return batches; + } + + /** 箱明细;不可变。 */ + public List boxes() { + return boxes; + } + + /** 纸箱 Label 地址;仓方可能不再返回。 */ + public String packingLabelUrl() { + return packingLabelUrl; + } + public Instant createdAt() { return createdAt; } @@ -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 batches = new ArrayList(); + private final List boxes = new ArrayList(); + private String packingLabelUrl; private Instant createdAt; private Instant receivedAt; private Instant estimatedArrivalAt; @@ -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; 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 new file mode 100644 index 0000000..5a66e0f --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBatch.java @@ -0,0 +1,112 @@ +package common.ecommerce.warehouse.model; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 入库单的批次明细(计划或上架)。 + * + *

与 {@link InboundBatch}(下发时的批次)不是一回事:这个是仓方 + * 回查时给的批次分布,多了箱唛号与库存类型。

+ */ +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 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(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 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 params = new ArrayList(); + + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBox.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBox.java new file mode 100644 index 0000000..f1f7b2d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderBox.java @@ -0,0 +1,110 @@ +package common.ecommerce.warehouse.model; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 入库单的箱明细:一箱装了哪些 SKU 的计划量与上架量。 + * + *

用于核对「这箱货到底收了多少」——头级汇总只能看总数, + * 短少 / 溢装要落到箱和 SKU 才定位得到。

+ */ +public final class InboundOrderBox { + + /** 箱唛号。 */ + private final String cartonNo; + private final List lines; + + private InboundOrderBox(Builder b) { + this.cartonNo = b.cartonNo; + this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); + } + + public static Builder builder() { + return new Builder(); + } + + public String cartonNo() { + return cartonNo; + } + + public List 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 lines = new ArrayList(); + + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java index 5501357..01a18f8 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java @@ -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); diff --git a/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWebhookAdapter.java b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWebhookAdapter.java new file mode 100644 index 0000000..914aa3d --- /dev/null +++ b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWebhookAdapter.java @@ -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(...)} 的分派、 + * 验签失败传播与解析结果透传。 + * + *

不做真实签名:只要请求头里带 {@code X-Signature} 且等于构造时给的值就算通过, + * 便于测试「验签失败 → 异常」这条路径而不必实现某家仓的算法。

+ */ +public final class FakeWebhookAdapter implements WarehouseWebhookCapable { + + /** 通过验签所需的签名值。 */ + private final String expectedSignature; + /** 解析出的回调;默认一条面单事件。 */ + private List parsed; + private int verifyCalls; + private int parseCalls; + /** 置 true 时 verify 抛异常,模拟验签失败。 */ + private boolean failVerify; + + public FakeWebhookAdapter(String expectedSignature) { + this.expectedSignature = expectedSignature; + this.parsed = new ArrayList(); + this.parsed.add(WarehouseCallback.builder() + .sourceProvider(WarehouseProvider.CUSTOM) + .eventType(WarehouseEventType.LABEL_PURCHASED) + .rawEventType("FAKE") + .providerOrderNo("WH-1") + .build()); + } + + public FakeWebhookAdapter parsed(List 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 capabilities() { + return EnumSet.of(WarehouseCapability.WEBHOOK); + } + + @Override + public void verify(ChannelSecret secret, Map 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 parse(WarehouseContext ctx, ChannelSecret secret, + Map headers, String rawBody) { + parseCalls++; + return parsed; + } +} diff --git a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseWebhookSdkTest.java b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseWebhookSdkTest.java new file mode 100644 index 0000000..4319784 --- /dev/null +++ b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseWebhookSdkTest.java @@ -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 分派、验签失败传播、解析结果透传。 + * + *

回调进来时只有 provider,没有 warehouseCode——这个入口不能依赖仓账户, + * 所以用不配置任何账户的 SDK 也能跑通。

+ */ +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 headers(String signature) { + Map h = new LinkedHashMap(); + h.put("X-Signature", signature); + return h; + } + + private static ChannelSecret secret() { + return ChannelSecret.builder().appKey("ak").appSecret("sk").build(); + } + + @Test + void dispatchesByProviderWithoutWarehouseAccount() { + List 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 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 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 out = sdk.webhook(WarehouseProvider.CUSTOM, null, + headers(SIGNATURE), BODY, NOW); + + assertEquals(1, out.size()); + } +} 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 f3ad49b..085cf9d 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 @@ -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 { .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 toOrderBatches( + YqnInboundPlanDtos.InboundPlanInfo.BatchInfo batchInfo) { + List out = + new ArrayList(); + if (batchInfo == null) { + return out; + } + addBatches(out, batchInfo.planBatchItems); + addBatches(out, batchInfo.inboundBatchItems); + return out; + } + + private static void addBatches(List out, + List 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 toOrderBoxes( + List boxes) { + List out = + new ArrayList(); + 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 toOrderLines( diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java index b9875e4..4f63ea9 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInboundPlanDtos.java @@ -69,6 +69,63 @@ public final class YqnInboundPlanDtos { public String remark; /** 产品详情(计划 / 装箱 / 实收)。 */ public List planProductDetailParamList; + /** 批次明细:计划批次与上架批次。 */ + public BatchInfo batchInfo; + /** 箱明细:每箱装了哪些 SKU、各多少。 */ + public List boxInfo; + /** + * 纸箱 Label 文件地址。 + * + *

文档已标注「现在应该通过打印箱标接口异步生成箱标,通过任务编号查询任务中心 + * 接口获取箱标地址」——这个字段可能逐渐废弃,取不到属正常。

+ */ + public String packingLabelUrl; + + /** 批次明细。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BatchInfo { + /** 计划批次。 */ + public List planBatchItems; + /** 上架批次。 */ + public List inboundBatchItems; + } + + /** 一条批次明细。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BatchItem { + public String sku; + public Integer qty; + /** 箱唛号。 */ + public String cartonNo; + public List 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 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) 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 new file mode 100644 index 0000000..684da4f --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnInboundPlanTest.java @@ -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 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 type, Runnable r) { + org.junit.jupiter.api.Assertions.assertThrows(type, r::run); + } +}