Browse Source
真机确认必填五项: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
9 changed files with 534 additions and 8 deletions
@ -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; |
||||||
|
} |
||||||
|
} |
||||||
@ -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; |
||||||
|
} |
||||||
|
} |
||||||
@ -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…
Reference in new issue