diff --git a/README.md b/README.md index 1cb3058..a55f9d8 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,8 @@ common.ecommerce │ HengjianProductMapper / HengjianOutboundMapper / │ HengjianOrderMapper / HengjianTrackingChangeMapper / │ HengjianFeeMapper / HengjianEstimateMapper / - │ HengjianInventoryMapper / HengjianInboundMapper + │ HengjianInventoryMapper / HengjianInboundMapper / + │ HengjianInboundQueryMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / @@ -390,7 +391,7 @@ common.ecommerce │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos / │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos / │ HengjianInventoryDtos / HengjianInventoryMovementDtos / - │ HengjianInboundCreateDtos + │ HengjianInboundCreateDtos / HengjianInboundQueryDtos ├── 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 d8abb73..7692c45 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -79,7 +79,9 @@ | 17 | 批量查库存(分页) | `GET /v2/inventory/get_inventory_by_page` | `INVENTORY_QUERY` | ✅ | | 18 | 库存变动流水 | `POST /v1/inventory/task/query` | `INVENTORY_QUERY` | ✅ | | 19 | 入库计划创建 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | ✅ | -| 20 | 回调 | — | — | ❌ 文档无回调页 | +| 20 | 入库计划详情 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` | ✅ | +| 21 | 入库计划列表 | `POST /v1/inbound/getInboundPlanPage` | `INBOUND` | ✅ | +| 22 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -419,6 +421,57 @@ productItems(入库产品明细必须填写) **未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。 +### 入库计划详情 / 列表(`INBOUND`)—— 已接入 + +两个接口回的对象**字段完全一致**,只有外层形状不同(`data` 对象 vs `data.content[]` 分页信封), +所以共用一份行模型与映射。 + +#### 详情(`/v1/inbound/getInboundPlanInfo`) + +- 真机确认 `orderNo` 必填(空 body 回「单号不能为空」)。 +- 单号可以是**仓方计划单号**,也可以是**来源单号**——响应同时回 `inboundPlanOrderNo` 与 `sourceNo`。 +- 双号映射:`inboundRequestNo = sourceNo`(缺失时退回仓单号)、`providerInboundId = inboundPlanOrderNo`。 +- `data` 为空 → 返回 `null`(查不到),不造空单。 + +#### 列表(`/v1/inbound/getInboundPlanPage`) + +- `page` / `size` 文档标必填,真机不传也能过校验(只停在鉴权);仍按文档下发。 +- 支持的过滤维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 / 七种时间区间 / Amazon shipmentId。 +- **状态过滤要转数字码**(`inboundPlanOrderStatusList` 是 int 数组); + 认不出的状态**拒绝**,不猜——猜错会拉回一大堆无关单。 +- 时间区间是**单值字符串** `yyyy-MM-dd ~ yyyy-MM-dd`,不是一个 start/end 对。 +- 统一模型 `InboundQuery` 只表达三种时间窗(创建 / 更新 / 完成);恒健另有四种 + (期望到货 / 预计发货 / 预计入库 / 首次接收),模型里没有——需要时再扩字段。 +- 页大小上限 200(文档没写,保守值);超限拒绝不截断。 + +#### 状态枚举(`HengjianInboundStatus`) + +**两套码表不能混**: + +| 来源 | 码表 | +|---|---| +| 计划单 `inboundPlanOrderStatus` / 列表过滤参数 | 0 草稿 / 5 待审核 / 6 审核拒回 / 8 待装箱 / 10 待发货 / 15 待接收 / 20 待入库 / 25 入库中 / 70 已完成 / 100 已取消 | +| 收货单 `inboundOrderList[].inboundOrderStatus` | 0 草稿 / 70 已完成 / 90 已关闭 | + +同一个值 `70` 在两张表里都表示「已完成」纯属巧合;`0` 一个是草稿、另一个也是草稿但语义不同套。 +适配器只把**计划单**的状态归一成 `InboundStatus`,收货单的状态原样保留。 + +枚举的 `of()` 同时认数字串(`"70"`)与中文名(`"已完成"`)——因为详情字段表标 STRING、 +示例给 `"70"`,而列表请求参数是数字数组,三种形态都出现过。 + +#### 数量三层的口径 + +`planQty` / `packedQty` / `receivedQty` → `plannedQuantity` / `packedQuantity` / `receivedQuantity`, +**不重算**——仓方给的就是准的,重算会掩盖仓方的数据问题。 + +产品行的 `qtyReceivedSaleable` / `qtyReceivedUnsaleable` 分开映射;两者都为 0 而 +`qtyReceived > 0` 时按可售兜底(总数一致,不编造拆分)。 + +#### 收货单 → 批次 + +`inboundOrderList` 是**实际收货单**,落成 `InboundOrderBatch` 的 `INBOUNDED` 阶段。 +收货单号作为 `cartonNo`(该粒度没有独立箱号);库存类型保持 null(收货单层面没有细分)。 + ### 库存(`INVENTORY_QUERY`)—— 已接入 恒健有**两个**库存接口,能力不同,统一模型只有一个 `query()`,按「给了什么」分流: @@ -570,7 +623,8 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射 │ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射 │ │ ├── HengjianInventoryMapper.java 库存两个接口 + 变动流水 - │ │ └── HengjianInboundMapper.java 入库计划创建 + │ │ ├── HengjianInboundMapper.java 入库计划创建 + │ │ └── HengjianInboundQueryMapper.java 入库详情 / 列表 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -603,13 +657,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射 ├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射 ├── adapter/HengjianInboundCreateTest.java 17 个:必填 / 柜型 / 装箱 / 无仓单号 + ├── adapter/HengjianInboundQueryTest.java 18 个:详情映射 / 状态码表 / 列表过滤 / 分页 ├── 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` 全部通过(220 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(238 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java index 30335eb..c38156b 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java @@ -36,6 +36,21 @@ public interface InboundCapable extends WarehouseAdapter { */ Page query(WarehouseContext ctx, String cursor); + /** + * 多条件分页查入库单。 + * + *

与 {@link #query(WarehouseContext, String)} 的区别:那个只有游标 + * (没有列表接口的仓拿单号当游标),这个支持仓 / 状态 / 单号 / 时间窗等条件。 + * 不支持的维度由适配器显式拒绝,不静默忽略。

+ * + *

默认不支持——只有提供列表接口的仓才覆盖。

+ */ + default Page queryInbounds(WarehouseContext ctx, + common.ecommerce.warehouse.model.InboundQuery query) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND); + } + /** BOL 文档;无此能力的仓返回空列表。 */ default List bols(WarehouseContext ctx, String inboundRef) { return Collections.emptyList(); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundQuery.java new file mode 100644 index 0000000..4db6cf0 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundQuery.java @@ -0,0 +1,303 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.InboundStatus; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 入库计划列表查询条件。 + * + *

与 {@code InboundCapable.query(ctx, cursor)} 的区别:那个只有游标( + * 运去哪 / 信仓没有列表接口,只能用单号当游标),这个是真正的多条件分页查询。

+ * + *

各仓支持的维度不同:不支持的维度由适配器显式拒绝,不静默忽略—— + * 忽略一个过滤条件会让调用方以为「这段时间就这么多入库单」。

+ */ +public final class InboundQuery { + + private final List warehouseCodes; + private final List providerOrderNos; + private final List sourceNos; + private final List statuses; + /** 库存类型:null 不限 / 0 可售 / 1 不可售。 */ + private final Integer inventoryType; + /** 创建时间窗起点(UTC 日期);与 {@link #createdBefore()} 成对。 */ + private final LocalDate createdAfter; + private final LocalDate createdBefore; + /** 更新时间窗(UTC 日期)。 */ + private final LocalDate updatedAfter; + private final LocalDate updatedBefore; + /** 完成时间窗。 */ + private final LocalDate completedAfter; + private final LocalDate completedBefore; + /** Amazon 货件号。 */ + private final String shipmentId; + private final int pageSize; + private final String cursor; + + private InboundQuery(Builder b) { + this.warehouseCodes = Collections.unmodifiableList(new ArrayList(b.warehouseCodes)); + this.providerOrderNos = Collections.unmodifiableList(new ArrayList(b.providerOrderNos)); + this.sourceNos = Collections.unmodifiableList(new ArrayList(b.sourceNos)); + this.statuses = Collections.unmodifiableList(new ArrayList(b.statuses)); + this.inventoryType = b.inventoryType; + requirePair(b.createdAfter, b.createdBefore, "createdAfter", "createdBefore"); + requirePair(b.updatedAfter, b.updatedBefore, "updatedAfter", "updatedBefore"); + requirePair(b.completedAfter, b.completedBefore, "completedAfter", "completedBefore"); + this.createdAfter = b.createdAfter; + this.createdBefore = b.createdBefore; + this.updatedAfter = b.updatedAfter; + this.updatedBefore = b.updatedBefore; + this.completedAfter = b.completedAfter; + this.completedBefore = b.completedBefore; + this.shipmentId = b.shipmentId; + this.pageSize = b.pageSize; + this.cursor = b.cursor; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓 code 列表;空表示用账户配置的仓。 */ + public List warehouseCodes() { + return warehouseCodes; + } + + /** 仓方入库计划单号列表。 */ + public List providerOrderNos() { + return providerOrderNos; + } + + /** 来源单号(我们下发的入库单号)列表。 */ + public List sourceNos() { + return sourceNos; + } + + /** 状态过滤;空表示不限。 */ + public List statuses() { + return statuses; + } + + /** 库存类型:null 不限 / 0 可售 / 1 不可售。 */ + public Integer inventoryType() { + return inventoryType; + } + + public LocalDate createdAfter() { + return createdAfter; + } + + public LocalDate createdBefore() { + return createdBefore; + } + + /** 是否给了创建时间窗。 */ + public boolean hasCreatedRange() { + return createdAfter != null; + } + + public LocalDate updatedAfter() { + return updatedAfter; + } + + public LocalDate updatedBefore() { + return updatedBefore; + } + + /** 是否给了更新时间窗。 */ + public boolean hasUpdatedRange() { + return updatedAfter != null; + } + + public LocalDate completedAfter() { + return completedAfter; + } + + public LocalDate completedBefore() { + return completedBefore; + } + + /** 是否给了完成时间窗。 */ + public boolean hasCompletedRange() { + return completedAfter != null; + } + + public String shipmentId() { + return shipmentId; + } + + public int pageSize() { + return pageSize; + } + + /** 分页游标;null 表示第一页。 */ + public String cursor() { + return cursor; + } + + /** 翻页时只改游标。 */ + public Builder toBuilder() { + Builder b = builder() + .warehouseCodes(warehouseCodes) + .providerOrderNos(providerOrderNos) + .sourceNos(sourceNos) + .statuses(statuses) + .inventoryType(inventoryType) + .shipmentId(shipmentId) + .pageSize(pageSize) + .cursor(cursor); + if (hasCreatedRange()) { + b.createdRange(createdAfter, createdBefore); + } + if (hasUpdatedRange()) { + b.updatedRange(updatedAfter, updatedBefore); + } + if (hasCompletedRange()) { + b.completedRange(completedAfter, completedBefore); + } + return b; + } + + private static void requirePair(LocalDate after, LocalDate before, String an, String bn) { + if ((after == null) != (before == null)) { + throw new IllegalArgumentException(an + " and " + bn + " must be set together"); + } + if (after != null && after.isAfter(before)) { + throw new IllegalArgumentException(an + " must not be after " + bn); + } + } + + public static final class Builder { + + private final List warehouseCodes = new ArrayList(); + private final List providerOrderNos = new ArrayList(); + private final List sourceNos = new ArrayList(); + private final List statuses = new ArrayList(); + private Integer inventoryType; + private LocalDate createdAfter; + private LocalDate createdBefore; + private LocalDate updatedAfter; + private LocalDate updatedBefore; + private LocalDate completedAfter; + private LocalDate completedBefore; + private String shipmentId; + private int pageSize = 100; + private String cursor; + + public Builder warehouseCode(String v) { + if (v != null && !v.trim().isEmpty()) { + this.warehouseCodes.add(v.trim()); + } + return this; + } + + public Builder warehouseCodes(List v) { + if (v != null) { + for (String one : v) { + warehouseCode(one); + } + } + return this; + } + + /** 仓方入库计划单号。 */ + public Builder providerOrderNo(String v) { + if (v != null && !v.trim().isEmpty()) { + this.providerOrderNos.add(v.trim()); + } + return this; + } + + public Builder providerOrderNos(List v) { + if (v != null) { + for (String one : v) { + providerOrderNo(one); + } + } + return this; + } + + /** 来源单号(我们下发的入库单号)。 */ + public Builder sourceNo(String v) { + if (v != null && !v.trim().isEmpty()) { + this.sourceNos.add(v.trim()); + } + return this; + } + + public Builder sourceNos(List v) { + if (v != null) { + for (String one : v) { + sourceNo(one); + } + } + return this; + } + + public Builder status(InboundStatus v) { + if (v != null) { + this.statuses.add(v); + } + return this; + } + + public Builder statuses(List v) { + if (v != null) { + for (InboundStatus one : v) { + status(one); + } + } + return this; + } + + /** 库存类型:0 可售 / 1 不可售;null 不限。 */ + public Builder inventoryType(Integer v) { + this.inventoryType = v; + return this; + } + + /** 创建时间窗;两端成对。 */ + public Builder createdRange(LocalDate after, LocalDate before) { + this.createdAfter = after; + this.createdBefore = before; + return this; + } + + /** 更新时间窗;两端成对。 */ + public Builder updatedRange(LocalDate after, LocalDate before) { + this.updatedAfter = after; + this.updatedBefore = before; + return this; + } + + /** 完成时间窗;两端成对。 */ + public Builder completedRange(LocalDate after, LocalDate before) { + this.completedAfter = after; + this.completedBefore = before; + return this; + } + + public Builder shipmentId(String v) { + this.shipmentId = v; + return this; + } + + public Builder pageSize(int v) { + this.pageSize = v; + return this; + } + + public Builder cursor(String v) { + this.cursor = v; + return this; + } + + public InboundQuery build() { + return new InboundQuery(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index b049525..5bae159 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -483,6 +483,24 @@ public final class WarehouseOperations { } /** + * 多条件分页查入库单。只读。 + * + *

与 {@link #query(String)} 的区别:那个只有游标,这个支持仓 / 状态 / 单号 / 时间窗。

+ */ + public Page queryInbounds( + final common.ecommerce.warehouse.model.InboundQuery query) { + require(WarehouseCapability.INBOUND, InboundCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.inbound.queryInbounds", + CallSupport.params("warehouseCount", query.warehouseCodes().size(), + "statusCount", query.statuses().size(), + "sourceNoCount", query.sourceNos().size(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + p -> p.size(), + () -> ((InboundCapable) adapter).queryInbounds(ctx, query)); + } + + /** * 完善入库单资料。写操作:强制经幂等守卫,幂等键 * {@code warehouseCode + inboundRef + improve}。 */ 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 e7bcb20..2025ad5 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 @@ -203,6 +203,27 @@ public final class HengjianConstants { public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; /** + * 入库计划详情({@code POST})。 + * + *

真机确认:{@code orderNo} 必填(空 body 回「单号不能为空」)。

+ */ + public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo"; + + /** + * 入库计划列表({@code POST},分页)。 + * + *

真机确认:{@code page} / {@code size} 不传也能过参数校验(只停在鉴权), + * 但文档标必填,适配器仍按文档下发。

+ */ + public static final String PATH_INBOUND_PAGE = "/v1/inbound/getInboundPlanPage"; + + /** 入库计划列表默认页大小。 */ + public static final int INBOUND_PAGE_SIZE_DEFAULT = 20; + + /** 入库计划列表单页上限:文档没写,取 200;超限拒绝不截断。 */ + public static final int INBOUND_PAGE_SIZE_MAX = 200; + + /** * {@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 6f9f083..1c82d8d 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 @@ -8,6 +8,7 @@ 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.HengjianInboundQueryDtos; import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; @@ -58,6 +59,7 @@ 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.InboundQuery; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryMovement; import common.ecommerce.warehouse.model.InventoryMovementQuery; @@ -118,6 +120,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti 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"; + private static final String OP_INBOUND_GET = "warehouse.inbound.get"; + private static final String OP_INBOUND_QUERY = "warehouse.inbound.query"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -184,26 +188,65 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti return InboundReceipt.of(cmd.inboundRequestNo(), null); } - /** 入库查询未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + /** + * 查入库计划详情({@code POST /v1/inbound/getInboundPlanInfo})。 + * + *

恒健只按单号查,且这个单号可以是仓方计划单号,也可以是来源单号 + * (详情响应同时回 {@code inboundPlanOrderNo} 与 {@code sourceNo})。

+ * + *

查不到({@code data} 为空)返回 null——与其它仓一致。

+ */ @Override public InboundOrder get(WarehouseContext ctx, String inboundRef) { - throw unsupportedInbound("warehouse.inbound.get", ctx); + String orderNo = trimToNull(inboundRef); + if (orderNo == null) { + throw new IllegalArgumentException("hengjian inbound get requires an order number"); + } + HengjianInboundQueryDtos.FindOneRequest body = + HengjianInboundQueryMapper.toFindOneRequest(orderNo); + String raw = execute(ctx, HengjianConstants.PATH_INBOUND_GET, body, OP_INBOUND_GET); + JsonNode data = json.nodeAt(raw, "data"); + if (data == null || data.isNull() || data.isMissingNode()) { + return null; + } + HengjianInboundQueryDtos.InboundPlan plan = + json.fromJson(data.toString(), HengjianInboundQueryDtos.InboundPlan.class); + return HengjianInboundQueryMapper.toOrder(plan, fallbackWarehouse(ctx)); } + /** + * 按游标分页查入库单。 + * + *

统一模型这个入口只有一个游标,恒健的列表接口支持多条件;这里把游标当页码, + * 其余条件为空——需要按状态 / 时间窗筛时用 + * {@link #queryInbounds(WarehouseContext, InboundQuery)}。

+ */ @Override public Page query(WarehouseContext ctx, String cursor) { - throw unsupportedInbound("warehouse.inbound.query", ctx); + return queryInbounds(ctx, InboundQuery.builder().cursor(cursor).build()); } - 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(); + /** + * 多条件分页查入库计划({@code POST /v1/inbound/getInboundPlanPage})。 + * + *

恒健列表支持的维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 / + * 七种时间区间(创建 / 更新 / 完成 / 期望到货 / 预计发货 / 预计入库 / 首次接收)/ + * Amazon shipmentId。

+ * + *

统一模型只表达其中三种时间窗(创建 / 更新 / 完成)。其余四种恒健独有, + * 模型里没有——需要时再经 {@code InboundQuery} 扩字段,不在这里硬塞。

+ * + *

未支持的维度直接拒绝:见 {@link #queryInbounds} 里的校验。

+ */ + @Override + public Page queryInbounds(WarehouseContext ctx, InboundQuery query) { + HengjianInboundQueryDtos.PageRequest body = + HengjianInboundQueryMapper.toPageRequest(query, ctx.providerWarehouseId()); + String raw = execute(ctx, HengjianConstants.PATH_INBOUND_PAGE, body, OP_INBOUND_QUERY); + HengjianInboundQueryDtos.PageResponse resp = + json.fromJson(raw, HengjianInboundQueryDtos.PageResponse.class); + return HengjianInboundQueryMapper.toPage(resp == null ? null : resp.data, + fallbackWarehouse(ctx), query.cursor()); } // ------------------------------------------------------------------ 库存 diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryMapper.java new file mode 100644 index 0000000..b4d697d --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryMapper.java @@ -0,0 +1,449 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos; +import common.ecommerce.hengjian.enums.HengjianInboundStatus; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.InboundStatus; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundOrderBatch; +import common.ecommerce.warehouse.model.InboundOrderBox; +import common.ecommerce.warehouse.model.InboundOrderLine; +import common.ecommerce.warehouse.model.InboundQuery; + +import java.time.Instant; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.ZoneOffset; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 恒健入库计划报文映射(详情 / 列表共用)。 + * + *

两个接口一个行模型

+ *

{@code getInboundPlanInfo} 与 {@code getInboundPlanPage} 回的对象字段完全一致, + * 只有外层形状不同(对象 vs 分页信封),所以映射只有一份。

+ * + *

状态码表

+ *

计划单状态用 {@link HengjianInboundStatus};{@code inboundOrderList[]} 里的 + * {@code inboundOrderStatus} 是收货单的码表(0/70/90),与计划单不同,不混用。

+ * + *

数量三层

+ *

{@code planQty} / {@code packedQty} / {@code receivedQty} 分别落 + * {@code plannedQuantity} / {@code packedQuantity} / {@code receivedQuantity}, + * 短少与溢装靠比对它们发现,不重算——仓方给的就是准的。

+ */ +public final class HengjianInboundQueryMapper { + + /** 时间格式(文档未标时区;与其它接口同口径按 UTC 解析)。 */ + private static final DateTimeFormatter DATE_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + private HengjianInboundQueryMapper() { + } + + // ================================================================ 详情 / 列表请求 + + /** 详情请求:只按单号。 */ + public static HengjianInboundQueryDtos.FindOneRequest toFindOneRequest(String orderNo) { + HengjianInboundQueryDtos.FindOneRequest req = new HengjianInboundQueryDtos.FindOneRequest(); + req.orderNo = orderNo; + return req; + } + + /** + * 列表请求。 + * + *

恒健的列表参数都很直接,只需要注意两点:

+ *
    + *
  • 状态过滤要转成数字码({@code inboundPlanOrderStatusList} 是 int 数组);
  • + *
  • 时间区间是单值字符串 {@code yyyy-MM-dd ~ yyyy-MM-dd},不是一个 start/end 对。
  • + *
+ * + * @throws IllegalArgumentException 状态无法映射成恒健码(认不出的状态不能猜) + */ + public static HengjianInboundQueryDtos.PageRequest toPageRequest(InboundQuery query, + String defaultWarehouseCode) { + HengjianInboundQueryDtos.PageRequest req = new HengjianInboundQueryDtos.PageRequest(); + req.page = pageOf(query.cursor()); + req.size = sizeOf(query.pageSize()); + req.inventoryType = query.inventoryType(); + + if (!query.providerOrderNos().isEmpty()) { + req.inboundPlanOrderNoList = new ArrayList(query.providerOrderNos()); + } + if (!query.sourceNos().isEmpty()) { + req.sourceNoList = new ArrayList(query.sourceNos()); + } + if (!query.statuses().isEmpty()) { + List codes = new ArrayList(query.statuses().size()); + for (InboundStatus status : query.statuses()) { + Integer code = codeOf(status); + if (code == null) { + // 认不出的状态不能猜:猜错会拉回一大堆无关单 + throw new IllegalArgumentException( + "hengjian inbound list cannot filter by status " + status); + } + codes.add(code); + } + req.inboundPlanOrderStatusList = codes; + } + // 仓过滤:调用方给了就用,否则用账户仓 + if (!query.warehouseCodes().isEmpty()) { + req.orgWarehouseCodeList = new ArrayList(query.warehouseCodes()); + } else if (defaultWarehouseCode != null && !defaultWarehouseCode.trim().isEmpty()) { + req.orgWarehouseCodeList = Collections.singletonList(defaultWarehouseCode.trim()); + } + if (query.hasCreatedRange()) { + req.btCreatedDate = rangeOf(query.createdAfter(), query.createdBefore()); + } + if (query.hasUpdatedRange()) { + req.btUpdatedDate = rangeOf(query.updatedAfter(), query.updatedBefore()); + } + if (query.hasCompletedRange()) { + req.btCompleteDate = rangeOf(query.completedAfter(), query.completedBefore()); + } + if (query.shipmentId() != null && !query.shipmentId().trim().isEmpty()) { + req.shipmentId = query.shipmentId().trim(); + } + return req; + } + + /** 核心状态 → 恒健数字码;认不出返回 null。 */ + static Integer codeOf(InboundStatus status) { + if (status == null) { + return null; + } + switch (status) { + case DRAFT: + return 0; + case PENDING_REVIEW: + return 5; + case REJECTED: + return 6; + case PENDING_PACKING: + return 8; + case PENDING_SHIPMENT: + return 10; + case IN_TRANSIT: + return 15; + case PENDING_STORAGE: + return 20; + case STORING: + return 25; + case COMPLETED: + return 70; + case CANCELLED: + return 100; + default: + // RECEIVING / RECEIVED / UNKNOWN 等恒健没有对应码 + return null; + } + } + + /** 日期区间 → {@code yyyy-MM-dd ~ yyyy-MM-dd}。 */ + static String rangeOf(LocalDate start, LocalDate end) { + return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end; + } + + /** 页码:游标是字符串化页码,空游标表示第 1 页(入参 1 基)。 */ + static int pageOf(String cursor) { + String v = trimToNull(cursor); + if (v == null) { + return 1; + } + try { + int page = Integer.parseInt(v); + return page < 1 ? 1 : page; + } catch (NumberFormatException e) { + throw new IllegalArgumentException( + "hengjian inbound list cursor must be a page number, got " + v); + } + } + + /** 页大小:未指定用默认;上限没有文档依据,取 200 并拒绝超标(不静默截断)。 */ + static int sizeOf(int requested) { + if (requested <= 0) { + return HengjianConstants.INBOUND_PAGE_SIZE_DEFAULT; + } + if (requested > HengjianConstants.INBOUND_PAGE_SIZE_MAX) { + throw new IllegalArgumentException( + "hengjian inbound page size must not exceed " + + HengjianConstants.INBOUND_PAGE_SIZE_MAX + ", got " + requested); + } + return requested; + } + + // ================================================================ 响应 + + /** 一个入库计划 → 统一模型。 */ + public static InboundOrder toOrder(HengjianInboundQueryDtos.InboundPlan plan, + String warehouseCode) { + String sourceNo = trimToNull(plan.sourceNo); + String planNo = trimToNull(plan.inboundPlanOrderNo); + // 双号:来源单号是我们下发的,仓单号是仓方生成的。 + // 来源单号缺失时(老单可能没回填)退回仓单号,避免构造期因空值失败 + String requestNo = sourceNo != null ? sourceNo : planNo; + if (requestNo == null) { + throw new IllegalArgumentException( + "hengjian inbound plan has neither sourceNo nor inboundPlanOrderNo"); + } + InboundStatus status = HengjianInboundStatus.toCore(plan.inboundPlanOrderStatus); + + InboundOrder.Builder builder = InboundOrder.builder() + .inboundRequestNo(requestNo) + .providerInboundId(planNo) + .warehouseCode(firstNonBlank(plan.orgWarehouseCode, warehouseCode)) + .status(status) + .rawStatus(trimToNull(plan.inboundPlanOrderStatus)) + .rawStatusName(firstNonBlank(plan.inboundPlanOrderStatusName, null)) + .sourceProvider(WarehouseProvider.HENGJIAN) + .inventoryType(inventoryTypeOf(plan.inventoryType)) + .boxCount(intOf(plan.cartonQty)) + .plannedQuantity(intOf(plan.planQty)) + .packedQuantity(intOf(plan.packedQty)) + .receivedQuantity(intOf(plan.receivedQty)) + .lineName(trimToNull(plan.lineName)) + .shipmentId(trimToNull(plan.shipmentId)) + .referenceId(trimToNull(plan.referenceId)) + .shipmentNo(trimToNull(plan.shipmentNo)) + .goodsType(trimToNull(plan.goodsType)) + .actualShippedAt(parseDate(plan.actualShipDate)) + .cartonTotalWeightKg(positiveOrNull(plan.cartonTotalWeight)) + .cartonTotalVolumeCbm(positiveOrNull(plan.cartonTotalVolume)) + .packingLabelUrl(trimToNull(plan.packingLabelUrl)) + // 创建时间:详情与列表都回 createdAt,与运去哪不同(那边没有) + .createdAt(parseTime(plan.createdAt)) + .receivedAt(parseTime(firstNonNull(plan.firstReceptionTime, plan.firstReceptionDate))) + .estimatedArrivalAt(parseTime(plan.estimateArriveTime)) + .actualArrivalAt(parseTime(plan.actualArriveTime)) + .shipperName(trimToNull(plan.shipperName)) + .shipperContact(trimToNull(plan.shipperContact)) + .shipperPhone(trimToNull(plan.shipperPhone)) + .shipperAddress(trimToNull(plan.shipperAddress)) + .totalWeightKg(positiveOrNull(plan.totalWeight)) + .totalVolumeCbm(positiveOrNull(plan.totalVolume)) + .remark(trimToNull(plan.remark)) + .modifiedAt(parseTime(plan.updatedAt)); + addContainers(builder, plan); + builder.lines(toLines(plan.planProductDetailParamList)); + addReceivedOrders(builder, plan.inboundOrderList); + return builder.build(); + } + + /** 列表 → 统一 Page。 */ + public static Page toPage(HengjianInboundQueryDtos.PageData data, + String warehouseCode, String cursor) { + if (data == null) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(); + if (data.content != null) { + for (HengjianInboundQueryDtos.InboundPlan plan : data.content) { + if (plan != null) { + out.add(toOrder(plan, warehouseCode)); + } + } + } + // 响应 number 是 0 基,请求 page 是 1 基:下一页 = number + 2 + boolean last = data.last != null ? data.last + : (data.numberOfElements != null && data.number == null); + if (last) { + return Page.last(out); + } + int next = (data.number == null ? 0 : data.number) + 2; + return Page.of(out, String.valueOf(next)); + } + + // ================================================================ 组件 + + /** 柜型:恒健把四种规格拆成独立字段,这里按有数量的规格逐个建 ContainerInfo。 */ + private static void addContainers(InboundOrder.Builder builder, + HengjianInboundQueryDtos.InboundPlan plan) { + addContainer(builder, InboundOrder.ContainerType.GP20, plan.gpQuantity20, plan.gpCartonNo20); + addContainer(builder, InboundOrder.ContainerType.GP40, plan.gpQuantity40, plan.gpCartonNo40); + addContainer(builder, InboundOrder.ContainerType.HQ40, plan.hqQuantity40, plan.hqCartonNo40); + addContainer(builder, InboundOrder.ContainerType.HQ45, plan.hqQuantity45, plan.hqCartonNo45); + } + + private static void addContainer(InboundOrder.Builder builder, InboundOrder.ContainerType type, + String quantity, String cartonNo) { + Integer qty = intOrNull(quantity); + if (qty == null || qty <= 0) { + return; + } + builder.container(InboundOrder.ContainerInfo.builder() + .type(type) + .quantity(qty) + .containerNo(trimToNull(cartonNo)) + .rawType(type.name()) + .build()); + } + + /** + * 产品明细。 + * + *

数量缺失或非正的行跳过:{@link InboundOrderLine} 要求计划数量为正, + * 保留会在构造期抛异常,把「一条坏数据」放大成「整单查不出来」。

+ */ + static List toLines(List details) { + List out = new ArrayList(); + if (details == null) { + return out; + } + for (HengjianInboundQueryDtos.InboundPlan.ProductDetail detail : details) { + if (detail == null) { + continue; + } + String sku = trimToNull(detail.sku); + int planned = intOf(detail.qty); + if (sku == null || planned <= 0) { + continue; + } + int received = intOf(detail.qtyReceived); + int saleable = intOf(detail.qtyReceivedSaleable); + int unsaleable = intOf(detail.qtyReceivedUnsaleable); + // 仓方把可售 / 不可售分开给;没有细分时按可售兜底(总数一致,不编造拆分) + if (saleable == 0 && unsaleable == 0 && received > 0) { + saleable = received; + } + out.add(InboundOrderLine.builder() + .providerSku(sku) + .plannedQuantity(planned) + .packedQuantity(intOf(detail.qtyPacked)) + .receivedQuantity(received) + .receivedSaleableQuantity(saleable) + .receivedUnsaleableQuantity(unsaleable) + .build()); + } + return out; + } + + /** + * 实际收货单 → 批次明细。 + * + *

恒健的 {@code inboundOrderList} 是「实际收货单」,每张单有独立的码表 + * (0 草稿 / 70 已完成 / 90 已关闭)与行明细。落成 + * {@link InboundOrderBatch} 的 {@code INBOUNDED} 阶段——它与「计划批次」是两段数据。

+ */ + private static void addReceivedOrders(InboundOrder.Builder builder, + List orders) { + if (orders == null) { + return; + } + for (HengjianInboundQueryDtos.InboundPlan.InboundOrderInfo order : orders) { + if (order == null || order.inboundOrderItemList == null) { + continue; + } + for (HengjianInboundQueryDtos.InboundPlan.InboundOrderInfo.InboundOrderItem item + : order.inboundOrderItemList) { + if (item == null) { + continue; + } + String sku = trimToNull(item.sku); + int qty = intOf(item.qty); + if (sku == null || qty <= 0) { + continue; + } + builder.batch(InboundOrderBatch.builder() + .phase(InboundOrderBatch.Phase.INBOUNDED) + .providerSku(sku) + .quantity(qty) + // 箱唛号:收货单粒度,每行没有独立箱号 + .cartonNo(trimToNull(order.inboundOrderNo)) + // 库存类型:收货单层面没有细分,保持 null(未知,不猜) + .inventoryType(null) + .build()); + } + } + } + + // ================================================================ 工具 + + /** 库存类型:文字「可售库存 / 不可售库存」与数字 {@code "0"/"1"} 都要认。 */ + static int inventoryTypeOf(String raw) { + String v = trimToNull(raw); + if (v == null) { + return 0; + } + if (v.contains("不可售")) { + return 1; + } + Integer n = intOrNull(v); + return n == null ? 0 : n; + } + + static Instant parseTime(String value) { + String v = trimToNull(value); + if (v == null) { + return null; + } + try { + return LocalDateTime.parse(v, DATE_TIME).toInstant(ZoneOffset.UTC); + } catch (DateTimeParseException e) { + // 有些字段只给日期(yyyy-MM-dd),按当天 00:00:00 解释 + try { + return LocalDate.parse(v, DATE).atStartOfDay().toInstant(ZoneOffset.UTC); + } catch (DateTimeParseException ignored) { + try { + return Instant.parse(v); + } catch (DateTimeParseException alsoIgnored) { + return null; + } + } + } + } + + static Instant parseDate(String value) { + return parseTime(value); + } + + static int intOf(Integer value) { + return value == null ? 0 : value; + } + + /** 文本转 int;空 / 非数字返回 0(仓方有些数量字段标 STRING 却可能给空串)。 */ + static int intOf(String value) { + Integer n = intOrNull(value); + return n == null ? 0 : n; + } + + static Integer intOrNull(String value) { + String v = trimToNull(value); + if (v == null) { + return null; + } + try { + return Integer.valueOf(v); + } catch (NumberFormatException e) { + return null; + } + } + + private static Double positiveOrNull(Double v) { + return v == null || v <= 0 ? null : v; + } + + private static String firstNonNull(String a, String b) { + String x = trimToNull(a); + return x != null ? x : trimToNull(b); + } + + private static String firstNonBlank(String a, String b) { + return firstNonNull(a, b); + } + + 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/HengjianInboundQueryDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundQueryDtos.java new file mode 100644 index 0000000..5e81e6e --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundQueryDtos.java @@ -0,0 +1,357 @@ +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 getInboundPlanInfo} / {@code getInboundPlanPage})回的对象 + * 字段完全一致,只有外层形状不同:详情是 {@code data} 对象,列表是 + * {@code data.content[]} 分页信封。所以行模型共用。

+ * + *

类型怪癖:同一个字段在不同接口 / 不同示例里类型不一致——

+ *
    + *
  • {@code inboundPlanOrderStatus}:字段表标 STRING,示例给 {@code "70"}(数字的字符串), + * 而列表的请求参数又是数字数组。
  • + *
  • {@code inventoryType}:详情示例给中文「可售库存」,列表示例给 {@code "0"}。
  • + *
  • {@code gpQuantity20} 等柜数:字段表标 STRING,示例给数字。
  • + *
+ *

统一按文本读,解析时再转——这样两种形态都能接住,不会因类型漂移炸掉整单。

+ */ +public final class HengjianInboundQueryDtos { + + private HengjianInboundQueryDtos() { + } + + /** 详情请求:只按入库计划单号。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FindOneRequest { + + /** 入库计划单号(我们下发时是来源单号 orderNo)。 */ + public String orderNo; + } + + /** 详情响应。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class FindOneResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public InboundPlan plan; + } + + /** + * 列表请求。 + * + *

所有过滤条件都可选;{@code page} / {@code size} 文档标必填, + * 但真机不传也能过校验(只停在鉴权),适配器仍按文档发。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class PageRequest { + + /** 第几页,默认 1。 */ + public Integer page; + + /** 每页几条,默认 10。 */ + public Integer size; + + /** 库存类型:0 可售 / 1 不可售。 */ + public Integer inventoryType; + + /** 入库计划单号列表。 */ + public List inboundPlanOrderNoList; + + /** 来源单号列表。 */ + public List sourceNoList; + + /** 状态码列表(数字码,见 {@code HengjianInboundStatus})。 */ + public List inboundPlanOrderStatusList; + + /** 仓库 code 列表。 */ + public List orgWarehouseCodeList; + + /** 时间区间过滤,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。 */ + public String btUpdatedDate; + public String btCreatedDate; + public String btCompleteDate; + public String btExpectArriveDate; + public String btPredictionShipDate; + public String btEstimateArriveDate; + public String btFirstReceptionDate; + + /** Amazon shipmentId。 */ + public String shipmentId; + } + + /** 列表响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PageResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public PageData data; + } + + /** 分页数据。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PageData { + + @JsonProperty("content") + public List content; + + @JsonProperty("totalElements") + public Integer totalElements; + + @JsonProperty("totalPages") + public Integer totalPages; + + @JsonProperty("numberOfElements") + public Integer numberOfElements; + + /** 当前页码,0 基(与订单 / 库存列表同口径)。 */ + @JsonProperty("number") + public Integer number; + + @JsonProperty("size") + public Integer size; + + @JsonProperty("last") + public Boolean last; + } + + /** + * 一个入库计划。 + * + *

字段名与类型都照抄文档与示例;不确定类型的一律用 String 接。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class InboundPlan { + + /** 仓 code。 */ + @JsonProperty("orgWarehouseCode") + public String orgWarehouseCode; + + /** 项目名称。 */ + @JsonProperty("lineName") + public String lineName; + + /** 库存类型:可能回 {@code "0"} / {@code "1"} 或中文「可售库存」。 */ + @JsonProperty("inventoryType") + public String inventoryType; + + /** 库存类型名(示例里有,字段表没列)。 */ + @JsonProperty("inventoryTypeName") + public String inventoryTypeName; + + /** 入库计划单号(仓方单号)。 */ + @JsonProperty("inboundPlanOrderNo") + public String inboundPlanOrderNo; + + /** 单据状态:数字码的字符串形式(如 {@code "70"})或中文名。 */ + @JsonProperty("inboundPlanOrderStatus") + public String inboundPlanOrderStatus; + + /** 状态名(示例里有,字段表没列)。 */ + @JsonProperty("inboundPlanOrderStatusName") + public String inboundPlanOrderStatusName; + + /** 来源单号(我们下发的 orderNo)。 */ + @JsonProperty("sourceNo") + public String sourceNo; + + @JsonProperty("shipmentId") + public String shipmentId; + @JsonProperty("referenceId") + public String referenceId; + @JsonProperty("shipmentNo") + public String shipmentNo; + + /** 关联单号。 */ + @JsonProperty("associatedOrderNo") + public String associatedOrderNo; + + /** 预计到仓日期(示例里有字段表没列的两个日期)。 */ + @JsonProperty("expectArriveDate") + public String expectArriveDate; + @JsonProperty("predictionShipDate") + public String predictionShipDate; + @JsonProperty("estimateArriveTime") + public String estimateArriveTime; + @JsonProperty("actualArriveTime") + public String actualArriveTime; + @JsonProperty("firstReceptionDate") + public String firstReceptionDate; + + /** 首次接收时刻(示例里有)。 */ + @JsonProperty("firstReceptionTime") + public String firstReceptionTime; + /** 到仓时刻(示例里有)。 */ + @JsonProperty("warehouseArriveDate") + public String warehouseArriveDate; + /** 完成时间(示例里有)。 */ + @JsonProperty("completeAt") + public String completeAt; + /** 创建 / 更新时间(示例里有)。 */ + @JsonProperty("createdAt") + public String createdAt; + @JsonProperty("updatedAt") + public String updatedAt; + + @JsonProperty("shipperName") + public String shipperName; + @JsonProperty("shipperAddress") + public String shipperAddress; + @JsonProperty("shipperContact") + public String shipperContact; + @JsonProperty("shipperPhone") + public String shipperPhone; + + /** 货物形态:{@code container} 集装箱 / {@code truck} 卡车(示例里也可能是数字)。 */ + @JsonProperty("goodsType") + public String goodsType; + + /** 各规格柜数与柜号。 */ + @JsonProperty("gpQuantity20") + public String gpQuantity20; + @JsonProperty("gpCartonNo20") + public String gpCartonNo20; + @JsonProperty("gpQuantity40") + public String gpQuantity40; + @JsonProperty("gpCartonNo40") + public String gpCartonNo40; + @JsonProperty("hqQuantity40") + public String hqQuantity40; + @JsonProperty("hqCartonNo40") + public String hqCartonNo40; + @JsonProperty("hqQuantity45") + public String hqQuantity45; + @JsonProperty("hqCartonNo45") + public String hqCartonNo45; + + /** 纸箱数。 */ + @JsonProperty("cartonQty") + public String cartonQty; + + /** 计划 / 装箱 / 接收数量。 */ + @JsonProperty("planQty") + public Integer planQty; + @JsonProperty("packedQty") + public Integer packedQty; + @JsonProperty("receivedQty") + public Integer receivedQty; + + /** 总重量(KG)/ 总体积(CBM)。 */ + @JsonProperty("totalWeight") + public Double totalWeight; + @JsonProperty("totalVolume") + public Double totalVolume; + + /** 实际发运日期。 */ + @JsonProperty("actualShipDate") + public String actualShipDate; + + /** 总纸箱重(KG)/ 总纸箱体积(CBM)。 */ + @JsonProperty("cartonTotalWeight") + public Double cartonTotalWeight; + @JsonProperty("cartonTotalVolume") + public Double cartonTotalVolume; + + /** 纸箱 Label 标签文件地址。 */ + @JsonProperty("packingLabelUrl") + public String packingLabelUrl; + + @JsonProperty("remark") + public String remark; + + /** 异常状态码 / 异常信息。 */ + @JsonProperty("errorStatus") + public String errorStatus; + @JsonProperty("errorMessage") + public String errorMessage; + + /** 标签生成状态。 */ + @JsonProperty("labelCreateStatus") + public String labelCreateStatus; + + /** 是否短收:0 否 / 1 是。 */ + @JsonProperty("isShortReceipt") + public String isShortReceipt; + + /** 产品明细。 */ + @JsonProperty("planProductDetailParamList") + public List planProductDetailParamList; + + /** 接收入库信息(实际收货单)。 */ + @JsonProperty("inboundOrderList") + public List inboundOrderList; + + /** 产品明细行。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ProductDetail { + + @JsonProperty("sku") + public String sku; + @JsonProperty("qty") + public Integer qty; + @JsonProperty("qtyPacked") + public Integer qtyPacked; + @JsonProperty("qtyReceived") + public Integer qtyReceived; + @JsonProperty("qtyReceivedSaleable") + public Integer qtyReceivedSaleable; + @JsonProperty("qtyReceivedUnsaleable") + public Integer qtyReceivedUnsaleable; + } + + /** + * 实际收货单。 + * + *

{@code inboundOrderStatus} 的码表与计划单不同: + * 0 草稿 / 70 已完成 / 90 已关闭。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class InboundOrderInfo { + + @JsonProperty("inboundOrderNo") + public String inboundOrderNo; + @JsonProperty("sourceNo") + public String sourceNo; + @JsonProperty("inboundOrderStatus") + public String inboundOrderStatus; + @JsonProperty("confirmedAt") + public String confirmedAt; + @JsonProperty("qty") + public Integer qty; + @JsonProperty("remark") + public String remark; + @JsonProperty("inboundOrderItemList") + public List inboundOrderItemList; + + /** 收货单明细行。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class InboundOrderItem { + + @JsonProperty("inboundOrderNo") + public String inboundOrderNo; + @JsonProperty("sku") + public String sku; + @JsonProperty("qty") + public Integer qty; + } + } + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianInboundStatus.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianInboundStatus.java new file mode 100644 index 0000000..694b6f4 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianInboundStatus.java @@ -0,0 +1,106 @@ +package common.ecommerce.hengjian.enums; + +import common.ecommerce.warehouse.enums.InboundStatus; + +/** + * 恒健入库计划单状态。 + * + *

两套码表要分清:

+ *
    + *
  • 列表接口({@code getInboundPlanPage})的过滤参数 + * {@code inboundPlanOrderStatusList} 用数字码: + * 0 草稿 / 5 待审核 / 6 审核拒回 / 8 待装箱 / 10 待发货 / 15 待接收 / + * 20 待入库 / 25 入库中 / 70 已完成 / 100 已取消。
  • + *
  • 详情与列表响应的 {@code inboundPlanOrderStatus} 回的是 + * 上面这些数字的字符串形式(示例里 {@code "70"}),偶尔也可能是中文名。
  • + *
+ *

所以 {@link #of(String)} 同时认数字串与中文名;两者都对不上归 {@link #UNKNOWN}。

+ * + *

不是 {@code inboundOrderList[].inboundOrderStatus}——那是入库单 + * (实际收货单)的状态,码表是 0 草稿 / 70 已完成 / 90 已关闭,与计划单不同。 + * 两者不能混用。

+ */ +public enum HengjianInboundStatus { + + /** 0 草稿。 */ + DRAFT("0", "草稿", InboundStatus.DRAFT), + /** 5 待审核。 */ + PENDING_REVIEW("5", "待审核", InboundStatus.PENDING_REVIEW), + /** 6 审核拒回。 */ + // 注意:core 叫 REJECTED(审核拒绝),这里是「拒回」,语义相同 + REJECTED("6", "审核拒回", InboundStatus.REJECTED), + /** 8 待装箱。 */ + PENDING_PACKING("8", "待装箱", InboundStatus.PENDING_PACKING), + /** 10 待发货。 */ + PENDING_SHIPMENT("10", "待发货", InboundStatus.PENDING_SHIPMENT), + /** 15 待接收(货未到仓)。 */ + PENDING_RECEIVING("15", "待接收", InboundStatus.IN_TRANSIT), + /** 20 待入库(已收货,待上架)。 */ + PENDING_STORAGE("20", "待入库", InboundStatus.PENDING_STORAGE), + /** 25 入库中(上架中)。 */ + STORING("25", "入库中", InboundStatus.STORING), + /** 70 已完成。 */ + COMPLETED("70", "已完成", InboundStatus.COMPLETED), + /** 100 已取消。 */ + CANCELLED("100", "已取消", InboundStatus.CANCELLED), + /** 无法识别。 */ + UNKNOWN(null, null, InboundStatus.UNKNOWN); + + private final String rawCode; + private final String rawName; + private final InboundStatus core; + + HengjianInboundStatus(String rawCode, String rawName, InboundStatus core) { + this.rawCode = rawCode; + this.rawName = rawName; + this.core = core; + } + + /** 仓方数字码(字符串形式);UNKNOWN 为 null。 */ + public String rawCode() { + return rawCode; + } + + /** 仓方中文名;UNKNOWN 为 null。 */ + public String rawName() { + return rawName; + } + + /** 下发给列表接口时用的数字码;UNKNOWN 返回 null。 */ + public Integer codeForQuery() { + return rawCode == null ? null : Integer.valueOf(rawCode); + } + + public InboundStatus toCore() { + return core; + } + + /** + * 仓方原值 → 平台枚举。 + * + *

先按数字串精确匹配,再按中文名精确匹配;都认不出归 {@link #UNKNOWN},不猜。

+ */ + public static HengjianInboundStatus of(String raw) { + if (raw == null) { + return UNKNOWN; + } + String s = raw.trim(); + if (s.isEmpty()) { + return UNKNOWN; + } + for (HengjianInboundStatus v : values()) { + if (v == UNKNOWN) { + continue; + } + if (s.equals(v.rawCode) || s.equals(v.rawName)) { + return v; + } + } + return UNKNOWN; + } + + /** 仓方原值 → 底层状态。 */ + public static InboundStatus toCore(String raw) { + return of(raw).toCore(); + } +} 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 d7b4e59..8d44180 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,15 +74,6 @@ 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() { diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryTest.java new file mode 100644 index 0000000..99254cc --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryTest.java @@ -0,0 +1,341 @@ +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.Page; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.hengjian.enums.HengjianInboundStatus; +import common.ecommerce.warehouse.enums.InboundStatus; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundOrderBatch; +import common.ecommerce.warehouse.model.InboundQuery; +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 java.util.List; + +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 getInboundPlanInfo})与列表({@code getInboundPlanPage})契约测试。 + */ +class HengjianInboundQueryTest { + + 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 HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + /** 文档示例的详情结构。 */ + private static final String DETAIL_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取入库信息成功\",\"data\":{" + + "\"orgWarehouseCode\":\"EFCA\",\"lineName\":\"Default\"," + + "\"inventoryType\":\"可售库存\"," + + "\"inboundPlanOrderNo\":\"IP25062700001\"," + + "\"inboundPlanOrderStatus\":\"70\"," + + "\"inboundPlanOrderStatusName\":\"已完成\"," + + "\"sourceNo\":\"IB-1\",\"shipmentId\":\"\",\"referenceId\":\"\"," + + "\"goodsType\":\"container\"," + + "\"gpQuantity20\":1,\"gpCartonNo20\":\"TEST1234567\"," + + "\"cartonQty\":3,\"planQty\":10,\"packedQty\":8,\"receivedQty\":9," + + "\"totalWeight\":0.01,\"totalVolume\":0.0," + + "\"estimateArriveTime\":\"2025-06-27\"," + + "\"actualArriveTime\":null," + + "\"firstReceptionTime\":\"2025-06-27 02:58:05\"," + + "\"createdAt\":\"2025-06-27 02:46:04\"," + + "\"updatedAt\":\"2025-08-14 02:09:07\"," + + "\"shipperName\":\"发货人\",\"shipperAddress\":\"地址\"," + + "\"packingLabelUrl\":\"https://cdn/label.pdf\"," + + "\"planProductDetailParamList\":[" + + "{\"sku\":\"TEST1\",\"qty\":10,\"qtyPacked\":8,\"qtyReceived\":9," + + "\"qtyReceivedSaleable\":7,\"qtyReceivedUnsaleable\":2}]," + + "\"inboundOrderList\":[{\"inboundOrderNo\":\"IO20250627000001\"," + + "\"sourceNo\":\"G2506270000001\",\"inboundOrderStatus\":70," + + "\"confirmedAt\":\"2025-06-27 02:58:05\",\"qty\":9," + + "\"inboundOrderItemList\":[{\"inboundOrderNo\":\"IO20250627000001\"," + + "\"sku\":\"TEST1\",\"qty\":9}]}]}}"; + + private static RecordingTransport detailing() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_GET, req -> Responses.ok(DETAIL_BODY)); + } + + // ---------------------------------------------------------------- 详情 + + @Test + void getPostsOrderNo() { + RecordingTransport transport = detailing(); + adapter(transport).get(CTX, "IB-1"); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inbound/getInboundPlanInfo", + transport.lastDataRequest().url()); + assertEquals("{\"orderNo\":\"IB-1\"}", transport.lastDataRequest().body()); + } + + /** 状态码:{@code "70"} → 已完成。 */ + @Test + void getMapsCoreFields() { + InboundOrder order = adapter(detailing()).get(CTX, "IB-1"); + + assertEquals("IB-1", order.inboundRequestNo(), "来源单号优先作为业务键"); + assertEquals("IP25062700001", order.providerInboundId(), "仓方计划单号"); + assertEquals("EFCA", order.warehouseCode()); + assertEquals(InboundStatus.COMPLETED, order.status()); + assertEquals("70", order.rawStatus()); + assertEquals("已完成", order.rawStatusName()); + assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider()); + assertEquals(0, order.inventoryType(), "「可售库存」归一成 0"); + assertEquals(3, order.boxCount()); + assertEquals(10, order.plannedQuantity()); + assertEquals(8, order.packedQuantity()); + assertEquals(9, order.receivedQuantity()); + assertEquals(Instant.parse("2025-06-27T02:46:04Z"), order.createdAt()); + assertEquals(Instant.parse("2025-08-14T02:09:07Z"), order.modifiedAt()); + assertEquals(Instant.parse("2025-06-27T02:58:05Z"), order.receivedAt()); + assertEquals("https://cdn/label.pdf", order.packingLabelUrl()); + } + + /** 柜型:有数量的规格才建 ContainerInfo。 */ + @Test + void getMapsContainers() { + InboundOrder order = adapter(detailing()).get(CTX, "IB-1"); + + assertEquals(1, order.containers().size()); + InboundOrder.ContainerInfo gp20 = order.containers().get(0); + assertEquals(InboundOrder.ContainerType.GP20, gp20.type()); + assertEquals(Integer.valueOf(1), gp20.quantity()); + assertEquals("TEST1234567", gp20.containerNo()); + } + + /** 产品明细:可售 / 不可售分开。 */ + @Test + void getMapsProductLines() { + InboundOrder order = adapter(detailing()).get(CTX, "IB-1"); + + assertEquals(1, order.lines().size()); + assertEquals("TEST1", order.lines().get(0).providerSku()); + assertEquals(10, order.lines().get(0).plannedQuantity()); + assertEquals(8, order.lines().get(0).packedQuantity()); + assertEquals(9, order.lines().get(0).receivedQuantity()); + assertEquals(7, order.lines().get(0).receivedSaleableQuantity()); + assertEquals(2, order.lines().get(0).receivedUnsaleableQuantity()); + } + + /** 可售 / 不可售都没给时按可售兜底(总数一致,不编造拆分)。 */ + @Test + void splitsReceivedQuantityWhenDetailMissing() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_GET, req -> Responses.ok( + "{\"code\":200,\"data\":{\"inboundPlanOrderNo\":\"IP1\"," + + "\"sourceNo\":\"IB-1\",\"inboundPlanOrderStatus\":\"70\"," + + "\"planProductDetailParamList\":[" + + "{\"sku\":\"S1\",\"qty\":5,\"qtyReceived\":3}]}}")); + + InboundOrder order = adapter(transport).get(CTX, "IB-1"); + assertEquals(3, order.lines().get(0).receivedSaleableQuantity()); + assertEquals(0, order.lines().get(0).receivedUnsaleableQuantity()); + } + + /** 实际收货单落成 INBOUNDED 阶段批次。 */ + @Test + void getMapsReceivedOrdersAsBatches() { + InboundOrder order = adapter(detailing()).get(CTX, "IB-1"); + + assertEquals(1, order.batches().size()); + InboundOrderBatch batch = order.batches().get(0); + assertEquals(InboundOrderBatch.Phase.INBOUNDED, batch.phase()); + assertEquals("TEST1", batch.providerSku()); + assertEquals(9, batch.quantity()); + assertEquals("IO20250627000001", batch.cartonNo(), "收货单号作为箱唛号"); + assertNull(batch.inventoryType(), "收货单层面没有库存类型细分,保持未知"); + } + + /** 来源单号缺失时退回仓单号,不让构造期失败。 */ + @Test + void fallsBackToPlanNoWhenSourceNoMissing() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_GET, req -> Responses.ok( + "{\"code\":200,\"data\":{\"inboundPlanOrderNo\":\"IP1\"," + + "\"sourceNo\":null,\"inboundPlanOrderStatus\":\"70\"," + + "\"planProductDetailParamList\":[]}}")); + + InboundOrder order = adapter(transport).get(CTX, "IP1"); + assertEquals("IP1", order.inboundRequestNo()); + assertEquals("IP1", order.providerInboundId()); + } + + /** data 为空表示查不到:返回 null,不造空单。 */ + @Test + void returnsNullWhenDataMissing() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_GET, req -> Responses.ok( + "{\"code\":200,\"message\":\"未找到\"}")); + + assertNull(adapter(transport).get(CTX, "IP-NONE")); + } + + // ---------------------------------------------------------------- 状态枚举 + + /** 文档里的 11 个值都要映射对,且数字与中文名都能认。 */ + @Test + void allDocumentedStatusesMap() { + assertEquals(InboundStatus.DRAFT, HengjianInboundStatus.toCore("0")); + assertEquals(InboundStatus.PENDING_REVIEW, HengjianInboundStatus.toCore("5")); + assertEquals(InboundStatus.REJECTED, HengjianInboundStatus.toCore("6")); + assertEquals(InboundStatus.PENDING_PACKING, HengjianInboundStatus.toCore("8")); + assertEquals(InboundStatus.PENDING_SHIPMENT, HengjianInboundStatus.toCore("10")); + assertEquals(InboundStatus.IN_TRANSIT, HengjianInboundStatus.toCore("15")); + assertEquals(InboundStatus.PENDING_STORAGE, HengjianInboundStatus.toCore("20")); + assertEquals(InboundStatus.STORING, HengjianInboundStatus.toCore("25")); + assertEquals(InboundStatus.COMPLETED, HengjianInboundStatus.toCore("70")); + assertEquals(InboundStatus.CANCELLED, HengjianInboundStatus.toCore("100")); + // 中文名同样能认 + assertEquals(InboundStatus.COMPLETED, HengjianInboundStatus.toCore("已完成")); + } + + @Test + void unknownStatusIsNotGuessed() { + assertEquals(InboundStatus.UNKNOWN, HengjianInboundStatus.toCore("999")); + assertEquals(InboundStatus.UNKNOWN, HengjianInboundStatus.toCore(null)); + } + + // ---------------------------------------------------------------- 列表 + + private static final String PAGE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取入库信息成功\",\"data\":{" + + "\"totalElements\":1,\"totalPages\":1,\"numberOfElements\":1," + + "\"number\":0,\"size\":10,\"last\":true,\"content\":[{" + + "\"orgWarehouseCode\":\"EFCA\",\"inboundPlanOrderNo\":\"IP1\"," + + "\"sourceNo\":\"IB-1\",\"inboundPlanOrderStatus\":\"70\"," + + "\"inventoryType\":\"0\",\"planQty\":10,\"receivedQty\":10}]}}"; + + private static RecordingTransport paging() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_PAGE, req -> Responses.ok(PAGE_BODY)); + } + + @Test + void queryPostsPagingAndFilters() { + RecordingTransport transport = paging(); + adapter(transport).queryInbounds(CTX, InboundQuery.builder() + .warehouseCode("EFCA") + .status(InboundStatus.COMPLETED) + .sourceNo("IB-1") + .createdRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")) + .pageSize(10) + .build()); + String body = transport.lastDataRequest().body(); + + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inbound/getInboundPlanPage", + transport.lastDataRequest().url()); + assertTrue(body.contains("\"page\":1"), body); + assertTrue(body.contains("\"size\":10"), body); + assertTrue(body.contains("\"inboundPlanOrderStatusList\":[70]"), body); + assertTrue(body.contains("\"sourceNoList\":[\"IB-1\"]"), body); + assertTrue(body.contains("\"orgWarehouseCodeList\":[\"EFCA\"]"), body); + assertTrue(body.contains("\"btCreatedDate\":\"2026-10-01 ~ 2026-10-31\""), body); + } + + /** 没给仓时用账户仓,避免跨仓混账。 */ + @Test + void pageFallsBackToAccountWarehouse() { + RecordingTransport transport = paging(); + adapter(transport).queryInbounds(CTX, InboundQuery.builder().pageSize(10).build()); + + assertTrue(transport.lastDataRequest().body().contains("\"orgWarehouseCodeList\":[\"EFCA\"]")); + } + + /** 认不出的状态不能猜:直接拒绝。 */ + @Test + void rejectsUnmappableStatus() { + RecordingTransport transport = paging(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).queryInbounds(CTX, InboundQuery.builder() + .status(InboundStatus.RECEIVING).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 页大小超上限拒绝,不静默截断。 */ + @Test + void rejectsPageSizeAboveLimit() { + RecordingTransport transport = paging(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).queryInbounds(CTX, + InboundQuery.builder().pageSize(HengjianConstants.INBOUND_PAGE_SIZE_MAX + 1).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 游标版入口把游标当页码。 */ + @Test + void cursorBasedQueryUsesPageNumber() { + RecordingTransport transport = paging(); + adapter(transport).query(CTX, "3"); + + assertTrue(transport.lastDataRequest().body().contains("\"page\":3")); + } + + @Test + void pageMapsRows() { + Page page = adapter(paging()).queryInbounds(CTX, + InboundQuery.builder().warehouseCode("EFCA").build()); + + assertEquals(1, page.size()); + assertFalse(page.hasMore()); + assertEquals("IB-1", page.items().get(0).inboundRequestNo()); + assertEquals(10, page.items().get(0).plannedQuantity()); + assertEquals(10, page.items().get(0).receivedQuantity()); + } + + /** 未到末页时给出下一页游标(响应 number 0 基 → 下一页 = number+2)。 */ + @Test + void pageAdvancesCursor() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_PAGE, req -> Responses.ok( + "{\"code\":200,\"data\":{\"last\":false,\"number\":0," + + "\"content\":[{\"inboundPlanOrderNo\":\"IP1\",\"sourceNo\":\"IB-1\"," + + "\"inboundPlanOrderStatus\":\"70\"}]}}")); + + Page page = adapter(transport).queryInbounds(CTX, + InboundQuery.builder().warehouseCode("EFCA").pageSize(1).build()); + + assertTrue(page.hasMore()); + assertEquals("2", page.nextCursor()); + } + + /** 空页不是错误。 */ + @Test + void emptyPageIsNotAnError() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INBOUND_PAGE, req -> Responses.ok( + "{\"code\":200,\"data\":{\"last\":true,\"numberOfElements\":0,\"content\":[]}}")); + + assertTrue(adapter(transport).queryInbounds(CTX, + InboundQuery.builder().warehouseCode("EFCA").build()).items().isEmpty()); + } + + /** 时间窗必须成对:构造期就挡。 */ + @Test + void queryRequiresPairedDateRange() { + assertThrows(IllegalArgumentException.class, + () -> InboundQuery.builder() + .createdRange(LocalDate.parse("2026-10-01"), null).build()); + } +}