From 948ff1a96dfb133b3c9e3bc46a4c661c361b0761 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 10 Nov 2026 14:41:00 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=2099=20=E5=AF=B9?= =?UTF-8?q?=E6=8E=A5=E6=89=93=E5=8D=B0=E5=85=A5=E5=BA=93=E8=AE=A1=E5=88=92?= =?UTF-8?q?=E5=8D=95=E7=AE=B1=E6=A0=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 BOX_LABEL 能力位与 SKU_LABEL(后者预留,本期未接)。 - BoxLabelCommand:仓侧单号 + 来源单号 + 导出方式 + 尺寸 + 每页数量 + 两份 + 展示客户码 - LabelDownloadMode(压缩包 / 单个 PDF)、LabelSizeType(100×100 / 100×150 / 104×98)、LabelsPerPage(1 / 6)三个底层枚举,仓方码值由 YqnBoxLabelMapper 映射 - LabelPrintTask:只有任务编号,label() 恒为 null——仓方异步生成文件, 下载地址要另外查任务中心。Javadoc 写清「本调用拿不到文件」 - InboundCapable.printBoxLabel 默认抛不支持;门面为 inbound().printBoxLabel(cmd) 尺寸与每页数量有联动约束(每页 1 个 → 100×100/100×150;每页 6 个 → 104×98), 在 BoxLabelCommand 构造期校验,不等仓方拒绝。这条规则的错误此前只会表现为 仓方业务报错,排查成本高。 不走幂等守卫:重复调用只是再生成一份文件,不改业务状态。 Co-Authored-By: Claude --- README.md | 6 +- .../warehouse/capability/InboundCapable.java | 16 +++ .../warehouse/enums/LabelDownloadMode.java | 43 ++++++ .../ecommerce/warehouse/enums/LabelSizeType.java | 55 ++++++++ .../ecommerce/warehouse/enums/LabelsPerPage.java | 38 +++++ .../warehouse/enums/WarehouseCapability.java | 6 +- .../ecommerce/warehouse/model/BoxLabelCommand.java | 144 +++++++++++++++++++ .../ecommerce/warehouse/model/LabelPrintTask.java | 103 ++++++++++++++ .../warehouse/sdk/WarehouseOperations.java | 20 +++ .../java/common/ecommerce/yqn/YqnConstants.java | 2 + .../common/ecommerce/yqn/adapter/YqnAdapter.java | 21 +++ .../ecommerce/yqn/adapter/YqnBoxLabelMapper.java | 87 ++++++++++++ .../java/common/ecommerce/yqn/dto/YqnDtos.java | 31 +++++ .../ecommerce/yqn/adapter/YqnBoxLabelTest.java | 155 +++++++++++++++++++++ 14 files changed, 724 insertions(+), 3 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java diff --git a/README.md b/README.md index 6b8cc9a..c02c5b0 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,8 @@ common.ecommerce │ │ WarehouseProvider / WarehouseCapability / OutboundStatus / │ │ InboundStatus / TransferStatus / TransferType / LabelMode / │ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType / -│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType +│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / +│ │ LabelDownloadMode / LabelSizeType / LabelsPerPage │ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine / │ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec / │ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult / @@ -308,7 +309,8 @@ common.ecommerce │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / │ │ WarehouseReturn / TransferCommand / TransferOrder / │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / -│ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder +│ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder / +│ │ BoxLabelCommand / LabelPrintTask / WarehouseLabel │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / │ │ WarehouseReturnCapable / WarehouseFeeCapable / │ │ WarehouseFeeEstimateCapable / TransferCapable / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java index 0686174..f96eb7e 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java @@ -1,9 +1,11 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.model.BoxLabelCommand; import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; +import common.ecommerce.warehouse.model.LabelPrintTask; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -30,4 +32,18 @@ public interface InboundCapable extends WarehouseAdapter { default List bols(WarehouseContext ctx, String inboundRef) { return Collections.emptyList(); } + + /** + * 打印入库计划单箱标。 + * + *

仓方异步生成文件:返回的 {@link LabelPrintTask} 只有任务编号, + * 下载地址要另外查任务中心。不要指望本调用直接拿到文件。

+ * + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code BOX_LABEL} + */ + default LabelPrintTask printBoxLabel(WarehouseContext ctx, BoxLabelCommand cmd) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.BOX_LABEL); + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java new file mode 100644 index 0000000..9148e6f --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java @@ -0,0 +1,43 @@ +package common.ecommerce.warehouse.enums; + +/** + * 标签文件导出方式。 + * + *

与 {@link LabelMode} 不是一回事:那个说的是「面单由谁出」(仓自有 / 平台面单), + * 这个说的是「打印文件怎么打包」。

+ */ +public enum LabelDownloadMode { + + /** 多张标签合成一个压缩包。 */ + ARCHIVE(10, "压缩包"), + /** 多张标签合成一个 PDF。 */ + PDF(20, "单个PDF"); + + private final int code; + private final String label; + + LabelDownloadMode(int code, String label) { + this.code = code; + this.label = label; + } + + /** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ + public int code() { + return code; + } + + /** 中文显示名。 */ + public String label() { + return label; + } + + /** 按落库码反查。 */ + public static LabelDownloadMode ofCode(int code) { + for (LabelDownloadMode v : values()) { + if (v.code == code) { + return v; + } + } + return null; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java new file mode 100644 index 0000000..537ddb9 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java @@ -0,0 +1,55 @@ +package common.ecommerce.warehouse.enums; + +/** + * 标签纸尺寸。 + * + *

与 {@link LabelsPerPage} 联动:每页 1 个时只能用 100×100 / 100×150, + * 每页 6 个时只能用 104×98(美国信纸)。约束在 {@code BoxLabelCommand} 构造期校验。

+ */ +public enum LabelSizeType { + + /** 100mm × 100mm。 */ + SIZE_100_100(10, "100×100"), + /** 100mm × 150mm。 */ + SIZE_100_150(20, "100×150"), + /** 104mm × 98mm(美国信纸)。 */ + SIZE_104_98(30, "104×98(美国信纸)"); + + private final int code; + private final String label; + + LabelSizeType(int code, String label) { + this.code = code; + this.label = label; + } + + /** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ + public int code() { + return code; + } + + /** 中文显示名。 */ + public String label() { + return label; + } + + /** 按落库码反查。 */ + public static LabelSizeType ofCode(int code) { + for (LabelSizeType v : values()) { + if (v.code == code) { + return v; + } + } + return null; + } + + /** 是否可用于每页 1 个的排版。 */ + public boolean singlePerPage() { + return this == SIZE_100_100 || this == SIZE_100_150; + } + + /** 是否可用于每页 6 个的排版。 */ + public boolean sixPerPage() { + return this == SIZE_104_98; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java new file mode 100644 index 0000000..aa247ae --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java @@ -0,0 +1,38 @@ +package common.ecommerce.warehouse.enums; + +/** 每页标签数量。 */ +public enum LabelsPerPage { + + /** 每页一个。 */ + ONE(1, "每页1个"), + /** 每页 6 个(需配 104×98 美国信纸)。 */ + SIX(6, "每页6个"); + + private final int count; + private final String label; + + LabelsPerPage(int count, String label) { + this.count = count; + this.label = label; + } + + /** 每页标签数量本身(不是落库码)。 */ + public int count() { + return count; + } + + /** 中文显示名。 */ + public String label() { + return label; + } + + /** 按每页数量反查;不支持的数量返回 null。 */ + public static LabelsPerPage ofCount(int count) { + for (LabelsPerPage v : values()) { + if (v.count == count) { + return v; + } + } + return null; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java index f0e082d..9139ea8 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java @@ -45,7 +45,11 @@ public enum WarehouseCapability { /** 费用试算 */ FEE_ESTIMATE(180, "费用试算"), /** 状态回调推送 */ - WEBHOOK(190, "状态回调"); + WEBHOOK(190, "状态回调"), + /** 打印入库计划单箱标(异步任务) */ + BOX_LABEL(200, "入库箱标"), + /** 打印 SKU 标 */ + SKU_LABEL(210, "SKU标"); private final int code; private final String label; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java new file mode 100644 index 0000000..cbea449 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java @@ -0,0 +1,144 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.LabelDownloadMode; +import common.ecommerce.warehouse.enums.LabelSizeType; +import common.ecommerce.warehouse.enums.LabelsPerPage; + +/** + * 打印箱标命令(入库计划单的外箱标签)。 + * + *

仓方异步生成文件:调用成功只拿到 {@link LabelPrintTask#taskNo()},下载地址要另外查 + * 任务中心。不要指望本调用直接拿到文件。

+ * + *

尺寸与每页数量有联动约束(每页 1 个 → 100×100 或 100×150;每页 6 个 → 104×98), + * 在这里构造期就校验,避免下发后才被仓方拒绝。

+ */ +public final class BoxLabelCommand { + + /** 入库计划单号(仓方口径),必填。 */ + private final String providerInboundNo; + /** 来源单号(OMS 下发入库单时的单号),必填。 */ + private final String inboundRequestNo; + private final LabelDownloadMode downloadMode; + private final LabelSizeType sizeType; + private final LabelsPerPage labelsPerPage; + /** 是否一式两份。 */ + private final boolean twoCopies; + /** 是否展示客户唯一标识符。 */ + private final boolean showOrgUniqueCode; + + private BoxLabelCommand(Builder b) { + this.providerInboundNo = require(b.providerInboundNo, "providerInboundNo"); + this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo"); + this.downloadMode = java.util.Objects.requireNonNull(b.downloadMode, "downloadMode"); + this.sizeType = java.util.Objects.requireNonNull(b.sizeType, "sizeType"); + this.labelsPerPage = java.util.Objects.requireNonNull(b.labelsPerPage, "labelsPerPage"); + requireCompatible(sizeType, labelsPerPage); + this.twoCopies = b.twoCopies; + this.showOrgUniqueCode = b.showOrgUniqueCode; + } + + public static Builder builder() { + return new Builder(); + } + + /** 入库计划单号(仓方口径)。 */ + public String providerInboundNo() { + return providerInboundNo; + } + + /** 来源单号(OMS 入库单号)。 */ + public String inboundRequestNo() { + return inboundRequestNo; + } + + public LabelDownloadMode downloadMode() { + return downloadMode; + } + + public LabelSizeType sizeType() { + return sizeType; + } + + public LabelsPerPage labelsPerPage() { + return labelsPerPage; + } + + public boolean twoCopies() { + return twoCopies; + } + + public boolean showOrgUniqueCode() { + return showOrgUniqueCode; + } + + /** 尺寸与每页数量必须匹配,否则仓方会拒绝——在构造期就失败,别等下发。 */ + private static void requireCompatible(LabelSizeType size, LabelsPerPage perPage) { + if (perPage == LabelsPerPage.ONE && !size.singlePerPage()) { + throw new IllegalArgumentException( + "sizeType " + size.label() + " is only valid when labelsPerPage=6; " + + "use 100x100 or 100x150 for one per page"); + } + if (perPage == LabelsPerPage.SIX && !size.sixPerPage()) { + throw new IllegalArgumentException( + "sizeType " + size.label() + " is only valid when labelsPerPage=1; " + + "use 104x98 (US letter) for six per page"); + } + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String providerInboundNo; + private String inboundRequestNo; + private LabelDownloadMode downloadMode = LabelDownloadMode.PDF; + private LabelSizeType sizeType = LabelSizeType.SIZE_100_100; + private LabelsPerPage labelsPerPage = LabelsPerPage.ONE; + private boolean twoCopies; + private boolean showOrgUniqueCode; + + public Builder providerInboundNo(String v) { + this.providerInboundNo = v; + return this; + } + + public Builder inboundRequestNo(String v) { + this.inboundRequestNo = v; + return this; + } + + public Builder downloadMode(LabelDownloadMode v) { + this.downloadMode = v; + return this; + } + + public Builder sizeType(LabelSizeType v) { + this.sizeType = v; + return this; + } + + public Builder labelsPerPage(LabelsPerPage v) { + this.labelsPerPage = v; + return this; + } + + public Builder twoCopies(boolean v) { + this.twoCopies = v; + return this; + } + + public Builder showOrgUniqueCode(boolean v) { + this.showOrgUniqueCode = v; + return this; + } + + public BoxLabelCommand build() { + return new BoxLabelCommand(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java new file mode 100644 index 0000000..3f0b816 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java @@ -0,0 +1,103 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.WarehouseProvider; + +/** + * 标签打印任务。 + * + *

仓方是异步生成文件的:本对象只有任务编号 {@link #taskNo()},文件下载地址需要 + * 另外查任务中心(运去哪 API 99 文档明确「后续可通过调用查询任务中心详情接口获取下载地址」)。

+ * + *

{@link #label()} 在任务已同步完成、仓方直接返回文件时才有值;异步生成的仓恒为 null。

+ */ +public final class LabelPrintTask { + + private final WarehouseProvider sourceProvider; + private final String taskNo; + /** 仓侧的入库计划单号(运去哪 {@code orderNo})。 */ + private final String providerInboundNo; + /** 来源单号(OMS 入库单号)。 */ + private final String inboundRequestNo; + /** 已生成的文件;异步任务为 null。 */ + private final WarehouseLabel label; + + private LabelPrintTask(Builder b) { + this.sourceProvider = b.sourceProvider; + this.taskNo = require(b.taskNo, "taskNo"); + this.providerInboundNo = b.providerInboundNo; + this.inboundRequestNo = b.inboundRequestNo; + this.label = b.label; + } + + public static Builder builder() { + return new Builder(); + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + /** 任务编号;用它去任务中心查下载地址。 */ + public String taskNo() { + return taskNo; + } + + /** 仓侧入库计划单号。 */ + public String providerInboundNo() { + return providerInboundNo; + } + + /** 来源单号(OMS 入库单号)。 */ + public String inboundRequestNo() { + return inboundRequestNo; + } + + /** 已生成的文件;异步任务为 null。 */ + public WarehouseLabel label() { + return label; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private WarehouseProvider sourceProvider; + private String taskNo; + private String providerInboundNo; + private String inboundRequestNo; + private WarehouseLabel label; + + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public Builder taskNo(String v) { + this.taskNo = v; + return this; + } + + public Builder providerInboundNo(String v) { + this.providerInboundNo = v; + return this; + } + + public Builder inboundRequestNo(String v) { + this.inboundRequestNo = v; + return this; + } + + public Builder label(WarehouseLabel v) { + this.label = v; + return this; + } + + public LabelPrintTask build() { + return new LabelPrintTask(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 17466ab..9386785 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -28,9 +28,11 @@ import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.model.DestructionCommand; import common.ecommerce.warehouse.model.DestructionOrder; +import common.ecommerce.warehouse.model.BoxLabelCommand; import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; +import common.ecommerce.warehouse.model.LabelPrintTask; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.enums.InventorySyncStrategy; @@ -306,6 +308,24 @@ public final class WarehouseOperations { require(WarehouseCapability.INBOUND, InboundCapable.class); return ((InboundCapable) adapter).bols(ctx, inboundRef); } + + /** + * 打印入库计划单箱标。 + * + *

只读语义但仓方是异步生成:调用成功只拿到任务编号,文件要另外去任务中心取。 + * 所以不走幂等守卫——重复调用只是再生成一份,不会改业务状态。

+ */ + public LabelPrintTask printBoxLabel(BoxLabelCommand cmd) { + require(WarehouseCapability.BOX_LABEL, InboundCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.inbound.boxLabel", + CallSupport.params("providerInboundNo", cmd.providerInboundNo(), + "inboundRequestNo", cmd.inboundRequestNo(), + "downloadMode", cmd.downloadMode(), + "sizeType", cmd.sizeType(), + "labelsPerPage", cmd.labelsPerPage()), + r -> CallSupport.NO_COUNT, + () -> ((InboundCapable) adapter).printBoxLabel(ctx, cmd)); + } } /** 退货视图。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index e4b7578..77bc81e 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -38,6 +38,8 @@ public final class YqnConstants { public static final String PATH_TRANSFER_CREATE = "/v2/transferOutboundPlan/create"; /** 创建入库计划单(API 97)。 */ public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; + /** 打印入库计划单箱标(API 99):异步生成,只回任务编号。 */ + public static final String PATH_INBOUND_BOX_LABEL = "/v1/inbound/generateBoxLabel"; /** 查询入库计划(API 101)。 */ public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo"; /** 创建销售退货(API 81)。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 944a270..c8237c9 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -30,8 +30,10 @@ import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; +import common.ecommerce.warehouse.model.BoxLabelCommand; import common.ecommerce.warehouse.model.DestructionCommand; import common.ecommerce.warehouse.model.DestructionOrder; +import common.ecommerce.warehouse.model.LabelPrintTask; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; @@ -113,6 +115,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, + WarehouseCapability.BOX_LABEL, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, WarehouseCapability.RETURN_DISPOSITION, @@ -493,6 +496,24 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); } + // ------------------------------------------------------------------ 入库箱标 + + /** + * 打印入库计划单箱标(API 99)。 + * + *

仓方异步生成文件:响应只有 {@code taskNo},没有文件内容,下载地址要另外查 + * 任务中心。所以返回的 {@link LabelPrintTask#label()} 恒为 null。

+ */ + @Override + public LabelPrintTask printBoxLabel(WarehouseContext ctx, BoxLabelCommand cmd) { + YqnDtos.BoxLabelRequest body = YqnBoxLabelMapper.toRequest(cmd); + String raw = execute(ctx, YqnConstants.PATH_INBOUND_BOX_LABEL, body, + "warehouse.inbound.boxLabel"); + YqnDtos.BoxLabelResponse resp = + json.fromJson(String.valueOf(json.nodeAt(raw, "data")), YqnDtos.BoxLabelResponse.class); + return YqnBoxLabelMapper.toTask(resp, cmd); + } + // ------------------------------------------------------------------ 销毁 /** diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java new file mode 100644 index 0000000..5eb0cf7 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java @@ -0,0 +1,87 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.warehouse.enums.LabelDownloadMode; +import common.ecommerce.warehouse.enums.LabelSizeType; +import common.ecommerce.warehouse.enums.LabelsPerPage; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BoxLabelCommand; +import common.ecommerce.warehouse.model.LabelPrintTask; +import common.ecommerce.yqn.dto.YqnDtos; + +/** + * 运去哪入库箱标报文映射(API 99)。 + * + *

尺寸 / 每页数量的联动约束已在 {@code BoxLabelCommand} 构造期校验,这里只做码值搬运。

+ */ +public final class YqnBoxLabelMapper { + + private YqnBoxLabelMapper() { + } + + /** 统一命令 → 运去哪请求。 */ + public static YqnDtos.BoxLabelRequest toRequest(BoxLabelCommand cmd) { + YqnDtos.BoxLabelRequest req = new YqnDtos.BoxLabelRequest(); + req.orderNo = cmd.providerInboundNo(); + req.sourceNo = cmd.inboundRequestNo(); + req.downloadMode = downloadModeCode(cmd.downloadMode()); + req.labelSizeType = sizeTypeCode(cmd.sizeType()); + req.numPerPage = cmd.labelsPerPage().count(); + req.twoCopies = cmd.twoCopies(); + req.showOrgUniqueCode = cmd.showOrgUniqueCode(); + return req; + } + + /** 响应 → 任务。异步接口只回任务编号,不带文件。 */ + public static LabelPrintTask toTask(YqnDtos.BoxLabelResponse resp, BoxLabelCommand cmd) { + return LabelPrintTask.builder() + .sourceProvider(WarehouseProvider.YQN) + .taskNo(resp.taskNo) + .providerInboundNo(hasText(resp.orderNo) ? resp.orderNo : cmd.providerInboundNo()) + .inboundRequestNo(hasText(resp.sourceNo) ? resp.sourceNo : cmd.inboundRequestNo()) + .build(); + } + + /** 导出方式 → 运去哪 downloadMode:1 压缩包 / 2 单个 PDF。 */ + static Integer downloadModeCode(LabelDownloadMode mode) { + if (mode == null) { + return null; + } + switch (mode) { + case ARCHIVE: + return 1; + case PDF: + return 2; + default: + throw new IllegalArgumentException("yqn does not support downloadMode: " + mode); + } + } + + /** 尺寸 → 运去哪 labelSizeType:1 100×100 / 2 100×150 / 3 104×98。 */ + static Integer sizeTypeCode(LabelSizeType size) { + if (size == null) { + return null; + } + switch (size) { + case SIZE_100_100: + return 1; + case SIZE_100_150: + return 2; + case SIZE_104_98: + return 3; + default: + throw new IllegalArgumentException("yqn does not support labelSizeType: " + size); + } + } + + /** 每页数量 → 运去哪 numPerPage;只支持 1 与 6。 */ + static Integer numPerPageCode(LabelsPerPage perPage) { + if (perPage == null) { + return null; + } + return perPage.count(); + } + + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index 3fdc3fc..eb1f00c 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -1065,4 +1065,35 @@ public final class YqnDtos { /** 仓侧销毁计划单号。 */ public String destroyPlanOrderNo; } + + // ------------------------------------------------------------------ 入库箱标(API 99) + + /** 打印入库计划单箱标请求(API 99 {@code /v1/inbound/generateBoxLabel})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BoxLabelRequest { + + /** 入库计划单号(仓侧 ip 单号)。 */ + public String orderNo; + /** 来源单号(OMS 推单时的外部单号)。 */ + public String sourceNo; + /** 1 合成压缩包 / 2 合成一个 pdf。 */ + public Integer downloadMode; + /** 1 100*100 / 2 100*150 / 3 104*98(美国信纸)。 */ + public Integer labelSizeType; + /** 每页打印数量 1 / 6。 */ + public Integer numPerPage; + /** 是否一式两份。 */ + public Boolean twoCopies; + /** 是否展示客户唯一标识符。 */ + public Boolean showOrgUniqueCode; + } + + /** 打印入库计划单箱标响应(API 99 {@code data})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BoxLabelResponse { + /** 任务编号;文件生成后靠它去任务中心查下载地址。 */ + public String taskNo; + public String orderNo; + public String sourceNo; + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java new file mode 100644 index 0000000..9aee711 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java @@ -0,0 +1,155 @@ +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.LabelDownloadMode; +import common.ecommerce.warehouse.enums.LabelSizeType; +import common.ecommerce.warehouse.enums.LabelsPerPage; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BoxLabelCommand; +import common.ecommerce.warehouse.model.LabelPrintTask; +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 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 99)契约测试。 + */ +class YqnBoxLabelTest { + + 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-label", CLOCK); + } + + private static BoxLabelCommand command() { + return BoxLabelCommand.builder() + .providerInboundNo("IP20261110001") + .inboundRequestNo("OMS-IN-001") + .downloadMode(LabelDownloadMode.PDF) + .sizeType(LabelSizeType.SIZE_100_100) + .labelsPerPage(LabelsPerPage.ONE) + .twoCopies(true) + .showOrgUniqueCode(true) + .build(); + } + + private static String okBody() { + return "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"," + + "\"data\":{\"taskNo\":\"TASK-1\",\"orderNo\":\"IP20261110001\"," + + "\"sourceNo\":\"OMS-IN-001\"}}"; + } + + @Test + void sendsDocumentedShape() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_INBOUND_BOX_LABEL, req -> Responses.ok(okBody())); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + LabelPrintTask task = adapter.printBoxLabel(ctx(), command()); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"orderNo\":\"IP20261110001\""), body); + assertTrue(body.contains("\"sourceNo\":\"OMS-IN-001\""), body); + assertTrue(body.contains("\"downloadMode\":2"), body); + assertTrue(body.contains("\"labelSizeType\":1"), body); + assertTrue(body.contains("\"numPerPage\":1"), body); + assertTrue(body.contains("\"twoCopies\":true"), body); + assertTrue(body.contains("\"showOrgUniqueCode\":true"), body); + + assertEquals("TASK-1", task.taskNo()); + assertEquals("IP20261110001", task.providerInboundNo()); + assertEquals("OMS-IN-001", task.inboundRequestNo()); + assertEquals(WarehouseProvider.YQN, task.sourceProvider()); + } + + /** 异步接口只回任务编号,不返回文件。 */ + @Test + void taskCarriesNoLabelFile() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_INBOUND_BOX_LABEL, req -> Responses.ok(okBody())); + + LabelPrintTask task = new YqnAdapter(transport, new JacksonJsonCodec()) + .printBoxLabel(ctx(), command()); + + assertNull(task.label()); + } + + @Test + void sixPerPageUsesUsLetterSize() { + BoxLabelCommand sixPerPage = BoxLabelCommand.builder() + .providerInboundNo("IP1") + .inboundRequestNo("OMS-1") + .sizeType(LabelSizeType.SIZE_104_98) + .labelsPerPage(LabelsPerPage.SIX) + .build(); + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_INBOUND_BOX_LABEL, req -> Responses.ok(okBody())); + new YqnAdapter(transport, new JacksonJsonCodec()).printBoxLabel(ctx(), sixPerPage); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"labelSizeType\":3"), body); + assertTrue(body.contains("\"numPerPage\":6"), body); + // 默认值:PDF + 不两份 + 不展示客户码 + assertTrue(body.contains("\"downloadMode\":2"), body); + assertTrue(body.contains("\"twoCopies\":false"), body); + } + + /** 尺寸与每页数量不匹配,构造期就失败,不等仓方拒绝。 */ + @Test + void incompatibleSizeAndPerPageRejected() { + assertThrows(IllegalArgumentException.class, () -> BoxLabelCommand.builder() + .providerInboundNo("IP1").inboundRequestNo("OMS-1") + .sizeType(LabelSizeType.SIZE_104_98) + .labelsPerPage(LabelsPerPage.ONE) + .build()); + + assertThrows(IllegalArgumentException.class, () -> BoxLabelCommand.builder() + .providerInboundNo("IP1").inboundRequestNo("OMS-1") + .sizeType(LabelSizeType.SIZE_100_100) + .labelsPerPage(LabelsPerPage.SIX) + .build()); + } + + @Test + void archiveModeMapsToOne() { + assertEquals(Integer.valueOf(1), + YqnBoxLabelMapper.downloadModeCode(LabelDownloadMode.ARCHIVE)); + assertEquals(Integer.valueOf(2), + YqnBoxLabelMapper.downloadModeCode(LabelDownloadMode.PDF)); + assertEquals(Integer.valueOf(2), + YqnBoxLabelMapper.sizeTypeCode(LabelSizeType.SIZE_100_150)); + assertNull(YqnBoxLabelMapper.sizeTypeCode(null)); + } + + @Test + void declaresBoxLabelCapability() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertTrue(adapter.capabilities().contains(WarehouseCapability.BOX_LABEL)); + } + + @Test + void blankNumbersRejected() { + assertThrows(IllegalArgumentException.class, () -> BoxLabelCommand.builder() + .inboundRequestNo("OMS-1").build()); + assertThrows(IllegalArgumentException.class, () -> BoxLabelCommand.builder() + .providerInboundNo("IP1").build()); + } +}