From 70ae09d7c81e6c17a962c3a9da99892476b893c4 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Mon, 16 Nov 2026 15:21:25 +0800 Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E5=85=A5?= =?UTF-8?q?=E5=BA=93=E8=AE=A1=E5=88=92=E5=88=9B=E5=BB=BA=20/v1/inbound/cre?= =?UTF-8?q?ateInboundPlan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 HengjianInboundCreateDtos + HengjianInboundMapper,实现 InboundCapable.create,声明 INBOUND - 真机确认必填 orderNo / warehouseCode / inventoryType / productItems; 文档标必填的 currency 真机不校验,按选填实现 - 响应不回仓单号(只有 code/message),providerInboundId 保持 null, 不拿来源单号顶替 - 柜型按恒健的四个独立字段映射(20GP/40GP/40HQ/45HQ + 各自箱号); 认不出的柜型直接拒绝,静默丢弃等于少报柜数 - 装箱信息映射 cartonItems(尺寸 cm / 重量 g),空则不传 - 入库查询 / 分页未接,显式抛异常而非返回 null - core InboundCommand 补 6 个恒健协议字段(documentStatus / purchaseOrderNos / actualShipDate / goodsType / shippingCompanyName / containers), 其它仓不读,行为不变 验证:mvn test 全量通过,恒健 220 个用例(+17)通过。 Co-Authored-By: Claude Code --- README.md | 7 +- docs-warehouse/hengjian/README.md | 52 +++- .../ecommerce/warehouse/model/InboundCommand.java | 146 +++++++++++ .../ecommerce/hengjian/HengjianConstants.java | 8 + .../hengjian/adapter/HengjianAdapter.java | 57 ++++- .../hengjian/adapter/HengjianInboundMapper.java | 210 ++++++++++++++++ .../hengjian/dto/HengjianInboundCreateDtos.java | 164 +++++++++++++ .../hengjian/adapter/HengjianAdapterTest.java | 17 +- .../hengjian/adapter/HengjianCreateOrderTest.java | 4 +- .../hengjian/adapter/HengjianDirectoryTest.java | 5 +- .../adapter/HengjianInboundCreateTest.java | 273 +++++++++++++++++++++ 11 files changed, 928 insertions(+), 15 deletions(-) create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundMapper.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundCreateDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundCreateTest.java diff --git a/README.md b/README.md index 36b8902..1cb3058 100644 --- a/README.md +++ b/README.md @@ -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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建) | 依赖方向: ``` @@ -381,7 +381,7 @@ common.ecommerce │ HengjianProductMapper / HengjianOutboundMapper / │ HengjianOrderMapper / HengjianTrackingChangeMapper / │ HengjianFeeMapper / HengjianEstimateMapper / - │ HengjianInventoryMapper + │ HengjianInventoryMapper / HengjianInboundMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / @@ -389,7 +389,8 @@ common.ecommerce │ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos / │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos / │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos / - │ HengjianInventoryDtos / HengjianInventoryMovementDtos + │ HengjianInventoryDtos / HengjianInventoryMovementDtos / + │ HengjianInboundCreateDtos ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); │ 其余状态枚举约定见 package-info,待建 ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 75a485d..d8abb73 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -78,7 +78,8 @@ | 16 | 按 SKU 查库存 | `POST /v1/inventory/getInventory` | `INVENTORY_QUERY` | ✅ | | 17 | 批量查库存(分页) | `GET /v2/inventory/get_inventory_by_page` | `INVENTORY_QUERY` | ✅ | | 18 | 库存变动流水 | `POST /v1/inventory/task/query` | `INVENTORY_QUERY` | ✅ | -| 19 | 回调 | — | — | ❌ 文档无回调页 | +| 19 | 入库计划创建 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | ✅ | +| 20 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -375,6 +376,49 @@ 入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标, 预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。 +### 入库计划创建(`/v1/inbound/createInboundPlan`)—— 已接入 + +**真机确认的必填项**(空 body 触发的校验信息): + +``` +orderNo(订单号必须填写) +warehouseCode(仓库必须填写) +inventoryType(库存类型必须填写) +productItems(入库产品明细必须填写) +``` + +**文档标必填、真机不校验的**:`currency`(文档说「默认 USD」,真机不传也能过校验, +只会在鉴权处停下)。按选填实现,不传由仓方按 USD 处理。 + +**响应不回仓单号**:只有 `code / message`。所以 `InboundReceipt.providerInboundId` 为 null, +**不拿来源单号顶替**——后续查详情 / 取消只能用 `orderNo`(来源单号)。 + +**草稿语义**:`status=0` 是草稿,草稿状态下再调本接口是**更新**而非新建。 +由调用方经 `InboundCommand.documentStatus()` 决定,适配器不猜。 + +**柜型映射**:恒健把 20GP / 40GP / 40HQ / 45HQ 拆成独立字段 +(`gpQuantity20` / `gpQuantity40` / `hqQuantity40` / `hqQuantity45` + 各自箱号)。 +统一模型用 `InboundCommand.Container(柜型, 数量, 箱号)` 表达;**认不出的柜型直接拒绝** +——静默丢弃等于少报柜数。 + +**其它字段映射**: + +| 恒健 | 统一模型 | +|---|---| +| `lineCode` | `lineName`(项目名称) | +| `batchNumber` | `factoryBatchNo` | +| `poNos` | `purchaseOrderNos`(逗号分隔) | +| `shippingCompany` | `shippingCompanyName`(**名称**,与信仓的 `shippingCompanyId` 不同) | +| `goodsType`(2 集装箱 / 4 卡车) | `goodsType`(**不是** `containerSize` 也不是 `deliveryType`) | +| `actualShipDate` / `estimateArriveTime` / `expectArriveDate` / `predictionShipDate` | 同名日期,`yyyy-MM-dd` | +| `cartonItems` | `InboundCarton` 列表(外箱尺寸 cm / 重量 g) | +| `tmsNo` | `transportOrderNos` 逗号拼接 | + +**只为这个接口给 core 加的字段**:`documentStatus` / `purchaseOrderNos` / `actualShipDate` / +`goodsType` / `shippingCompanyName` / `containers`。其它仓不读这些字段,行为不变。 + +**未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。 + ### 库存(`INVENTORY_QUERY`)—— 已接入 恒健有**两个**库存接口,能力不同,统一模型只有一个 `query()`,按「给了什么」分流: @@ -525,7 +569,8 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型 │ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射 │ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射 - │ │ └── HengjianInventoryMapper.java 库存两个接口 + 变动流水 + │ │ ├── HengjianInventoryMapper.java 库存两个接口 + 变动流水 + │ │ └── HengjianInboundMapper.java 入库计划创建 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -557,13 +602,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过 ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射 ├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射 + ├── adapter/HengjianInboundCreateTest.java 17 个:必填 / 柜型 / 装箱 / 无仓单号 ├── 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` 全部通过(203 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(220 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java index 78c76b6..33d2d52 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java @@ -143,6 +143,32 @@ public final class InboundCommand { */ private final Integer referenceSkuCount; + // ---- 恒健入库计划协议字段(其它仓不用)---- + + /** + * 单据状态:0 草稿 / 5 提交。null 表示由仓方按默认(提交)处理。 + * + *

恒健 {@code status}:草稿状态可再次调用创建接口做更新。

+ */ + private final Integer documentStatus; + /** Amazon 货件的 reference id;恒健 {@code referenceId}。 */ + // referenceId 已在上文存在(通用字段),不重复定义 + /** 采购单号(多个用逗号分隔);恒健 {@code poNos}。 */ + private final String purchaseOrderNos; + /** 实际发运日期(自动发运时必填);恒健 {@code actualShipDate}。 */ + private final java.time.LocalDate actualShipDate; + /** + * 货物类型:2 集装箱 / 4 卡车(自动发运时必填);恒健 {@code goodsType}。 + * + *

与 {@link #containerSize()}(柜型 20GP/40HQ…)和 {@link #deliveryType()} + * 都不是一回事:这里是「集装箱 vs 卡车」。

+ */ + private final Integer goodsType; + /** 船运公司名称;恒健 {@code shippingCompany}(与信仓的 shippingCompanyId 不同)。 */ + private final String shippingCompanyName; + /** 各规格集装箱数量与箱号。 */ + private final List containers; + private InboundCommand(Builder b) { if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("inboundRequestNo must not be blank"); @@ -199,6 +225,13 @@ public final class InboundCommand { this.oversizeNote = b.oversizeNote; this.chnName = b.chnName; this.referenceSkuCount = b.referenceSkuCount; + this.documentStatus = b.documentStatus; + this.purchaseOrderNos = b.purchaseOrderNos; + this.actualShipDate = b.actualShipDate; + this.goodsType = b.goodsType; + this.shippingCompanyName = b.shippingCompanyName; + this.containers = java.util.Collections.unmodifiableList( + new java.util.ArrayList(b.containers)); } public static Builder builder() { @@ -392,6 +425,75 @@ public final class InboundCommand { return referenceSkuCount; } + /** 单据状态:0 草稿 / 5 提交;null 表示由仓方默认。 */ + public Integer documentStatus() { + return documentStatus; + } + + /** 采购单号(逗号分隔);null 表示不传。 */ + public String purchaseOrderNos() { + return purchaseOrderNos; + } + + /** 实际发运日期;null 表示不传。 */ + public java.time.LocalDate actualShipDate() { + return actualShipDate; + } + + /** 货物类型:2 集装箱 / 4 卡车;null 表示不传。 */ + public Integer goodsType() { + return goodsType; + } + + /** 船运公司名称;null 表示不传。 */ + public String shippingCompanyName() { + return shippingCompanyName; + } + + /** 各规格集装箱数量与箱号;不可变,空表示不传。 */ + public List containers() { + return containers; + } + + /** + * 一种规格的集装箱(数量 + 箱号)。 + * + *

恒健把 20GP / 40GP / 40HQ / 45HQ 拆成独立字段,各要数量与箱号。 + * 用「规格 + 数量 + 箱号」表达,适配器按规格映射到对应字段。

+ */ + public static final class Container { + + /** 柜型,取值由仓方定义(恒健与信仓的 cabinetType 同义:20GP / 40GP / 40HQ / 45HQ)。 */ + private final String containerType; + private final int quantity; + /** 集装箱号;null 表示不传。 */ + private final String containerNo; + + public Container(String containerType, int quantity, String containerNo) { + if (containerType == null || containerType.trim().isEmpty()) { + throw new IllegalArgumentException("containerType must not be blank"); + } + if (quantity <= 0) { + throw new IllegalArgumentException("container quantity must be positive"); + } + this.containerType = containerType.trim(); + this.quantity = quantity; + this.containerNo = containerNo; + } + + public String containerType() { + return containerType; + } + + public int quantity() { + return quantity; + } + + public String containerNo() { + return containerNo; + } + } + public static final class Builder { private String inboundRequestNo; @@ -434,6 +536,12 @@ public final class InboundCommand { private String oversizeNote; private String chnName; private Integer referenceSkuCount; + private Integer documentStatus; + private String purchaseOrderNos; + private java.time.LocalDate actualShipDate; + private Integer goodsType; + private String shippingCompanyName; + private final List containers = new ArrayList(); public Builder inboundRequestNo(String v) { this.inboundRequestNo = v; @@ -654,6 +762,44 @@ public final class InboundCommand { return this; } + /** 单据状态:0 草稿 / 5 提交;null 由仓方默认。 */ + public Builder documentStatus(Integer v) { + this.documentStatus = v; + return this; + } + + /** 采购单号(逗号分隔)。 */ + public Builder purchaseOrderNos(String v) { + this.purchaseOrderNos = v; + return this; + } + + /** 实际发运日期。 */ + public Builder actualShipDate(java.time.LocalDate v) { + this.actualShipDate = v; + return this; + } + + /** 货物类型:2 集装箱 / 4 卡车。 */ + public Builder goodsType(Integer v) { + this.goodsType = v; + return this; + } + + /** 船运公司名称。 */ + public Builder shippingCompanyName(String v) { + this.shippingCompanyName = v; + return this; + } + + /** 追加一个集装箱规格。 */ + public Builder container(Container v) { + if (v != null) { + this.containers.add(v); + } + return this; + } + public InboundCommand build() { return new InboundCommand(this); } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index 7b8d55c..e7bcb20 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -195,6 +195,14 @@ public final class HengjianConstants { public static final int INVENTORY_MOVEMENT_MAX_DAYS = 30; /** + * 入库计划创建({@code POST})。 + * + *

真机确认必填:{@code orderNo} / {@code warehouseCode} / {@code inventoryType} / + * {@code productItems}。响应不回仓单号。

+ */ + public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; + + /** * {@code btChargeAt} 的日期区间分隔符。 * *

文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。

diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 1efa93b..6f9f083 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -7,6 +7,7 @@ import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos; import common.ecommerce.hengjian.dto.HengjianInventoryDtos; +import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; @@ -28,6 +29,7 @@ import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.AddressClassificationCapable; +import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; @@ -54,6 +56,9 @@ import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeEstimateResult; import common.ecommerce.warehouse.model.FeeQuery; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryMovement; import common.ecommerce.warehouse.model.InventoryMovementQuery; import common.ecommerce.warehouse.model.InventoryQuery; @@ -92,7 +97,8 @@ import java.util.Map; */ public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, - WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable { + WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable, + InboundCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; @@ -111,6 +117,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_ADDRESS_CLASSIFY = "warehouse.address.classify"; private static final String OP_INVENTORY_QUERY = "warehouse.inventory.query"; private static final String OP_INVENTORY_MOVEMENTS = "warehouse.inventory.movements"; + private static final String OP_INBOUND_CREATE = "warehouse.inbound.create"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -144,6 +151,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.TRACKING_CHANGE, WarehouseCapability.INVENTORY_QUERY, + WarehouseCapability.INBOUND, WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.ADDRESS_CLASSIFICATION, @@ -151,6 +159,53 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 入库 + + /** + * 创建入库计划({@code POST /v1/inbound/createInboundPlan})。 + * + *

承接门面的幂等守卫(键 {@code warehouseCode + inboundRequestNo + create})。

+ * + *

响应不回仓单号:只有 {@code code / message}。所以 + * {@code providerInboundId} 为 null——后续查详情 / 取消只能用来源单号。 + * 这里不把来源单号冒充仓单号填进去。

+ * + *

{@code status=0} 是草稿,草稿状态下再调本接口是更新而非新建。 + * 由调用方经 {@code InboundCommand.documentStatus()} 决定,适配器不猜。

+ */ + @Override + public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { + String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( + cmd.warehouseId(), ctx.providerWarehouseId()); + HengjianInboundCreateDtos.CreateRequest body = + HengjianInboundMapper.toRequest(cmd, warehouseCode); + execute(ctx, HengjianConstants.PATH_INBOUND_CREATE, body, OP_INBOUND_CREATE); + // 仓方不回单号:保持 null,不拿来源单号顶替 + return InboundReceipt.of(cmd.inboundRequestNo(), null); + } + + /** 入库查询未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + @Override + public InboundOrder get(WarehouseContext ctx, String inboundRef) { + throw unsupportedInbound("warehouse.inbound.get", ctx); + } + + @Override + public Page query(WarehouseContext ctx, String cursor) { + throw unsupportedInbound("warehouse.inbound.query", ctx); + } + + private WarehouseException unsupportedInbound(String operation, WarehouseContext ctx) { + return WarehouseException.builder() + .message("hengjian does not implement " + operation + " yet") + .operation(operation) + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .build(); + } + // ------------------------------------------------------------------ 库存 /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundMapper.java new file mode 100644 index 0000000..b24e9c4 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundMapper.java @@ -0,0 +1,210 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.model.InboundCarton; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; + +/** + * 恒健入库计划报文映射({@code POST /v1/inbound/createInboundPlan})。 + * + *

真机确认的必填项

+ *

{@code orderNo} / {@code warehouseCode} / {@code inventoryType} / {@code productItems}。 + * 文档还标了 {@code currency},但真机校验里没有它,按选填实现。

+ * + *

响应不回仓单号

+ *

只有 {@code code / message},所以 {@code InboundReceipt.providerInboundId} 为 null。 + * 后续查详情 / 取消只能用来源单号({@code orderNo})。

+ * + *

柜型映射

+ *

恒健把四种柜型拆成独立字段({@code gpQuantity20} / {@code gpQuantity40} / + * {@code hqQuantity40} / {@code hqQuantity45} + 各自的箱号)。 + * 统一模型的 {@code InboundCommand.Container} 用「柜型 + 数量 + 箱号」表达, + * 这里按柜型名映射;认不出的柜型直接拒绝——静默丢弃等于少报柜数。

+ */ +public final class HengjianInboundMapper { + + /** 柜型的可识别写法(大小写不敏感)。 */ + private static final String GP20 = "20GP"; + private static final String GP40 = "40GP"; + private static final String HQ40 = "40HQ"; + private static final String HQ45 = "45HQ"; + + private HengjianInboundMapper() { + } + + /** + * 统一命令 → 恒健创建请求。 + * + * @param warehouseCode 仓 code(命令显式指定优先,其次账户配置) + * @throws IllegalArgumentException 缺必填项,或柜型无法识别 + */ + public static HengjianInboundCreateDtos.CreateRequest toRequest(InboundCommand cmd, + String warehouseCode) { + if (cmd.lines().isEmpty()) { + throw new IllegalArgumentException( + "hengjian inbound plan requires at least one product line"); + } + String orderNo = requireText(cmd.inboundRequestNo(), "inboundRequestNo"); + String wh = requireText(warehouseCode, "warehouseCode"); + + HengjianInboundCreateDtos.CreateRequest req = new HengjianInboundCreateDtos.CreateRequest(); + req.orderNo = orderNo; + req.warehouseCode = wh; + req.inventoryType = cmd.inventoryType(); + req.status = cmd.documentStatus(); + req.lineCode = trimToNull(cmd.lineName()); + req.batchNumber = trimToNull(cmd.factoryBatchNo()); + req.currency = trimToNull(cmd.currency()); + req.shipmentId = trimToNull(cmd.shipmentId()); + req.referenceId = trimToNull(cmd.referenceId()); + req.estimateArriveTime = dateOf(cmd.estimateArriveDate()); + req.predictionShipDate = dateOf(cmd.predictionShipDate()); + req.expectArriveDate = dateOf(cmd.expectArriveDate()); + req.shipperName = trimToNull(cmd.shipperName()); + req.shipperAddress = trimToNull(cmd.shipperAddress()); + req.shipperContact = trimToNull(cmd.shipperContact()); + req.shipperPhone = trimToNull(cmd.shipperPhone()); + req.remark = trimToNull(cmd.remark()); + req.originCountry = trimToNull(cmd.originCountry()); + req.poNos = trimToNull(cmd.purchaseOrderNos()); + req.actualShipDate = dateOf(cmd.actualShipDate()); + req.shippingCompany = trimToNull(cmd.shippingCompanyName()); + req.goodsType = cmd.goodsType(); + // tmsNo 是单值;统一模型是列表,多个时用逗号拼(文档没写分隔符,按逗号约定) + if (!cmd.transportOrderNos().isEmpty()) { + req.tmsNo = join(cmd.transportOrderNos()); + } + + req.productItems = toProductItems(cmd.lines()); + req.cartonItems = toCartonItems(cmd.cartons()); + applyContainers(req, cmd.containers()); + return req; + } + + private static List toProductItems( + List lines) { + List out = + new ArrayList(lines.size()); + for (InboundLine line : lines) { + HengjianInboundCreateDtos.CreateRequest.ProductItem item = + new HengjianInboundCreateDtos.CreateRequest.ProductItem(); + item.sku = skuOf(line); + item.qty = line.quantity(); + Money cost = line.cost(); + if (cost != null) { + item.cost = cost.amount().doubleValue(); + } + out.add(item); + } + return out; + } + + private static List toCartonItems( + List cartons) { + if (cartons == null || cartons.isEmpty()) { + return null; + } + List out = + new ArrayList(cartons.size()); + for (InboundCarton carton : cartons) { + HengjianInboundCreateDtos.CreateRequest.CartonItem item = + new HengjianInboundCreateDtos.CreateRequest.CartonItem(); + item.sku = trimToNull(carton.providerSku()); + item.qty = carton.quantity() > 0 ? carton.quantity() : null; + item.cartonQty = carton.cartonQuantity() > 0 ? carton.cartonQuantity() : null; + item.cartonNo = trimToNull(carton.cartonNo()); + item.cartonWeight = positiveOrNull(carton.weightGrams()); + item.cartonLength = positiveOrNull(carton.lengthCm()); + item.cartonWidth = positiveOrNull(carton.widthCm()); + item.cartonHeight = positiveOrNull(carton.heightCm()); + out.add(item); + } + return out; + } + + /** 柜型 → 恒健的四个独立字段;认不出的柜型直接拒绝。 */ + static void applyContainers(HengjianInboundCreateDtos.CreateRequest req, + List containers) { + if (containers == null || containers.isEmpty()) { + return; + } + for (InboundCommand.Container container : containers) { + String type = container.containerType().trim().toUpperCase(Locale.ROOT).replace(" ", ""); + switch (type) { + case GP20: + req.gpQuantity20 = container.quantity(); + req.gpCartonNo20 = trimToNull(container.containerNo()); + break; + case GP40: + req.gpQuantity40 = container.quantity(); + req.gpCartonNo40 = trimToNull(container.containerNo()); + break; + case HQ40: + req.hqQuantity40 = container.quantity(); + req.hqCartonNo40 = trimToNull(container.containerNo()); + break; + case HQ45: + req.hqQuantity45 = container.quantity(); + req.hqCartonNo45 = trimToNull(container.containerNo()); + break; + default: + // 认不出就拒绝:静默丢弃等于少报柜数 + throw new IllegalArgumentException( + "hengjian inbound supports container types 20GP / 40GP / 40HQ / 45HQ, got " + + container.containerType()); + } + } + } + + /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */ + static String skuOf(InboundLine line) { + String provider = trimToNull(line.providerSku()); + return provider != null ? provider : line.omsSku(); + } + + private static String dateOf(LocalDate date) { + return date == null ? null : date.toString(); + } + + private static Double positiveOrNull(double v) { + return v > 0 ? v : null; + } + + private static String join(List values) { + StringBuilder sb = new StringBuilder(); + for (String v : values) { + String t = trimToNull(v); + if (t == null) { + continue; + } + if (sb.length() > 0) { + sb.append(','); + } + sb.append(t); + } + return sb.length() == 0 ? null : sb.toString(); + } + + private static String requireText(String value, String field) { + String v = trimToNull(value); + if (v == null) { + throw new IllegalArgumentException("hengjian inbound plan requires " + field); + } + return v; + } + + private static String trimToNull(String v) { + if (v == null) { + return null; + } + String t = v.trim(); + return t.isEmpty() ? null : t; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundCreateDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundCreateDtos.java new file mode 100644 index 0000000..98b8d9f --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundCreateDtos.java @@ -0,0 +1,164 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.util.List; + +/** + * 恒健报文结构:入库计划创建({@code POST /v1/inbound/createInboundPlan})。 + * + *

真机确认的必填项(空 body 触发的校验信息):

+ *
+ * orderNo(订单号必须填写)
+ * warehouseCode(仓库必须填写)
+ * inventoryType(库存类型必须填写)
+ * productItems(入库产品明细必须填写)
+ * 
+ *

{@code currency} 文档标必填,但真机校验里没有它(不传也能过校验, + * 只会在鉴权处停下)——按选填实现,不传由仓方按 USD 处理。

+ * + *

响应没有 data:只有 {@code code / message},不回仓单号。 + * 所以 {@code InboundReceipt.providerInboundId} 为 null——不能把来源单号当仓单号填进去。

+ */ +public final class HengjianInboundCreateDtos { + + private HengjianInboundCreateDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateRequest { + + /** + * 单据状态:0 草稿 / 5 提交;不填默认 5(提交)。 + * + *

草稿状态下再调本接口是更新,不是新建。

+ */ + public Integer status; + + /** 仓库 code;必填。 */ + public String warehouseCode; + + /** 项目名称。 */ + public String lineCode; + + /** 库存类型:0 正常库存 / 1 不可售库存;必填。 */ + public Integer inventoryType; + + /** 批次号。 */ + public String batchNumber; + + /** 来源单号;必填。 */ + public String orderNo; + + /** Amazon 订单的 ShipmentId。 */ + public String shipmentId; + + /** Amazon 订单的 referenceId。 */ + public String referenceId; + + /** 单据币种,默认 USD,影响库存成本计算。 */ + public String currency; + + /** 预计入库日期 {@code yyyy-MM-dd}。 */ + public String estimateArriveTime; + + /** 预计发运日期 {@code yyyy-MM-dd}。 */ + public String predictionShipDate; + + /** 期望入库日期 {@code yyyy-MM-dd}。 */ + public String expectArriveDate; + + public String shipperName; + public String shipperAddress; + public String shipperContact; + public String shipperPhone; + public String remark; + public String originCountry; + + /** 采购单号。 */ + public String poNos; + + /** 实际发运日期 {@code yyyy-MM-dd}(自动发运时必填)。 */ + public String actualShipDate; + + /** 物流单号(自动发运用)。 */ + public String tmsNo; + + /** 船运公司(自动发运用)。 */ + public String shippingCompany; + + /** 货物类型:2 集装箱 / 4 卡车(自动发运时必填)。 */ + public Integer goodsType; + + /** 20GP 数量 / 箱号。 */ + public Integer gpQuantity20; + public String gpCartonNo20; + /** 40GP 数量 / 箱号。 */ + public Integer gpQuantity40; + public String gpCartonNo40; + /** 40HQ 数量 / 箱号。 */ + public Integer hqQuantity40; + public String hqCartonNo40; + /** 45HQ 数量 / 箱号。 */ + public Integer hqQuantity45; + public String hqCartonNo45; + + /** 产品明细;必填。 */ + public List productItems; + + /** 装箱信息。 */ + public List cartonItems; + + /** 产品明细行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ProductItem { + + /** 入库产品 SKU;必填。 */ + public String sku; + + /** 入库产品数量;必填。 */ + public Integer qty; + + /** 采购成本;影响库存成本,默认 0。 */ + public Double cost; + } + + /** 装箱信息行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CartonItem { + + /** 入库产品 SKU。 */ + public String sku; + + /** 产品数量。 */ + public Integer qty; + + /** 装箱入数。 */ + public Integer cartonQty; + + /** 箱码。 */ + public String cartonNo; + + /** 外箱重量(g)。 */ + public Double cartonWeight; + + /** 外箱尺寸(cm)。 */ + public Double cartonLength; + public Double cartonWidth; + public Double cartonHeight; + } + } + + /** 响应外层:没有 data。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CreateResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java index addc47d..d7b4e59 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -74,13 +74,22 @@ class HengjianAdapterTest { common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND)); } - /** 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ + /** 入库创建已接、查询未接:适配器对未实现的 get 显式抛异常。 */ + @Test + void unimplementedInboundGetIsRejected() { + WarehouseSdk sdk = sdk(); + + assertThrows(common.ecommerce.warehouse.error.WarehouseException.class, + () -> sdk.warehouses(WH, conn()).inbound().get("IB-1")); + } + + /** 退货仍未接入:门面按能力位直接拒绝。 */ @Test void undeclaredCapabilityIsRejected() { WarehouseSdk sdk = sdk(); assertThrows(WarehouseUnsupportedCapabilityException.class, - () -> sdk.warehouses(WH, conn()).inbound().get("IB-1")); + () -> sdk.warehouses(WH, conn()).returns().get("RT-1")); } /** 能力矩阵查询本身可用(不触发真实 API)。 */ @@ -88,9 +97,9 @@ class HengjianAdapterTest { void capabilityQueryIsOffline() { HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec()); - // 库存已接入;入库 / 退货仍是未接状态 + // 库存与入库已接入;退货仍是未接状态 assertTrue(!adapter.capabilities().contains( - common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND)); + common.ecommerce.warehouse.enums.WarehouseCapability.RETURN)); } @Test diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java index a812e89..4c62b00 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -484,7 +484,7 @@ class HengjianCreateOrderTest { .outboundRequestNo("OB-1").build())); } - /** 未声明的能力位仍然被门面挡住(INBOUND 还没接)。 */ + /** 未声明的能力位仍然被门面挡住(RETURN 还没接)。 */ @Test void undeclaredCapabilityIsRejectedByFacade() { WarehouseSdk sdk = WarehouseSdk.builder() @@ -504,6 +504,6 @@ class HengjianCreateOrderTest { HengjianConstants.TEST_BASE_URL, ChannelSecret.builder().appSecret("t").build(), ZoneOffset.UTC)) - .inbound().get("IB-1")); + .returns().get("RT-1")); } } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java index 3ecb7cb..9d76a95 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java @@ -235,8 +235,9 @@ class HengjianDirectoryTest { assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); - // 入库 / 退货 / 回调都还没接:声明了就必须有实现 - assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.INBOUND)); + // 退货 / 回调还没接:声明了就必须有实现 + assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.WEBHOOK)); } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundCreateTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundCreateTest.java new file mode 100644 index 0000000..b2ecf96 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundCreateTest.java @@ -0,0 +1,273 @@ +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.support.Money; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InboundCarton; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; +import common.ecommerce.warehouse.model.InboundReceipt; +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.LocalDate; +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 /v1/inbound/createInboundPlan})契约测试。 + */ +class HengjianInboundCreateTest { + + 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-16T00:00:00Z"), ZoneOffset.UTC)); + + private static final String CREATE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"创建入库计划成功\"}"; + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static RecordingTransport creating() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_CREATE, req -> Responses.ok(CREATE_BODY)); + } + + private static InboundCommand.Builder command() { + return InboundCommand.builder() + .inboundRequestNo("IB-2026-0001") + .warehouseId("EFCA") + .inventoryType(0) + .currency("USD") + .line(InboundLine.builder().omsSku("SKU-A").quantity(10).build()); + } + + // ---------------------------------------------------------------- 请求形状 + + @Test + void createPostsToInboundPlan() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inbound/createInboundPlan", + transport.lastDataRequest().url()); + } + + /** 真机确认的四个必填项都要出现。 */ + @Test + void sendsMandatoryFields() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"orderNo", "warehouseCode", "inventoryType", "productItems"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body); + } + assertTrue(body.contains("\"orderNo\":\"IB-2026-0001\""), body); + assertTrue(body.contains("\"warehouseCode\":\"EFCA\""), body); + assertTrue(body.contains("\"inventoryType\":0"), body); + } + + /** 产品明细:sku + qty,成本有就带。 */ + @Test + void sendsProductItems() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, InboundCommand.builder() + .inboundRequestNo("IB-2").warehouseId("EFCA").inventoryType(0) + .line(InboundLine.builder().omsSku("SKU-A").quantity(10) + .cost(Money.of("2.50", "USD")).build()) + .line(InboundLine.builder().providerSku("PROV-B").omsSku("OMS-B").quantity(3).build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"sku\":\"SKU-A\""), body); + assertTrue(body.contains("\"qty\":10"), body); + assertTrue(body.contains("\"cost\":2.5"), body); + // 仓侧 SKU 优先 + assertTrue(body.contains("\"sku\":\"PROV-B\""), body); + assertFalse(body.contains("OMS-B"), "有仓侧 SKU 时不该发 OMS SKU"); + } + + /** 文档标必填的 currency 真机校验里没有:不传也要能过。 */ + @Test + void currencyIsOptional() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, InboundCommand.builder() + .inboundRequestNo("IB-3").warehouseId("EFCA").inventoryType(0) + .line(InboundLine.builder().omsSku("SKU-A").quantity(1).build()).build()); + + assertFalse(transport.lastDataRequest().body().contains("currency")); + } + + /** 柜型映射到恒健的四个独立字段。 */ + @Test + void mapsContainerTypes() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command() + .container(new InboundCommand.Container("20GP", 2, "TCNU1234567")) + .container(new InboundCommand.Container("40HQ", 1, "OOLU7654321")) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"gpQuantity20\":2"), body); + assertTrue(body.contains("\"gpCartonNo20\":\"TCNU1234567\""), body); + assertTrue(body.contains("\"hqQuantity40\":1"), body); + assertTrue(body.contains("\"hqCartonNo40\":\"OOLU7654321\""), body); + } + + /** 认不出的柜型直接拒绝:静默丢弃等于少报柜数。 */ + @Test + void rejectsUnknownContainerType() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(CTX, command() + .container(new InboundCommand.Container("53FT", 1, null)).build())); + + assertTrue(ex.getMessage().contains("20GP"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 装箱信息:空不传,有则逐字段映射。 */ + @Test + void mapsCartonItems() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command() + .carton(InboundCarton.builder() + .providerSku("SKU-A").quantity(10).cartonQuantity(5) + .cartonNo("CTN-1") + .weightGrams(1200).lengthCm(40).widthCm(30).heightCm(20) + .build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"cartonItems\""), body); + assertTrue(body.contains("\"cartonQty\":5"), body); + assertTrue(body.contains("\"cartonNo\":\"CTN-1\""), body); + assertTrue(body.contains("\"cartonWeight\":1200.0"), body); + assertTrue(body.contains("\"cartonHeight\":20.0"), body); + } + + @Test + void omitsCartonItemsWhenEmpty() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + + assertFalse(transport.lastDataRequest().body().contains("cartonItems")); + } + + /** 日期按 yyyy-MM-dd 下发。 */ + @Test + void formatsDates() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command() + .estimateArriveDate(LocalDate.parse("2026-12-01")) + .expectArriveDate(LocalDate.parse("2026-12-05")) + .predictionShipDate(LocalDate.parse("2026-11-20")) + .actualShipDate(LocalDate.parse("2026-11-21")) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"estimateArriveTime\":\"2026-12-01\""), body); + assertTrue(body.contains("\"expectArriveDate\":\"2026-12-05\""), body); + assertTrue(body.contains("\"predictionShipDate\":\"2026-11-20\""), body); + assertTrue(body.contains("\"actualShipDate\":\"2026-11-21\""), body); + } + + /** 草稿状态可传:恒健的 status=0 是草稿,再调是更新。 */ + @Test + void sendsDocumentStatus() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().documentStatus(0).build()); + + assertTrue(transport.lastDataRequest().body().contains("\"status\":0")); + } + + /** 其它可选字段:采购单号 / 船运公司 / 货物类型。 */ + @Test + void sendsOptionalInboundFields() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command() + .purchaseOrderNos("PO-1,PO-2") + .shippingCompanyName("COSCO") + .goodsType(2) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"poNos\":\"PO-1,PO-2\""), body); + assertTrue(body.contains("\"shippingCompany\":\"COSCO\""), body); + assertTrue(body.contains("\"goodsType\":2"), body); + } + + // ---------------------------------------------------------------- 本地校验 + + @Test + void rejectsEmptyLines() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(CTX, InboundCommand.builder() + .inboundRequestNo("IB-X").warehouseId("EFCA").inventoryType(0).build())); + + assertTrue(ex.getMessage().contains("product line"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + // ---------------------------------------------------------------- 响应 + + /** 响应不回仓单号:不能拿来源单号顶替。 */ + @Test + void receiptHasNoProviderId() { + RecordingTransport transport = creating(); + InboundReceipt receipt = adapter(transport).create(CTX, command().build()); + + assertEquals("IB-2026-0001", receipt.inboundRequestNo()); + assertNull(receipt.providerInboundId(), "恒健不回仓单号,不能把来源单号填进去"); + } + + @Test + void businessErrorIsPropagated() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_CREATE, req -> Responses.ok( + "{\"statusCode\":500,\"status\":1,\"code\":999999," + + "\"message\":\"创建入库计划单失败SH1975454678入库订单已存在\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(CTX, command().build())); + assertTrue(ex.getMessage().contains("入库订单已存在"), ex.getMessage()); + } + + // ---------------------------------------------------------------- 能力位 + + @Test + void declaresInboundCapability() { + assertTrue(adapter(RecordingTransport.create()).capabilities() + .contains(WarehouseCapability.INBOUND)); + } + + /** 查询 / 分页还没接:显式拒绝,不返回 null。 */ + @Test + void unimplementedInboundQuery() { + HengjianAdapter adapter = adapter(RecordingTransport.create()); + + assertThrows(RuntimeException.class, () -> adapter.get(CTX, "IB-1")); + assertThrows(RuntimeException.class, () -> adapter.query(CTX, "IB-1")); + } +}