Browse Source

feat(yqn): 按 API 99 对接打印入库计划单箱标

新增 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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
948ff1a96d
  1. 6
      README.md
  2. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java
  3. 43
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java
  4. 55
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java
  5. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java
  6. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  7. 144
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java
  8. 103
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java
  9. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  10. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  11. 21
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  12. 87
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java
  13. 31
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  14. 155
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java

6
README.md

@ -299,7 +299,8 @@ common.ecommerce @@ -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 @@ -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 /

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java

@ -1,9 +1,11 @@ @@ -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 { @@ -30,4 +32,18 @@ public interface InboundCapable extends WarehouseAdapter {
default List<String> bols(WarehouseContext ctx, String inboundRef) {
return Collections.emptyList();
}
/**
* 打印入库计划单箱标。
*
* <p>仓方<b>异步</b>生成文件:返回的 {@link LabelPrintTask} 只有任务编号,
* 下载地址要另外查任务中心。不要指望本调用直接拿到文件。</p>
*
* @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);
}
}

43
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelDownloadMode.java

@ -0,0 +1,43 @@ @@ -0,0 +1,43 @@
package common.ecommerce.warehouse.enums;
/**
* 标签文件导出方式。
*
* <p>与 {@link LabelMode} 不是一回事:那个说的是「面单由谁出」(仓自有 / 平台面单),
* 这个说的是「打印文件怎么打包」。</p>
*/
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;
}
}

55
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java

@ -0,0 +1,55 @@ @@ -0,0 +1,55 @@
package common.ecommerce.warehouse.enums;
/**
* 标签纸尺寸。
*
* <p>与 {@link LabelsPerPage} 联动:每页 1 个时只能用 100×100 / 100×150,
* 每页 6 个时只能用 104×98(美国信纸)。约束在 {@code BoxLabelCommand} 构造期校验。</p>
*/
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;
}
}

38
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelsPerPage.java

@ -0,0 +1,38 @@ @@ -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;
}
}

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -45,7 +45,11 @@ public enum WarehouseCapability { @@ -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;

144
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java

@ -0,0 +1,144 @@ @@ -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;
/**
* 打印箱标命令(入库计划单的外箱标签)。
*
* <p>仓方异步生成文件:调用成功只拿到 {@link LabelPrintTask#taskNo()},下载地址要另外查
* 任务中心。<b>不要指望本调用直接拿到文件</b>。</p>
*
* <p>尺寸与每页数量有联动约束(每页 1 个 → 100×100 或 100×150;每页 6 个 → 104×98),
* 在这里构造期就校验,避免下发后才被仓方拒绝。</p>
*/
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);
}
}
}

103
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseProvider;
/**
* 标签打印任务。
*
* <p>仓方是<b>异步生成</b>文件的:本对象只有任务编号 {@link #taskNo()},文件下载地址需要
* 另外查任务中心(运去哪 API 99 文档明确「后续可通过调用查询任务中心详情接口获取下载地址」)。</p>
*
* <p>{@link #label()} 在任务已同步完成、仓方直接返回文件时才有值;异步生成的仓恒为 null。</p>
*/
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);
}
}
}

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -28,9 +28,11 @@ import common.ecommerce.warehouse.model.TransferOrder; @@ -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 { @@ -306,6 +308,24 @@ public final class WarehouseOperations {
require(WarehouseCapability.INBOUND, InboundCapable.class);
return ((InboundCapable) adapter).bols(ctx, inboundRef);
}
/**
* 打印入库计划单箱标。
*
* <p>只读语义但仓方是异步生成:调用成功只拿到任务编号,文件要另外去任务中心取。
* 所以不走幂等守卫——重复调用只是再生成一份,不会改业务状态。</p>
*/
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));
}
}
/** 退货视图。 */

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -38,6 +38,8 @@ public final class YqnConstants { @@ -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)。 */

21
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -30,8 +30,10 @@ import common.ecommerce.warehouse.capability.WarehouseReturnCapable; @@ -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 @@ -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 @@ -493,6 +496,24 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ 入库箱标
/**
* 打印入库计划单箱标(API 99)。
*
* <p>仓方异步生成文件:响应只有 {@code taskNo},没有文件内容,下载地址要另外查
* 任务中心。所以返回的 {@link LabelPrintTask#label()} 恒为 null。</p>
*/
@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);
}
// ------------------------------------------------------------------ 销毁
/**

87
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnBoxLabelMapper.java

@ -0,0 +1,87 @@ @@ -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)。
*
* <p>尺寸 / 每页数量的联动约束已在 {@code BoxLabelCommand} 构造期校验,这里只做码值搬运。</p>
*/
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();
}
}

31
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -1065,4 +1065,35 @@ public final class YqnDtos { @@ -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;
}
}

155
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnBoxLabelTest.java

@ -0,0 +1,155 @@ @@ -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());
}
}
Loading…
Cancel
Save