Browse Source

feat(hengjian): 对接入库箱标生成 /v2/inbound/boxLabelGenerate

真机确认必填五项:inboundPlanOrderNo / type / pageSize / isIndexNo /
isOriginCountry(空 body 时仓方一次性列出全部缺失项);paperType 与
fileNamingType 选填。

- 响应无 data:只有 code/message,不回任务号也不回文件,文件要去
  入库计划详情的 packingLabelUrl 取。所以 LabelPrintTask.taskNo 恒为
  null,不代表调用失败
- 份数口径不同:twoCopies → type 1 一式一份 / 2 一式两份,是份数码
  不是布尔
- 恒健没有 sizeType / downloadMode 口径,改用 paperType(1 A4 /
  2 10×10);labelsPerPage 直接映射 pageSize
- isIndexNo / isOriginCountry 仓方标必填,统一模型是 null-able:
  null 时本地拒绝而不是猜——猜「是」每箱多印一行,猜「否」漏印
- core LabelPrintTask.taskNo 改为可空;BoxLabelCommand 补
  showIndexNo / showOriginCountry / paperTypeCode / fileNamingType

顺带修正一处笔误:AddressClassificationCapable 的 @param city
被改成「必」,恢复为「必填」。

验证:mvn test 全量通过,恒健 340 个用例(+11)通过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
feature/Walmart
lml 3 days ago
parent
commit
93e85bfeb7
  1. 6
      README.md
  2. 41
      docs-warehouse/hengjian/README.md
  3. 77
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BoxLabelCommand.java
  4. 14
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelPrintTask.java
  5. 9
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  6. 30
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  7. 103
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianBoxLabelMapper.java
  8. 56
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianBoxLabelDtos.java
  9. 206
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianBoxLabelTest.java

6
README.md

@ -141,7 +141,7 @@ sequenceDiagram @@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁 / 箱标) |
依赖方向:
```
@ -384,7 +384,7 @@ common.ecommerce @@ -384,7 +384,7 @@ common.ecommerce
│ HengjianInventoryMapper / HengjianInboundMapper /
│ HengjianInboundQueryMapper / HengjianTransferMapper /
│ HengjianReturnMapper / HengjianReturnQueryMapper /
│ HengjianDestructionMapper
│ HengjianDestructionMapper / HengjianBoxLabelMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
@ -397,7 +397,7 @@ common.ecommerce @@ -397,7 +397,7 @@ common.ecommerce
│ HengjianTransferDtos / HengjianReturnPlanCreateDtos /
│ HengjianReturnDetailDtos / HengjianReturnListDtos /
│ HengjianReturnHandleDtos / HengjianOrderAttachmentDtos /
│ HengjianDestructionDtos
│ HengjianDestructionDtos / HengjianBoxLabelDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter

41
docs-warehouse/hengjian/README.md

@ -92,7 +92,8 @@ @@ -92,7 +92,8 @@
| 30 | 订单上传附件 | `POST /v1/saleOrder/createAttachment` | `OUTBOUND` | ✅ |
| 31 | 销毁计划创建 | `POST /v2/destroyPlanOrder/create`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 |
| 32 | 销毁计划查询 | `POST /v2/destroyPlanOrder/find`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 |
| 33 | 回调 | — | — | ❌ 文档无回调页 |
| 33 | 入库箱标生成 | `POST /v2/inbound/boxLabelGenerate` | `BOX_LABEL` | ✅ |
| 34 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@ -444,7 +445,40 @@ productItems(入库产品明细必须填写) @@ -444,7 +445,40 @@ productItems(入库产品明细必须填写)
**只为这个接口给 core 加的字段**:`documentStatus` / `purchaseOrderNos` / `actualShipDate` /
`goodsType` / `shippingCompanyName` / `containers`。其它仓不读这些字段,行为不变。
**未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。
**未接入**:取消 / 加附件 / 发运 / 预约单,调用显式抛异常。
#### 入库箱标生成(`/v2/inbound/boxLabelGenerate`)
**真机确认的必填项**(空 body 一次性列出全部缺失项):
```
inboundPlanOrderNo(单号不能为空)
type(类型不能为空)
pageSize(每页个数不能为空)
isIndexNo(是否生成数字标不能为空)
isOriginCountry(是否展示原产地不能为空)
```
`paperType`(1 A4 / 2 10×10)与 `fileNamingType`(0 按入库计划名 / 1 按来源单号)选填。
**响应无 data**:只有 `code / message`("生成箱标成功"),
**不回任务号、不回文件**。文件要去入库计划详情的 `packingLabelUrl` 里取。
所以 `LabelPrintTask.taskNo()` 恒为 null——**不代表调用失败**,看有没有抛异常。
**与运去哪口径不同**:
| 统一模型 | 恒健 | 说明 |
|---|---|---|
| `twoCopies` | `type` 1/2 | 恒健是**份数**码,不是布尔 |
| `labelsPerPage` | `pageSize` | 1 或 6,与运去哪同值 |
| `sizeType` / `downloadMode` | — | 恒健没有这两个口径,改用 `paperType` |
**两个开关不允许留空**:`isIndexNo` / `isOriginCountry` 仓方标必填,统一模型是 null-able;
适配器在 null 时**拒绝而不是猜**——猜「是」每箱多印一行,猜「否」漏印。
**为这个接口给 core 改的东西**:
- `BoxLabelCommand` 补 `showIndexNo` / `showOriginCountry` / `paperTypeCode` / `fileNamingType`
- `LabelPrintTask.taskNo` 改为**可空**(恒健不回任务号),Javadoc 说明了 null 的含义
### 销毁(`DESTRUCTION`)—— 已接入,**路径未真机确认**
@ -906,13 +940,14 @@ warehouse-sdk-hengjian/ @@ -906,13 +940,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianReturnQueryTest.java 18 个:两套形态 / 三套码表 / 四项定位 / 处理方式映射
├── adapter/HengjianOrderAttachmentTest.java 12 个:平铺 / 类型整数 / base64 优先 / 本地校验
├── adapter/HengjianDestructionTest.java 16 个:Data 拼写 / 裸数组 / 7 状态 / 无仓单号
├── adapter/HengjianBoxLabelTest.java 11 个:五个必填 / 份数码 / 开关不猜 / 无任务号
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(329 个 + 4 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(340 个 + 4 个跳过)。
## 5. 探针用法

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

@ -26,6 +26,31 @@ public final class BoxLabelCommand { @@ -26,6 +26,31 @@ public final class BoxLabelCommand {
private final boolean twoCopies;
/** 是否展示客户唯一标识符。 */
private final boolean showOrgUniqueCode;
/**
* 是否在箱标上打印序号(数字标)。null 表示由仓方按默认处理。
*
* <p>恒健 {@code isIndexNo}(1 是 / 0 否)<b>标必填</b>;运去哪没有这个开关。</p>
*/
private final Boolean showIndexNo;
/**
* 是否在箱标上展示原产地。null 表示由仓方按默认处理。
*
* <p>恒健 {@code isOriginCountry}(1 是 / 0 否)<b>标必填</b>;运去哪没有这个开关。</p>
*/
private final Boolean showOriginCountry;
/**
* 纸张样式,取值由仓方定义。null 表示不传(仓方默认)。
*
* <p>恒健 {@code paperType}:1 A4 / 2 10×10。与 {@link #sizeType()} 不是同一套口径:
* 那个是标签纸物理尺寸(100×100 之类),这个是 PDF 排版样式。</p>
*/
private final Integer paperTypeCode;
/**
* 文件命名方式,取值由仓方定义。null 表示不传(仓方默认)。
*
* <p>恒健 {@code fileNamingType}:0 按入库计划名 / 1 按来源单号命名。</p>
*/
private final Integer fileNamingType;
private BoxLabelCommand(Builder b) {
this.providerInboundNo = require(b.providerInboundNo, "providerInboundNo");
@ -36,6 +61,10 @@ public final class BoxLabelCommand { @@ -36,6 +61,10 @@ public final class BoxLabelCommand {
requireCompatible(sizeType, labelsPerPage);
this.twoCopies = b.twoCopies;
this.showOrgUniqueCode = b.showOrgUniqueCode;
this.showIndexNo = b.showIndexNo;
this.showOriginCountry = b.showOriginCountry;
this.paperTypeCode = b.paperTypeCode;
this.fileNamingType = b.fileNamingType;
}
public static Builder builder() {
@ -72,6 +101,26 @@ public final class BoxLabelCommand { @@ -72,6 +101,26 @@ public final class BoxLabelCommand {
return showOrgUniqueCode;
}
/** 是否打印序号(数字标);null 表示由仓方默认。 */
public Boolean showIndexNo() {
return showIndexNo;
}
/** 是否展示原产地;null 表示由仓方默认。 */
public Boolean showOriginCountry() {
return showOriginCountry;
}
/** 纸张样式码(仓方口径);null 表示不传。 */
public Integer paperTypeCode() {
return paperTypeCode;
}
/** 文件命名方式码(仓方口径);null 表示不传。 */
public Integer fileNamingType() {
return fileNamingType;
}
/** 尺寸与每页数量必须匹配,否则仓方会拒绝——在构造期就失败,别等下发。 */
private static void requireCompatible(LabelSizeType size, LabelsPerPage perPage) {
if (perPage == LabelsPerPage.ONE && !size.singlePerPage()) {
@ -101,6 +150,10 @@ public final class BoxLabelCommand { @@ -101,6 +150,10 @@ public final class BoxLabelCommand {
private LabelsPerPage labelsPerPage = LabelsPerPage.ONE;
private boolean twoCopies;
private boolean showOrgUniqueCode;
private Boolean showIndexNo;
private Boolean showOriginCountry;
private Integer paperTypeCode;
private Integer fileNamingType;
public Builder providerInboundNo(String v) {
this.providerInboundNo = v;
@ -137,6 +190,30 @@ public final class BoxLabelCommand { @@ -137,6 +190,30 @@ public final class BoxLabelCommand {
return this;
}
/** 是否打印序号(数字标);null 表示由仓方默认。 */
public Builder showIndexNo(Boolean v) {
this.showIndexNo = v;
return this;
}
/** 是否展示原产地;null 表示由仓方默认。 */
public Builder showOriginCountry(Boolean v) {
this.showOriginCountry = v;
return this;
}
/** 纸张样式码(仓方口径);null 表示不传。 */
public Builder paperTypeCode(Integer v) {
this.paperTypeCode = v;
return this;
}
/** 文件命名方式码(仓方口径);null 表示不传。 */
public Builder fileNamingType(Integer v) {
this.fileNamingType = v;
return this;
}
public BoxLabelCommand build() {
return new BoxLabelCommand(this);
}

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

@ -9,6 +9,10 @@ import common.ecommerce.warehouse.enums.WarehouseProvider; @@ -9,6 +9,10 @@ import common.ecommerce.warehouse.enums.WarehouseProvider;
* 另外查任务中心(运去哪 API 99 文档明确「后续可通过调用查询任务中心详情接口获取下载地址」)。</p>
*
* <p>{@link #label()} 在任务已同步完成、仓方直接返回文件时才有值;异步生成的仓恒为 null。</p>
*
* <p><b>{@link #taskNo()} 可能为 null</b>:有的仓(恒健)的箱标接口只回「成功」,
* 不给任务号,文件要回入库计划详情里取。这类仓的 {@code taskNo} 恒为 null,
* 调用方不要拿它当「调用失败」——看有没有抛异常。</p>
*/
public final class LabelPrintTask {
@ -23,7 +27,8 @@ public final class LabelPrintTask { @@ -23,7 +27,8 @@ public final class LabelPrintTask {
private LabelPrintTask(Builder b) {
this.sourceProvider = b.sourceProvider;
this.taskNo = require(b.taskNo, "taskNo");
// taskNo 允许为空:恒健的箱标接口只回成功,不给任务号
this.taskNo = b.taskNo;
this.providerInboundNo = b.providerInboundNo;
this.inboundRequestNo = b.inboundRequestNo;
this.label = b.label;
@ -37,7 +42,12 @@ public final class LabelPrintTask { @@ -37,7 +42,12 @@ public final class LabelPrintTask {
return sourceProvider;
}
/** 任务编号;用它去任务中心查下载地址。 */
/**
* 任务编号;用它去任务中心查下载地址。
*
* <p>为 null 表示仓方没给任务号(恒健),文件要从入库计划详情里取,
* 不代表调用失败。</p>
*/
public String taskNo() {
return taskNo;
}

9
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java

@ -308,6 +308,15 @@ public final class HengjianConstants { @@ -308,6 +308,15 @@ public final class HengjianConstants {
public static final String PATH_DESTRUCTION_FIND = "/v2/destroyPlanOrder/find";
/**
* 入库箱标生成({@code POST})。
*
* <p>真机确认必填:{@code inboundPlanOrderNo} / {@code type} / {@code pageSize} /
* {@code isIndexNo} / {@code isOriginCountry}。响应<b>无 data</b>(只有 message),
* 不回任务号也不回文件——文件从入库计划详情的 {@code packingLabelUrl} 取。</p>
*/
public static final String PATH_INBOUND_BOX_LABEL = "/v2/inbound/boxLabelGenerate";
/**
* {@code btChargeAt} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

30
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -4,6 +4,7 @@ import com.fasterxml.jackson.databind.JsonNode; @@ -4,6 +4,7 @@ import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos;
import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianBoxLabelDtos;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianDestructionDtos;
import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos;
@ -64,6 +65,7 @@ import common.ecommerce.warehouse.error.OutboundCancelBlockedException; @@ -64,6 +65,7 @@ import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.DestructionCommand;
import common.ecommerce.warehouse.model.DestructionOrder;
import common.ecommerce.warehouse.model.CancelResult;
@ -75,6 +77,7 @@ import common.ecommerce.warehouse.model.InboundOrder; @@ -75,6 +77,7 @@ import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundQuery;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryMovement;
import common.ecommerce.warehouse.model.LabelPrintTask;
import common.ecommerce.warehouse.model.InventoryMovementQuery;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
@ -144,6 +147,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -144,6 +147,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_INBOUND_CREATE = "warehouse.inbound.create";
private static final String OP_INBOUND_GET = "warehouse.inbound.get";
private static final String OP_INBOUND_QUERY = "warehouse.inbound.query";
private static final String OP_INBOUND_BOX_LABEL = "warehouse.inbound.boxLabel";
private static final String OP_TRANSFER_CREATE = "warehouse.transfer.create";
private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query";
private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel";
@ -192,6 +196,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -192,6 +196,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.TRACKING_CHANGE,
WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.INBOUND,
WarehouseCapability.BOX_LABEL,
WarehouseCapability.TRANSFER,
WarehouseCapability.RETURN,
WarehouseCapability.DESTRUCTION,
@ -524,6 +529,31 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -524,6 +529,31 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
}
/**
* 生成入库箱标({@code POST /v2/inbound/boxLabelGenerate})。
*
* <p>响应<b>没有任务号也没有文件</b>:只有 {@code code / message}。
* 文件要从入库计划详情的 {@code packingLabelUrl} 取,所以返回的
* {@link LabelPrintTask#taskNo()} 为 null——<b>不代表调用失败</b>。</p>
*
* <p>恒健要求 {@code isIndexNo} / {@code isOriginCountry} 必填,统一模型里是
* null-able;没给时本地拒绝而不是猜一个值(猜错会多印或漏印一行)。</p>
*
* <p>尺寸 / 每页数量的联动约束由 {@link BoxLabelCommand} 构造期校验;
* 恒健没有 {@code sizeType} / {@code downloadMode} 口径,改用 {@code paperType}。</p>
*/
@Override
public LabelPrintTask printBoxLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
String fallback = trimToNull(ctx.providerWarehouseId());
if (fallback == null) {
fallback = trimToNull(cmd.inboundRequestNo());
}
HengjianBoxLabelDtos.BoxLabelRequest body =
HengjianBoxLabelMapper.toRequest(cmd, fallback);
execute(ctx, HengjianConstants.PATH_INBOUND_BOX_LABEL, body, OP_INBOUND_BOX_LABEL);
return HengjianBoxLabelMapper.toTask(cmd, fallback);
}
/**
* 按游标分页查入库单。
*
* <p>统一模型这个入口只有一个游标,恒健的列表接口支持多条件;这里把游标当页码,

103
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianBoxLabelMapper.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianBoxLabelDtos;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.LabelPrintTask;
/**
* 恒健入库箱标映射({@code POST /v2/inbound/boxLabelGenerate})。
*
* <h2>真机确认的必填项</h2>
* <p>{@code inboundPlanOrderNo} / {@code type} / {@code pageSize} / {@code isIndexNo} /
* {@code isOriginCountry}——五项缺一不可,空 body 时仓方一次性列出所有缺失项。</p>
*
* <h2>响应没有任务号</h2>
* <p>只有 {@code code / message}(「生成箱标成功」),<b>不回任务号也不回文件</b>。
* 文件要从入库计划详情({@code getInboundPlanInfo})的 {@code packingLabelUrl} 里取。
* 所以 {@link LabelPrintTask#taskNo()} 恒为 null——不代表调用失败。</p>
*
* <h2>与运去哪字段口径不同</h2>
* <table border="1">
* <tr><th>统一模型</th><th>恒健</th><th>说明</th></tr>
* <tr><td>{@code twoCopies}</td><td>{@code type} 1/2</td>
* <td>恒健是<b>份数</b>码(1 一式一份 / 2 一式两份),不是布尔</td></tr>
* <tr><td>{@code labelsPerPage}</td><td>{@code pageSize}</td>
* <td>1 或 6;与运去哪同值</td></tr>
* <tr><td>{@code sizeType} / {@code downloadMode}</td><td>—</td>
* <td>恒健没有这两个口径,改用 {@code paperType}(1 A4 / 2 10×10)</td></tr>
* </table>
*/
public final class HengjianBoxLabelMapper {
/** 打印份数:一式一份。 */
static final int COPIES_ONE = 1;
/** 打印份数:一式两份。 */
static final int COPIES_TWO = 2;
private HengjianBoxLabelMapper() {
}
/**
* 统一命令 → 恒健请求。
*
* <p>{@code showIndexNo} / {@code showOriginCountry} 在统一模型里是 null-able,
* 但恒健<b>标必填</b>——没给时拒绝而不是替调用方猜一个值:
* 猜「是」会让每箱多印一行,猜「否」会漏印。</p>
*
* @param cmd 统一命令
* @param fallbackNo 命令里没给仓单号时的回退值(账户仓 id 或来源单号)
* @throws IllegalArgumentException 缺必填开关
*/
public static HengjianBoxLabelDtos.BoxLabelRequest toRequest(BoxLabelCommand cmd,
String fallbackNo) {
String planNo = firstNonBlank(cmd.providerInboundNo(), fallbackNo);
if (planNo == null) {
throw new IllegalArgumentException(
"hengjian box label requires inboundPlanOrderNo; none given and account has none");
}
if (cmd.showIndexNo() == null) {
throw new IllegalArgumentException(
"hengjian box label requires showIndexNo (1 是 / 0 否,仓方必填);"
+ "给 null 会让每箱是否印序号变成猜的");
}
if (cmd.showOriginCountry() == null) {
throw new IllegalArgumentException(
"hengjian box label requires showOriginCountry (1 是 / 0 否,仓方必填)");
}
HengjianBoxLabelDtos.BoxLabelRequest req = new HengjianBoxLabelDtos.BoxLabelRequest();
req.inboundPlanOrderNo = planNo;
req.type = cmd.twoCopies() ? COPIES_TWO : COPIES_ONE;
req.pageSize = cmd.labelsPerPage().count();
req.isIndexNo = cmd.showIndexNo() ? 1 : 0;
req.isOriginCountry = cmd.showOriginCountry() ? 1 : 0;
req.paperType = cmd.paperTypeCode();
req.fileNamingType = cmd.fileNamingType();
return req;
}
/**
* 响应 → 任务。
*
* <p>恒健只回成功,没有任务号也没有文件——两者都留 null,不编。</p>
*/
public static LabelPrintTask toTask(BoxLabelCommand cmd, String fallbackNo) {
return LabelPrintTask.builder()
.sourceProvider(WarehouseProvider.HENGJIAN)
// taskNo 为 null:恒健不回任务号,文件从入库计划详情的 packingLabelUrl 取
.providerInboundNo(firstNonBlank(cmd.providerInboundNo(), fallbackNo))
.inboundRequestNo(cmd.inboundRequestNo())
.build();
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
if (b != null && !b.trim().isEmpty()) {
return b.trim();
}
return null;
}
}

56
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianBoxLabelDtos.java

@ -0,0 +1,56 @@ @@ -0,0 +1,56 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 恒健报文结构:入库箱标生成({@code POST /v2/inbound/boxLabelGenerate})。
*
* <p><b>真机确认的必填项</b>(空 body 触发的校验信息):</p>
* <pre>
* inboundPlanOrderNo(单号不能为空)
* type(类型不能为空)
* pageSize(每页个数不能为空)
* isIndexNo(是否生成数字标不能为空)
* isOriginCountry(是否展示原产地不能为空)
* </pre>
* <p>{@code paperType} / {@code fileNamingType} 选填。</p>
*
* <p><b>响应无 data</b>:只有 {@code code / message},<b>不回任务号、不回文件</b>。</p>
*/
public final class HengjianBoxLabelDtos {
private HengjianBoxLabelDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BoxLabelRequest {
/** 入库计划单号;必填。 */
public String inboundPlanOrderNo;
/** 打印份数:1 一式一份 / 2 一式两份;必填。 */
public Integer type;
/** 每页箱标个数:1 或 6;必填。 */
public Integer pageSize;
/** 是否生成数字标:1 是 / 0 否;必填。 */
public Integer isIndexNo;
/** 是否展示原产地:1 是 / 0 否;必填。 */
public Integer isOriginCountry;
/** PDF 样式:1 A4 / 2 10×10;不填默认 1(A4)。 */
public Integer paperType;
/** 文件命名类型:0 按入库计划名 / 1 按来源单号命名;不填默认 0。 */
public Integer fileNamingType;
}
/** 响应:无 data。 */
public static final class BoxLabelResponse {
public Integer code;
public String message;
}
}

206
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianBoxLabelTest.java

@ -0,0 +1,206 @@ @@ -0,0 +1,206 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
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.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 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.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 入库箱标生成({@code /v2/inbound/boxLabelGenerate})契约测试。
*/
class HengjianBoxLabelTest {
private static final WarehouseContext CTX = WarehouseContext.of(
"HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC));
private static final String OK_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"生成箱标成功\"}";
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static RecordingTransport generating() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_INBOUND_BOX_LABEL, req -> Responses.ok(OK_BODY));
}
private static BoxLabelCommand.Builder command() {
return BoxLabelCommand.builder()
.providerInboundNo("IP26052500012")
.inboundRequestNo("IB-1")
.sizeType(LabelSizeType.SIZE_100_100)
.labelsPerPage(LabelsPerPage.ONE)
.showIndexNo(true)
.showOriginCountry(true);
}
// ---------------------------------------------------------------- 请求形状
@Test
void postsToBoxLabelGenerate() {
RecordingTransport transport = generating();
adapter(transport).printBoxLabel(CTX, command().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/inbound/boxLabelGenerate",
transport.lastDataRequest().url());
}
/** 真机确认的五个必填项都要出现。 */
@Test
void sendsMandatoryFields() {
RecordingTransport transport = generating();
adapter(transport).printBoxLabel(CTX, command().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"inboundPlanOrderNo", "type", "pageSize",
"isIndexNo", "isOriginCountry"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
assertTrue(body.contains("\"inboundPlanOrderNo\":\"IP26052500012\""), body);
}
/** 份数:twoCopies → type 1/2(恒健是份数码,不是布尔)。 */
@Test
void twoCopiesMapsToTypeOneOrTwo() {
RecordingTransport one = generating();
adapter(one).printBoxLabel(CTX, command().twoCopies(false).build());
assertTrue(one.lastDataRequest().body().contains("\"type\":1"));
RecordingTransport two = generating();
adapter(two).printBoxLabel(CTX, command().twoCopies(true).build());
assertTrue(two.lastDataRequest().body().contains("\"type\":2"));
}
/** 每页数量 1 / 6 直接下发。 */
@Test
void labelsPerPageMapsToPageSize() {
RecordingTransport one = generating();
adapter(one).printBoxLabel(CTX, command().labelsPerPage(LabelsPerPage.ONE).build());
assertTrue(one.lastDataRequest().body().contains("\"pageSize\":1"));
RecordingTransport six = generating();
adapter(six).printBoxLabel(CTX, command()
.labelsPerPage(LabelsPerPage.SIX).sizeType(LabelSizeType.SIZE_104_98).build());
assertTrue(six.lastDataRequest().body().contains("\"pageSize\":6"));
}
/** 开关:1 是 / 0 否。 */
@Test
void booleanFlagsMapToOneZero() {
RecordingTransport transport = generating();
adapter(transport).printBoxLabel(CTX, command()
.showIndexNo(false).showOriginCountry(true).build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"isIndexNo\":0"), body);
assertTrue(body.contains("\"isOriginCountry\":1"), body);
}
/** 选填的 paperType / fileNamingType 给了才发。 */
@Test
void optionalFieldsOnlyWhenGiven() {
RecordingTransport absent = generating();
adapter(absent).printBoxLabel(CTX, command().build());
assertFalse(absent.lastDataRequest().body().contains("paperType"));
assertFalse(absent.lastDataRequest().body().contains("fileNamingType"));
RecordingTransport present = generating();
adapter(present).printBoxLabel(CTX, command()
.paperTypeCode(1).fileNamingType(1).build());
String body = present.lastDataRequest().body();
assertTrue(body.contains("\"paperType\":1"), body);
assertTrue(body.contains("\"fileNamingType\":1"), body);
}
// ---------------------------------------------------------------- 本地校验
/** 仓方必填的两个开关没给时拒绝,不猜(猜错会多印或漏印一行)。 */
@Test
void rejectsMissingRequiredFlags() {
RecordingTransport transport = generating();
HengjianAdapter adapter = adapter(transport);
IllegalArgumentException noIndex = assertThrows(IllegalArgumentException.class,
() -> adapter.printBoxLabel(CTX, BoxLabelCommand.builder()
.providerInboundNo("IP1").inboundRequestNo("IB-1")
.showOriginCountry(true).build()));
assertTrue(noIndex.getMessage().contains("showIndexNo"), noIndex.getMessage());
IllegalArgumentException noOrigin = assertThrows(IllegalArgumentException.class,
() -> adapter.printBoxLabel(CTX, BoxLabelCommand.builder()
.providerInboundNo("IP1").inboundRequestNo("IB-1")
.showIndexNo(true).build()));
assertTrue(noOrigin.getMessage().contains("showOriginCountry"), noOrigin.getMessage());
assertTrue(transport.dataRequests().isEmpty());
}
/** 尺寸 / 每页数量的联动约束在 BoxLabelCommand 构造期已挡。 */
@Test
void commandRejectsIncompatibleSizeAndPerPage() {
assertThrows(IllegalArgumentException.class, () -> BoxLabelCommand.builder()
.providerInboundNo("IP1").inboundRequestNo("IB-1")
.sizeType(LabelSizeType.SIZE_104_98).labelsPerPage(LabelsPerPage.ONE)
.showIndexNo(true).showOriginCountry(true).build());
}
// ---------------------------------------------------------------- 响应
/** 恒健不回任务号:taskNo 为 null,不代表失败。 */
@Test
void taskHasNoTaskNo() {
LabelPrintTask task = adapter(generating()).printBoxLabel(CTX, command().build());
assertNull(task.taskNo(), "恒健不回任务号,文件从入库计划详情的 packingLabelUrl 取");
assertNull(task.label(), "同步也没有文件");
assertEquals("IP26052500012", task.providerInboundNo());
assertEquals("IB-1", task.inboundRequestNo());
assertEquals(WarehouseProvider.HENGJIAN, task.sourceProvider());
}
@Test
void businessErrorIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_INBOUND_BOX_LABEL, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"生成箱标失败\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).printBoxLabel(CTX, command().build()));
assertTrue(ex.getMessage().contains("生成箱标失败"), ex.getMessage());
}
// ---------------------------------------------------------------- 能力位
@Test
void declaresBoxLabelCapability() {
assertTrue(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.BOX_LABEL));
}
}
Loading…
Cancel
Save