diff --git a/README.md b/README.md index 427d6f8..36b8902 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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水) | 依赖方向: ``` @@ -380,14 +380,16 @@ common.ecommerce │ HengjianAdapterFactory / HengjianDirectoryMapper / │ HengjianProductMapper / HengjianOutboundMapper / │ HengjianOrderMapper / HengjianTrackingChangeMapper / - │ HengjianFeeMapper / HengjianEstimateMapper + │ HengjianFeeMapper / HengjianEstimateMapper / + │ HengjianInventoryMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / │ HengjianCancelOrderDtos / HengjianTrackingChangeDtos / │ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos / │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos / - │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos + │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos / + │ HengjianInventoryDtos / HengjianInventoryMovementDtos ├── 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 b06f3d8..75a485d 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -75,7 +75,10 @@ | 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ | | 14 | 运费测算 | `POST /v2/api/shipping/calculate` | `FEE_ESTIMATE` | ✅ | | 15 | 地址属性识别 | `POST /v2/api/shipping/addressClassification` | `ADDRESS_CLASSIFICATION` | ✅ | -| 16 | 回调 | — | — | ❌ 文档无回调页 | +| 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 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -372,6 +375,49 @@ 入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标, 预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。 +### 库存(`INVENTORY_QUERY`)—— 已接入 + +恒健有**两个**库存接口,能力不同,统一模型只有一个 `query()`,按「给了什么」分流: + +| 条件 | 接口 | 分页 | 过滤维度 | +|---|---|---|---| +| 给 `providerSkus` | `POST /v1/inventory/getInventory` | **不分页** | 只按 SKU | +| 只给 `warehouseCodes` | `GET /v2/inventory/get_inventory_by_page` | 分页,rows ≤ 500 | 只按仓 | +| 两个都给 | — | — | **拒绝**:恒健没有这种接口 | +| 都不给 | — | — | **拒绝**:不能因为缺省就退化成整仓全量 | +| 给 `updatedAfter` | — | — | **拒绝**:恒健不支持增量,策略是 `FULL_PULL_DIFF` | + +其它被拒绝的过滤项:`inventoryType` / `includeZeroStock`(恒健库存接口没有这两个参数)。 + +**字段名两套写法**:分页接口的文档字段表写 `snake_case`(`warehouse_code`), +同一页的返回示例却写 `camelCase`(`warehouseCode`)。DTO 用 `@JsonAlias` 同时接住两种, +不多花钱但能防一次真机翻车。 + +**`data` 形状两套**:分页接口的字段表说 `data` 是对象,返回示例却是数组。 +适配器用 `JsonNode` 判形状后分流,两种都接住。 + +**数量字段类型不一致**:`inventoryTransport` / `inventoryCurrent` 文档标 STRING, +`inventoryAvailable` 标 INTEGER。统一按文本转 int。 + +**`updatedAt` 必须有值**:快照时间是对账对齐的依据,仓方没给时**报错**而不是填 +`EPOCH`——填 EPOCH 会让「物理库存 vs 逻辑库存」比对得出错误结论。 + +**同步策略**:`FULL_PULL_DIFF`。两个库存接口都没有 `updatedAfter` 入参, +只能全量拉后自己做差异比对。流水接口虽然能按日期查,但那是**变动明细**、不是余额, +不能拿来重建当前库存。 + +#### 库存变动流水(`/v1/inventory/task/query`) + +- **必填**(真机确认):`skus`(非空数组)、`beginDateTime`、`endDateTime`(`yyyy-MM-dd`)。 + 缺任一项回 `MethodArgumentNotValidException` 并列出所有缺的字段。 +- **日期跨度 ≤ 30 个自然日(含首尾)**:`10-01~10-30` 合法,`10-01~10-31` 非法 + (真机回「查询日期最多包含30个自然日」)。适配器按含首尾口径算,正好 30 天放行。 +- **rows ≤ 100**(文档明写 1~100),超过拒绝不截断。 +- 这是**流水**不是余额:`changeQty` 按原值返回、**不转正负号**,方向看 `inventoryChangeType`。 +- 单行缺 `sku` 或 `createTime` 时**跳过该行**而不是整页失败——流水是明细,跳过一行比 + 拿不到整页有用;缺多少行由调用方对账发现。 +- core 新增 `InventoryMovement` / `InventoryMovementQuery` / `queryMovements()`。 + ### 运费测算与地址属性 —— 已接入 #### 运费测算(`/v2/api/shipping/calculate`) @@ -478,7 +524,8 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型 │ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型 │ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射 - │ │ └── HengjianEstimateMapper.java 运费测算 + 地址属性映射 + │ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射 + │ │ └── HengjianInventoryMapper.java 库存两个接口 + 变动流水 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -509,13 +556,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态 ├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过 ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射 + ├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射 ├── 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` 全部通过(180 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(203 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java index e63502e..dd8dd34 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java @@ -39,6 +39,23 @@ public interface InventoryCapable extends WarehouseAdapter { common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY); } + /** + * 查库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。 + * + *

与 {@link #query} 是两回事:那个给当前余额,这个给变动明细。 + * 流水是按业务单据产生的,带一堆单号,用于对账与追溯。

+ * + *

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

+ * + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不提供流水查询 + */ + default Page queryMovements( + WarehouseContext ctx, common.ecommerce.warehouse.model.InventoryMovementQuery query) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY); + } + /** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */ default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) { throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovement.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovement.java new file mode 100644 index 0000000..e310a23 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovement.java @@ -0,0 +1,277 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.WarehouseProvider; + +import java.time.Instant; + +/** + * 一条库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。 + * + *

这是流水,不是余额:{@link #changeQuantity()} 是单笔变动量, + * 按仓方原值返回、不转正负号(方向看 {@link #changeType()}), + * 也不代表当前库存。当前库存用 {@link InventorySnapshot}。

+ * + *

流水是按业务单据产生的,所以带一堆单号: + * {@link #planOrderNo()} / {@link #sourceNo()} / {@link #executeOrderNo()} / + * {@link #platformOrderNo()} / {@link #saleOrderNo()} / {@link #poNumber()}。 + * 各仓填哪几个不一样,未填的为 null。

+ */ +public final class InventoryMovement { + + private final WarehouseProvider sourceProvider; + private final String warehouseCode; + private final String providerSku; + /** 卖家 / 店铺侧 SKU;仓方未给为 null。 */ + private final String sellerSku; + /** 商品名;仓方未给为 null。 */ + private final String productName; + /** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ + private final Integer inventoryType; + + /** 单据类型,仓方原值(如「采购入库」「销售出库」);不归一,跨仓口径不同。 */ + private final String documentType; + /** 变动方向,仓方原值(如「入库」「出库」)。 */ + private final String changeType; + /** 单笔变动量(正数,方向看 {@link #changeType()})。 */ + private final int changeQuantity; + /** 调整原因;非调整类流水为 null。 */ + private final String adjustReason; + + private final String planOrderNo; + private final String sourceNo; + private final String executeOrderNo; + private final String platformOrderNo; + private final String saleOrderNo; + private final String poNumber; + + /** 流水创建时间(UTC)。 */ + private final Instant createdAt; + /** 业务操作时间(UTC);仓方未给为 null。 */ + private final Instant businessAt; + + private InventoryMovement(Builder b) { + this.sourceProvider = b.sourceProvider; + this.warehouseCode = require(b.warehouseCode, "warehouseCode"); + this.providerSku = require(b.providerSku, "providerSku"); + this.sellerSku = b.sellerSku; + this.productName = b.productName; + this.inventoryType = b.inventoryType; + this.documentType = b.documentType; + this.changeType = b.changeType; + this.changeQuantity = b.changeQuantity; + this.adjustReason = b.adjustReason; + this.planOrderNo = b.planOrderNo; + this.sourceNo = b.sourceNo; + this.executeOrderNo = b.executeOrderNo; + this.platformOrderNo = b.platformOrderNo; + this.saleOrderNo = b.saleOrderNo; + this.poNumber = b.poNumber; + this.createdAt = java.util.Objects.requireNonNull(b.createdAt, "createdAt"); + this.businessAt = b.businessAt; + } + + public static Builder builder() { + return new Builder(); + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + public String warehouseCode() { + return warehouseCode; + } + + public String providerSku() { + return providerSku; + } + + public String sellerSku() { + return sellerSku; + } + + public String productName() { + return productName; + } + + /** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ + public Integer inventoryType() { + return inventoryType; + } + + /** 单据类型原值。 */ + public String documentType() { + return documentType; + } + + /** 变动方向原值(入库 / 出库)。 */ + public String changeType() { + return changeType; + } + + /** 单笔变动量;方向看 {@link #changeType()}。 */ + public int changeQuantity() { + return changeQuantity; + } + + public String adjustReason() { + return adjustReason; + } + + public String planOrderNo() { + return planOrderNo; + } + + public String sourceNo() { + return sourceNo; + } + + public String executeOrderNo() { + return executeOrderNo; + } + + public String platformOrderNo() { + return platformOrderNo; + } + + public String saleOrderNo() { + return saleOrderNo; + } + + public String poNumber() { + return poNumber; + } + + public Instant createdAt() { + return createdAt; + } + + public Instant businessAt() { + return businessAt; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private WarehouseProvider sourceProvider; + private String warehouseCode; + private String providerSku; + private String sellerSku; + private String productName; + private Integer inventoryType; + private String documentType; + private String changeType; + private int changeQuantity; + private String adjustReason; + private String planOrderNo; + private String sourceNo; + private String executeOrderNo; + private String platformOrderNo; + private String saleOrderNo; + private String poNumber; + private Instant createdAt; + private Instant businessAt; + + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public Builder warehouseCode(String v) { + this.warehouseCode = v; + return this; + } + + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + public Builder sellerSku(String v) { + this.sellerSku = v; + return this; + } + + public Builder productName(String v) { + this.productName = v; + return this; + } + + /** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ + public Builder inventoryType(Integer v) { + this.inventoryType = v; + return this; + } + + /** 单据类型原值。 */ + public Builder documentType(String v) { + this.documentType = v; + return this; + } + + /** 变动方向原值。 */ + public Builder changeType(String v) { + this.changeType = v; + return this; + } + + public Builder changeQuantity(int v) { + this.changeQuantity = v; + return this; + } + + public Builder adjustReason(String v) { + this.adjustReason = v; + return this; + } + + public Builder planOrderNo(String v) { + this.planOrderNo = v; + return this; + } + + public Builder sourceNo(String v) { + this.sourceNo = v; + return this; + } + + public Builder executeOrderNo(String v) { + this.executeOrderNo = v; + return this; + } + + public Builder platformOrderNo(String v) { + this.platformOrderNo = v; + return this; + } + + public Builder saleOrderNo(String v) { + this.saleOrderNo = v; + return this; + } + + public Builder poNumber(String v) { + this.poNumber = v; + return this; + } + + public Builder createdAt(Instant v) { + this.createdAt = v; + return this; + } + + public Builder businessAt(Instant v) { + this.businessAt = v; + return this; + } + + public InventoryMovement build() { + return new InventoryMovement(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovementQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovementQuery.java new file mode 100644 index 0000000..9a8d5b2 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovementQuery.java @@ -0,0 +1,148 @@ +package common.ecommerce.warehouse.model; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 库存变动流水查询条件。 + * + *

与 {@link InventoryQuery} 的区别:那个查当前库存余额,这个查流水 + * (每条是一次入库 / 出库 / 调整)。流水必须限定日期区间——不限定会拉到全部历史。

+ * + *

各仓约束不同(恒健要求 SKU + 日期区间都必填、区间 ≤ 30 天), + * 由适配器在拼请求时按自己的协议校验。

+ */ +public final class InventoryMovementQuery { + + private final List providerSkus; + private final List warehouseCodes; + /** 日期区间起点(含当天,UTC 流水创建时间)。 */ + private final LocalDate startDate; + /** 日期区间终点(含当天)。 */ + private final LocalDate endDate; + private final int pageSize; + private final String cursor; + + private InventoryMovementQuery(Builder b) { + if (b.startDate == null || b.endDate == null) { + throw new IllegalArgumentException("startDate and endDate are required"); + } + if (b.endDate.isBefore(b.startDate)) { + throw new IllegalArgumentException("endDate must not be earlier than startDate"); + } + this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus)); + this.warehouseCodes = Collections.unmodifiableList(new ArrayList(b.warehouseCodes)); + this.startDate = b.startDate; + this.endDate = b.endDate; + this.pageSize = b.pageSize; + this.cursor = b.cursor; + } + + public static Builder builder() { + return new Builder(); + } + + /** 产品 SKU 列表;不可变。 */ + public List providerSkus() { + return providerSkus; + } + + /** 仓 code 列表;空表示用账户配置的仓(按仓支持的仓)。 */ + public List warehouseCodes() { + return warehouseCodes; + } + + /** 日期区间起点(含当天)。 */ + public LocalDate startDate() { + return startDate; + } + + /** 日期区间终点(含当天)。 */ + public LocalDate endDate() { + return endDate; + } + + public int pageSize() { + return pageSize; + } + + /** 分页游标;null 表示第一页。 */ + public String cursor() { + return cursor; + } + + /** 翻页时只改游标。 */ + public Builder toBuilder() { + return builder() + .skus(providerSkus) + .warehouseCodes(warehouseCodes) + .dateRange(startDate, endDate) + .pageSize(pageSize) + .cursor(cursor); + } + + public static final class Builder { + + private final List providerSkus = new ArrayList(); + private final List warehouseCodes = new ArrayList(); + private LocalDate startDate; + private LocalDate endDate; + private int pageSize = 100; + private String cursor; + + public Builder sku(String v) { + if (v != null && !v.trim().isEmpty()) { + this.providerSkus.add(v.trim()); + } + return this; + } + + public Builder skus(List v) { + if (v != null) { + for (String one : v) { + sku(one); + } + } + return this; + } + + 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 dateRange(LocalDate start, LocalDate end) { + this.startDate = start; + this.endDate = end; + return this; + } + + public Builder pageSize(int v) { + this.pageSize = v; + return this; + } + + public Builder cursor(String v) { + this.cursor = v; + return this; + } + + public InventoryMovementQuery build() { + return new InventoryMovementQuery(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 146fecc..b049525 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 @@ -408,6 +408,24 @@ public final class WarehouseOperations { () -> ((InventoryCapable) adapter).queryAges(ctx, query)); } + /** + * 查库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。 + * + *

只读。与 {@link #query(InventoryQuery)} 不同:那个给当前余额,这个给变动明细。

+ */ + public Page movements( + final common.ecommerce.warehouse.model.InventoryMovementQuery query) { + require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.inventory.movements", + CallSupport.params("skuCount", query.providerSkus().size(), + "startDate", query.startDate(), + "endDate", query.endDate(), + "pageSize", query.pageSize(), + "cursor", query.cursor()), + p -> p.size(), + () -> ((InventoryCapable) adapter).queryMovements(ctx, query)); + } + /** 查库存。 */ public Page query(InventoryQuery query) { require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class); 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 5d5a91a..7b8d55c 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 @@ -155,6 +155,46 @@ public final class HengjianConstants { "/v2/api/shipping/addressClassification"; /** + * 按 SKU 查库存({@code POST},不分页)。 + * + *

真机确认:{@code skus} 必填且不能是空数组。

+ */ + public static final String PATH_INVENTORY_BY_SKU = "/v1/inventory/getInventory"; + + /** + * 批量查库存({@code GET},分页)。 + * + *

真机确认 {@code warehouseCodes} 是必填的 List 参数; + * {@code page / rows / sidx / sort} 也必填,{@code rows} 默认最高 500。

+ */ + public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page"; + + /** + * 库存变动流水({@code POST},分页)。 + * + *

真机确认 {@code skus} / {@code beginDateTime} / {@code endDateTime} 都必填; + * 日期跨度最多 30 个自然日。

+ */ + public static final String PATH_INVENTORY_MOVEMENTS = "/v1/inventory/task/query"; + + /** 批量库存分页默认页大小;文档:默认最高 500。 */ + public static final int INVENTORY_PAGE_ROWS_DEFAULT = 100; + + /** 批量库存分页单页上限;文档明写 500。 */ + public static final int INVENTORY_PAGE_ROWS_MAX = 500; + + /** 库存流水分页上限;文档明写 1~100。 */ + public static final int INVENTORY_MOVEMENT_ROWS_MAX = 100; + + /** + * 库存流水的日期跨度上限(自然日)。 + * + *

文档与真机一致:{@code 2026-10-01}~{@code 2026-10-30} 合法, + * {@code ~2026-10-31} 不合法(真机回 {@code 查询日期最多包含30个自然日})。

+ */ + public static final int INVENTORY_MOVEMENT_MAX_DAYS = 30; + + /** * {@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 5d5d129..1efa93b 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 @@ -6,6 +6,8 @@ import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos; 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.HengjianInventoryMovementDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; import common.ecommerce.hengjian.dto.HengjianOrderListDtos; @@ -26,6 +28,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.InventoryCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingChangeCapable; @@ -36,6 +39,7 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.AddressType; import common.ecommerce.warehouse.enums.CancelEligibility; +import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.TrackingChangeHandleType; import common.ecommerce.warehouse.enums.WarehouseCapability; @@ -50,6 +54,10 @@ 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.InventoryMovement; +import common.ecommerce.warehouse.model.InventoryMovementQuery; +import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; @@ -84,7 +92,7 @@ import java.util.Map; */ public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, - WarehouseFeeEstimateCapable, AddressClassificationCapable { + WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; @@ -101,6 +109,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_FEE_OPERATION = "warehouse.fee.operation"; private static final String OP_FEE_ESTIMATE = "warehouse.fee.estimate"; 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"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -133,6 +143,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.OUTBOUND, WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.TRACKING_CHANGE, + WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.ADDRESS_CLASSIFICATION, @@ -140,6 +151,108 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 库存 + + /** + * 库存同步策略。 + * + *

恒健的两个库存接口都不支持按更新时间增量:按 SKU 的全量返回、 + * 按仓的分页返回,都没有 {@code updatedAfter} 入参。所以策略是 + * {@link InventorySyncStrategy#FULL_PULL_DIFF}——宿主全量拉后自己做差异比对。

+ * + *

流水接口({@code movements})能按日期查,但那是变动明细, + * 不是余额,不能拿来重建当前库存。

+ */ + @Override + public InventorySyncStrategy syncStrategy() { + return InventorySyncStrategy.FULL_PULL_DIFF; + } + + /** + * 查库存。 + * + *

恒健有两个接口,统一模型只有一个方法,按「给了什么」分流:

+ *
    + *
  • 给了 SKU → {@code POST /v1/inventory/getInventory}(不分页,一次返回全部匹配行);
  • + *
  • 只给仓 → {@code GET /v2/inventory/get_inventory_by_page}(分页)。
  • + *
+ * + *

两者都给的场景(按仓 + SKU 过滤)恒健没有对应接口,本地拒绝—— + * 静默丢掉一个条件会让调用方以为过滤生效了。

+ * + *

{@code updatedAfter} 恒健不支持,传了就拒绝(同上理由)。

+ */ + @Override + public Page query(WarehouseContext ctx, InventoryQuery query) { + if (query.updatedAfter() != null) { + throw validation(ctx, OP_INVENTORY_QUERY, + "hengjian inventory has no updatedAfter filter; full-pull and diff instead"); + } + boolean bySku = !query.providerSkus().isEmpty(); + boolean byWarehouse = !query.warehouseCodes().isEmpty(); + if (bySku && byWarehouse) { + throw validation(ctx, OP_INVENTORY_QUERY, + "hengjian has two separate inventory APIs: one filters by sku, " + + "the other by warehouseCodes; combining both is not supported"); + } + if (query.inventoryType() != null || query.includeZeroStock() != null) { + throw validation(ctx, OP_INVENTORY_QUERY, + "hengjian inventory has no inventoryType / includeZeroStock filter"); + } + if (!bySku && !byWarehouse) { + // 什么都不给会退化成「整仓全量」;这必须是调用方显式意愿,不能由缺省触发 + throw validation(ctx, OP_INVENTORY_QUERY, + "hengjian inventory query requires providerSkus or warehouseCodes"); + } + return bySku ? queryBySku(ctx, query) : queryByPage(ctx, query); + } + + /** 按 SKU 查(不分页)。 */ + private Page queryBySku(WarehouseContext ctx, InventoryQuery query) { + HengjianInventoryDtos.QueryBySkuRequest body = HengjianInventoryMapper.toBySkuRequest(query); + String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_BY_SKU, body, OP_INVENTORY_QUERY); + List rows = + json.listAt(raw, "data", HengjianInventoryDtos.InventoryRow.class); + return Page.last(HengjianInventoryMapper.toSnapshots(rows, fallbackWarehouse(ctx))); + } + + /** 按仓分页查。 */ + private Page queryByPage(WarehouseContext ctx, InventoryQuery query) { + Map> params = + HengjianInventoryMapper.toPageParams(query, ctx.providerWarehouseId()); + rateLimiter.acquire(HengjianConstants.PATH_INVENTORY_PAGE, HengjianConstants.PERMITS_PER_SECOND); + HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), + HengjianConstants.PATH_INVENTORY_PAGE, params, ctx.secret(), ctx, OP_INVENTORY_QUERY); + String raw = HengjianEnvelope.of(transport.execute(req), json, OP_INVENTORY_QUERY, + ctx.warehouseCode(), ctx.requestId()).body(); + int rows = HengjianInventoryMapper.rowsOf(query.pageSize()); + return HengjianInventoryMapper.toPage(json.nodeAt(raw, "data"), + fallbackWarehouse(ctx), rows, json); + } + + /** + * 库存变动流水({@code POST /v1/inventory/task/query})。 + * + *

真机确认:SKU 与日期区间都必填,区间 ≤ 30 个自然日,rows 1~100。

+ */ + @Override + public Page queryMovements(WarehouseContext ctx, InventoryMovementQuery query) { + HengjianInventoryMovementDtos.QueryRequest body = + HengjianInventoryMapper.toMovementRequest(query); + String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_MOVEMENTS, body, OP_INVENTORY_MOVEMENTS); + HengjianInventoryMovementDtos.QueryResponse resp = + json.fromJson(raw, HengjianInventoryMovementDtos.QueryResponse.class); + int rows = HengjianInventoryMapper.movementRowsOf(query.pageSize()); + return HengjianInventoryMapper.toMovementPage( + resp == null ? null : resp.data, fallbackWarehouse(ctx), rows, query.cursor()); + } + + /** 仓编码兜底:优先仓方编码,其次 OMS 仓编码。 */ + private static String fallbackWarehouse(WarehouseContext ctx) { + String provider = trimToNull(ctx.providerWarehouseId()); + return provider == null ? ctx.warehouseCode() : provider; + } + // ------------------------------------------------------------------ 试算与地址属性 /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java new file mode 100644 index 0000000..55e2fc2 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java @@ -0,0 +1,366 @@ +package common.ecommerce.hengjian.adapter; + +import com.fasterxml.jackson.databind.JsonNode; +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.hengjian.dto.HengjianInventoryDtos; +import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InventoryMovement; +import common.ecommerce.warehouse.model.InventoryMovementQuery; +import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; + +import java.math.BigDecimal; +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.time.temporal.ChronoUnit; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 恒健库存报文映射(库存查询 / 批量分页 / 变动流水)。 + * + *

两个库存接口的差异

+ * + * + * + * + * + *
{@code getInventory}{@code get_inventory_by_page}
方法POSTGET
过滤只按 SKU只按仓({@code warehouseCodes} 必填)
分页不分页分页,rows 上限 500
+ *

统一模型是一个 {@code query()},所以:给了 SKU 走按 SKU 查(无分页); + * 只给仓走分页查。两条路都给的场景(按仓 + SKU 过滤)恒健没有对应接口, + * 本地拒绝而不是静默丢掉一个条件。

+ * + *

响应形状

+ *

分页接口的文档字段表说 {@code data} 是对象,返回示例却是数组; + * 这里用 JsonNode 判形状后分流,两种都接住。

+ */ +public final class HengjianInventoryMapper { + + /** 时间格式(文档未标时区,按 UTC 解析,与订单接口同口径假设)。 */ + private static final DateTimeFormatter TIME_FORMAT = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + private HengjianInventoryMapper() { + } + + // ================================================================ 库存查询 + + /** 按 SKU 查库存的请求;SKU 必填。 */ + public static HengjianInventoryDtos.QueryBySkuRequest toBySkuRequest(InventoryQuery query) { + List skus = query.providerSkus(); + if (skus.isEmpty()) { + throw new IllegalArgumentException( + "hengjian inventory-by-sku query requires at least one sku"); + } + HengjianInventoryDtos.QueryBySkuRequest req = new HengjianInventoryDtos.QueryBySkuRequest(); + req.skus = new ArrayList(skus); + return req; + } + + /** + * 批量查库存的 GET 参数。 + * + *

{@code warehouseCodes} 真机必填:调用方指定优先,否则用账户仓; + * 都没有就拒绝,避免把整个租户的库存拉下来。

+ * + * @throws IllegalArgumentException 没有仓 code + */ + public static Map> toPageParams(InventoryQuery query, + String defaultWarehouseCode) { + List codes = query.warehouseCodes(); + if (codes.isEmpty() && defaultWarehouseCode != null && !defaultWarehouseCode.trim().isEmpty()) { + codes = java.util.Collections.singletonList(defaultWarehouseCode.trim()); + } + if (codes.isEmpty()) { + throw new IllegalArgumentException( + "hengjian inventory page query requires warehouseCodes; " + + "none given and account has none"); + } + Map> params = new LinkedHashMap>(); + params.put("warehouseCodes", new ArrayList(codes)); + params.put("page", java.util.Collections.singletonList(String.valueOf(pageOf(query.cursor())))); + params.put("rows", java.util.Collections.singletonList(String.valueOf(rowsOf(query.pageSize())))); + params.put("sidx", java.util.Collections.singletonList(HengjianConstants.ORDER_LIST_DEFAULT_SIDX)); + params.put("sort", java.util.Collections.singletonList(HengjianConstants.ORDER_LIST_DEFAULT_SORT)); + return params; + } + + /** 页码:游标是字符串化页码,空游标表示第 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 inventory cursor must be a page number, got " + v); + } + } + + /** 页大小:未指定用默认;超过文档明写的 500 时拒绝(不静默截断)。 */ + static int rowsOf(int requested) { + if (requested <= 0) { + return HengjianConstants.INVENTORY_PAGE_ROWS_DEFAULT; + } + if (requested > HengjianConstants.INVENTORY_PAGE_ROWS_MAX) { + throw new IllegalArgumentException( + "hengjian inventory page rows must not exceed " + + HengjianConstants.INVENTORY_PAGE_ROWS_MAX + ", got " + requested); + } + return requested; + } + + /** 行 → 统一快照。 */ + public static InventorySnapshot toSnapshot(HengjianInventoryDtos.InventoryRow row, + String fallbackWarehouseCode) { + String warehouseCode = trimToNull(row.warehouseCode); + String sku = trimToNull(row.sku); + if (sku == null) { + throw new IllegalArgumentException("hengjian inventory row has no sku"); + } + Instant asOf = parseTime(row.updatedAt); + if (asOf == null) { + // 快照时间必须能对齐;仓方没给就拒绝,而不是填 EPOCH 让对账误判 + throw new IllegalArgumentException( + "hengjian inventory row for sku " + sku + " has no updatedAt"); + } + return InventorySnapshot.builder() + .warehouseCode(warehouseCode == null ? fallbackWarehouseCode : warehouseCode) + .providerSku(sku) + .available(intOfNumber(row.inventoryAvailable)) + .reserved(intOfNumber(row.inventoryReserved)) + .inTransit(intOfText(row.inventoryTransport)) + .onHand(intOfText(row.inventoryCurrent)) + .inventoryType(row.inventoryType == null ? 0 : row.inventoryType) + .asOfUtc(asOf) + .productName(trimToNull(row.lineName)) + .build(); + } + + /** 解析分页响应:{@code data} 可能是对象(有 content)也可能是数组。 */ + public static Page toPage(JsonNode data, String fallbackWarehouseCode, + int requestedRows, JacksonJsonCodec json) { + if (data == null || data.isNull() || data.isMissingNode()) { + return Page.last(new ArrayList()); + } + List rows = new ArrayList(); + boolean last; + Integer pageNumber = null; + if (data.isArray()) { + // 文档示例的形状:data 直接是数组(没有分页信息,按末页处理) + for (JsonNode node : data) { + rows.add(convert(node, json)); + } + last = true; + } else { + JsonNode content = data.get("content"); + if (content != null && content.isArray()) { + for (JsonNode node : content) { + rows.add(convert(node, json)); + } + } + JsonNode lastNode = data.get("last"); + JsonNode numberNode = data.get("number"); + pageNumber = numberNode == null || numberNode.isNull() ? null : numberNode.asInt(); + last = lastNode == null || lastNode.isNull() + ? rows.size() < requestedRows + : lastNode.asBoolean(); + } + List out = new ArrayList(rows.size()); + for (HengjianInventoryDtos.InventoryRow row : rows) { + if (row != null) { + out.add(toSnapshot(row, fallbackWarehouseCode)); + } + } + if (last) { + return Page.last(out); + } + // 响应 number 是 0 基,而请求的 page 是 1 基:当前第 number 页(0 基) + // 对应请求的 page = number+1,所以下一页的请求值 = number+2 + int next = (pageNumber == null ? 0 : pageNumber) + 2; + return Page.of(out, String.valueOf(next)); + } + + /** 非分页接口:{@code data} 是数组。 */ + public static List toSnapshots(List rows, + String fallbackWarehouseCode) { + List out = new ArrayList(); + if (rows == null) { + return out; + } + for (HengjianInventoryDtos.InventoryRow row : rows) { + if (row != null) { + out.add(toSnapshot(row, fallbackWarehouseCode)); + } + } + return out; + } + + // ================================================================ 变动流水 + + /** + * 统一流水条件 → 恒健请求。 + * + * @throws IllegalArgumentException SKU 为空,或日期跨度超 30 天 + */ + public static HengjianInventoryMovementDtos.QueryRequest toMovementRequest( + InventoryMovementQuery query) { + if (query.providerSkus().isEmpty()) { + throw new IllegalArgumentException( + "hengjian inventory movements require at least one sku"); + } + // 文档/真机口径是「最多包含 30 个自然日」,起止都含: + // 10-01~10-30 合法(30 天),10-01~10-31 不合法(31 天) + long inclusiveDays = ChronoUnit.DAYS.between(query.startDate(), query.endDate()) + 1; + if (inclusiveDays > HengjianConstants.INVENTORY_MOVEMENT_MAX_DAYS) { + throw new IllegalArgumentException( + "hengjian inventory movements window must not exceed " + + HengjianConstants.INVENTORY_MOVEMENT_MAX_DAYS + + " calendar days (inclusive), got " + inclusiveDays); + } + HengjianInventoryMovementDtos.QueryRequest req = + new HengjianInventoryMovementDtos.QueryRequest(); + req.skus = new ArrayList(query.providerSkus()); + req.page = pageOf(query.cursor()); + req.rows = movementRowsOf(query.pageSize()); + req.beginDateTime = query.startDate().toString(); + req.endDateTime = query.endDate().toString(); + return req; + } + + /** 流水页大小:文档 1~100;超过即拒绝。 */ + static int movementRowsOf(int requested) { + if (requested <= 0) { + return HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX; + } + if (requested > HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX) { + throw new IllegalArgumentException( + "hengjian inventory movements rows must not exceed " + + HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX + ", got " + requested); + } + return requested; + } + + /** 流水行 → 统一模型。 */ + public static InventoryMovement toMovement(HengjianInventoryMovementDtos.MovementRow row, + String fallbackWarehouseCode) { + String warehouseCode = trimToNull(row.warehouseCode); + String sku = trimToNull(row.sku); + if (sku == null) { + throw new IllegalArgumentException("hengjian inventory movement has no sku"); + } + Instant createdAt = parseTime(row.createTime); + if (createdAt == null) { + throw new IllegalArgumentException( + "hengjian inventory movement for sku " + sku + " has no createTime"); + } + return InventoryMovement.builder() + .sourceProvider(WarehouseProvider.HENGJIAN) + .warehouseCode(warehouseCode == null ? fallbackWarehouseCode : warehouseCode) + .providerSku(sku) + .sellerSku(trimToNull(row.sellerSku)) + .productName(trimToNull(row.lineName)) + .inventoryType(row.inventoryType) + .documentType(trimToNull(row.documentType)) + .changeType(trimToNull(row.inventoryChangeType)) + .changeQuantity(row.changeQty == null ? 0 : row.changeQty) + .adjustReason(trimToNull(row.adjustReason)) + .planOrderNo(trimToNull(row.planOrderNo)) + .sourceNo(trimToNull(row.sourceNo)) + .executeOrderNo(trimToNull(row.executeOrderNo)) + .platformOrderNo(trimToNull(row.platformOrderNo)) + .saleOrderNo(trimToNull(row.saleOrderNo)) + .poNumber(trimToNull(row.poNumber)) + .createdAt(createdAt) + .businessAt(parseTime(row.businessTime)) + .build(); + } + + /** 流水分页 → 统一 Page。 */ + public static Page toMovementPage(HengjianInventoryMovementDtos.PageData data, + String fallbackWarehouseCode, + int requestedRows, String cursor) { + if (data == null) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(); + if (data.content != null) { + for (HengjianInventoryMovementDtos.MovementRow row : data.content) { + if (row == null) { + continue; + } + // 单行数据不完整(缺 sku / createTime)时跳过而不是整页失败: + // 流水是明细,跳过一行比拿不到整页更有用。缺的行数由调用方对账发现。 + try { + out.add(toMovement(row, fallbackWarehouseCode)); + } catch (IllegalArgumentException ignored) { + // skip + } + } + } + boolean last = data.last != null ? data.last + : (data.content == null || data.content.size() < requestedRows); + // 有下一页时给出页码游标,否则 Page.of(..., null) 会被当成末页 + return last ? Page.last(out) + : Page.of(out, String.valueOf(pageOf(cursor) + 1)); + } + + // ================================================================ 工具 + + /** JsonNode → 行模型;{@code @JsonAlias} 会同时接 snake_case 与 camelCase。 */ + static HengjianInventoryDtos.InventoryRow convert(JsonNode node, JacksonJsonCodec json) { + return json.mapper().convertValue(node, HengjianInventoryDtos.InventoryRow.class); + } + + static Instant parseTime(String value) { + String v = trimToNull(value); + if (v == null) { + return null; + } + try { + return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC); + } catch (DateTimeParseException e) { + try { + return Instant.parse(v); + } catch (DateTimeParseException ignored) { + return null; + } + } + } + + /** 数量:文档有的字段标 STRING,有的标 INTEGER;统一按文本转。 */ + static int intOfText(String value) { + String v = trimToNull(value); + if (v == null) { + return 0; + } + try { + return new BigDecimal(v).intValue(); + } catch (NumberFormatException e) { + return 0; + } + } + + static int intOfNumber(Integer value) { + return value == null ? 0 : value; + } + + 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/HengjianInventoryDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryDtos.java new file mode 100644 index 0000000..f627fac --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryDtos.java @@ -0,0 +1,124 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonAlias; +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.util.List; + +/** + * 恒健报文结构:库存查询(两个接口共用行模型)。 + * + *

两个接口的字段命名不一致,且文档与示例互相矛盾(真机/文档双向核对):

+ *
    + *
  • {@code /v1/inventory/getInventory}:请求 {@code {skus:[...]}},不分页; + * 行是 camelCase({@code warehouseCode} / {@code inventoryAvailable})。
  • + *
  • {@code /v2/inventory/get_inventory_by_page}:GET,分页; + * 字段表写 snake_case({@code warehouse_code} / {@code inventory_available}), + * 但同一页的返回示例又是 camelCase。
  • + *
+ *

因此行字段用 {@link JsonAlias} 同时接两种写法——不多花钱,却能防一次真机翻车。

+ * + *

{@code data} 的形状两个接口也不一致:分页接口的字段表说 {@code data} 是对象 + * (含 {@code content} / {@code totalElements}),返回示例却是数组。 + * 适配器用 JsonNode 判形状后分流,见 {@code HengjianInventoryMapper}。

+ */ +public final class HengjianInventoryDtos { + + private HengjianInventoryDtos() { + } + + /** 按 SKU 查询的请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class QueryBySkuRequest { + + /** 产品 SKU 列表;真机确认必填且不能为空数组。 */ + public List skus; + } + + /** 一个库存行(两个接口共用)。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class InventoryRow { + + /** 仓库 code。 */ + @JsonProperty("warehouseCode") + @JsonAlias("warehouse_code") + public String warehouseCode; + + /** 项目名称。 */ + @JsonProperty("lineName") + @JsonAlias("line_name") + public String lineName; + + /** 产品 SKU。 */ + @JsonProperty("sku") + public String sku; + + /** 库存类型:0 可售 / 1 不可售。 */ + @JsonProperty("inventoryType") + @JsonAlias("inventory_type") + public Integer inventoryType; + + /** 可用库存。 */ + @JsonProperty("inventoryAvailable") + @JsonAlias("inventory_available") + public Integer inventoryAvailable; + + /** 预留库存。 */ + @JsonProperty("inventoryReserved") + @JsonAlias("inventory_reserved") + public Integer inventoryReserved; + + /** + * 在途库存。 + * + *

文档标 STRING、示例给数字;用 String 接住,解析时再转 int。

+ */ + @JsonProperty("inventoryTransport") + @JsonAlias("inventory_transport") + public String inventoryTransport; + + /** 当前总库存;同样按 String 接。 */ + @JsonProperty("inventoryCurrent") + @JsonAlias("inventory_current") + public String inventoryCurrent; + + /** + * 最近更新时间。 + * + *

文档没写时区。示例形如 {@code 2017-03-24 02:19:56}。按 UTC 解析, + * 待真机确认(与订单时间同口径假设)。

+ */ + @JsonProperty("updatedAt") + @JsonAlias("updated_at") + public String updatedAt; + } + + /** 分页信封。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PageData { + + @JsonProperty("content") + public List content; + + @JsonProperty("totalElements") + public Integer totalElements; + + @JsonProperty("totalPages") + public Integer totalPages; + + /** 当前页码,0 基(与订单列表同口径)。 */ + @JsonProperty("number") + public Integer number; + + @JsonProperty("size") + public Integer size; + + @JsonProperty("last") + public Boolean last; + + @JsonProperty("numberOfElements") + public Integer numberOfElements; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryMovementDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryMovementDtos.java new file mode 100644 index 0000000..8b458c5 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryMovementDtos.java @@ -0,0 +1,189 @@ +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/inventory/task/query})。 + * + *

真机确认的必填项:{@code skus}(非空数组)、{@code beginDateTime}、 + * {@code endDateTime}({@code yyyy-MM-dd})。缺任一项回 + * {@code MethodArgumentNotValidException} 并列出所有缺的字段。

+ * + *

真机确认的约束:日期范围最多 30 个自然日,超了回 + * {@code 查询日期最多包含30个自然日}。

+ * + *

这是流水,不是库存余额:{@code changeQty} 是单笔变动量, + * 按原值返回、不转正负号,也不代表当前库存。

+ */ +public final class HengjianInventoryMovementDtos { + + private HengjianInventoryMovementDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class QueryRequest { + + /** 产品 SKU 列表;必填,元素不能为 null / 空串 / 纯空格。 */ + public List skus; + + /** 页码,从 1 开始;不传默认 1。 */ + public Integer page; + + /** 每页条数,1~100;不传默认 10。 */ + public Integer rows; + + /** 开始日期 {@code yyyy-MM-dd}(UTC 流水创建时间,含当天);必填。 */ + public String beginDateTime; + + /** 结束日期 {@code yyyy-MM-dd}(含当天);必填,不能早于开始日期。 */ + public String endDateTime; + } + + /** 响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class QueryResponse { + + @JsonProperty("status") + public Integer status; + + @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("size") + public Integer size; + + @JsonProperty("first") + public Boolean first; + + @JsonProperty("last") + public Boolean last; + } + + /** 一条库存流水。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class MovementRow { + + /** 仓库编码。 */ + @JsonProperty("warehouseCode") + public String warehouseCode; + + /** 项目名称。 */ + @JsonProperty("lineName") + public String lineName; + + /** 流水保存的渠道值。 */ + @JsonProperty("channel") + public String channel; + + /** 产品 SKU。 */ + @JsonProperty("sku") + public String sku; + + /** 卖家 SKU。 */ + @JsonProperty("sellerSku") + public String sellerSku; + + /** 产品类型:1 成品 / 2 配件 / 3 耗材。 */ + @JsonProperty("productType") + public Integer productType; + + /** 卖家 SKU 类型:简单产品 / 打包产品;无对应类型时为空。 */ + @JsonProperty("sellerSkuProductType") + public String sellerSkuProductType; + + /** 库存类型:0 可售 / 1 不可售。 */ + @JsonProperty("inventoryType") + public Integer inventoryType; + + /** 流水保存的计划编号;销售出库场景可能是销售订单内部 ID。 */ + @JsonProperty("planOrderNo") + public String planOrderNo; + + /** 流水保存的来源编号;可能是业务单号或组合编号。 */ + @JsonProperty("sourceNo") + public String sourceNo; + + /** 流水保存的执行单号。 */ + @JsonProperty("executeOrderNo") + public String executeOrderNo; + + /** 平台订单号;未关联到时为空。 */ + @JsonProperty("platformOrderNo") + public String platformOrderNo; + + /** 流水保存的销售 / 渠道订单号;与 {@link #platformOrderNo} 分别返回。 */ + @JsonProperty("saleOrderNo") + public String saleOrderNo; + + /** PO Number。 */ + @JsonProperty("poNumber") + public String poNumber; + + /** 单据类型中文描述,如采购入库 / 销售出库 / 调拨入库 / 库存调整出库。 */ + @JsonProperty("documentType") + public String documentType; + + /** 调整原因。 */ + @JsonProperty("adjustReason") + public String adjustReason; + + /** 库存变动方向:入库 / 出库。 */ + @JsonProperty("inventoryChangeType") + public String inventoryChangeType; + + /** 单笔流水数量;按原值返回,不转正负号,不代表当前库存余额。 */ + @JsonProperty("changeQty") + public Integer changeQty; + + /** 当前产品资料尺寸(cm)。 */ + @JsonProperty("length") + public java.math.BigDecimal length; + @JsonProperty("width") + public java.math.BigDecimal width; + @JsonProperty("height") + public java.math.BigDecimal height; + /** 当前产品资料重量(g)。 */ + @JsonProperty("weight") + public java.math.BigDecimal weight; + + /** 流水保存的销售类型。 */ + @JsonProperty("saleType") + public String saleType; + + /** 流水创建时间 {@code yyyy-MM-dd HH:mm:ss}。 */ + @JsonProperty("createTime") + public String createTime; + + /** 流水更新时间。 */ + @JsonProperty("updateTime") + public String updateTime; + + /** 流水业务操作时间。 */ + @JsonProperty("businessTime") + public String businessTime; + } +} 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 e095ad5..addc47d 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,13 @@ class HengjianAdapterTest { common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND)); } - /** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ + /** 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ @Test void undeclaredCapabilityIsRejected() { WarehouseSdk sdk = sdk(); assertThrows(WarehouseUnsupportedCapabilityException.class, - () -> sdk.warehouses(WH, conn()).inventory().query(null)); + () -> sdk.warehouses(WH, conn()).inbound().get("IB-1")); } /** 能力矩阵查询本身可用(不触发真实 API)。 */ @@ -88,8 +88,9 @@ class HengjianAdapterTest { void capabilityQueryIsOffline() { HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + // 库存已接入;入库 / 退货仍是未接状态 assertTrue(!adapter.capabilities().contains( - common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY)); + common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND)); } @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 61699b9..a812e89 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())); } - /** 未声明的能力位仍然被门面挡住(INVENTORY_QUERY 还没接)。 */ + /** 未声明的能力位仍然被门面挡住(INBOUND 还没接)。 */ @Test void undeclaredCapabilityIsRejectedByFacade() { WarehouseSdk sdk = WarehouseSdk.builder() @@ -504,6 +504,6 @@ class HengjianCreateOrderTest { HengjianConstants.TEST_BASE_URL, ChannelSecret.builder().appSecret("t").build(), ZoneOffset.UTC)) - .inventory().query(null)); + .inbound().get("IB-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 dde4c2d..3ecb7cb 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 @@ -234,8 +234,8 @@ class HengjianDirectoryTest { assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); - // 库存 / 入库 / 退货 / 回调都还没接:声明了就必须有实现 - assertTrue(!adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); + // 入库 / 退货 / 回调都还没接:声明了就必须有实现 assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND)); 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/HengjianInventoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java new file mode 100644 index 0000000..6cfe969 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java @@ -0,0 +1,402 @@ +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.warehouse.enums.InventorySyncStrategy; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InventoryMovement; +import common.ecommerce.warehouse.model.InventoryMovementQuery; +import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import org.junit.jupiter.api.Test; + +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.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 库存三个接口的契约测试: + * 按 SKU 查({@code /v1/inventory/getInventory})、 + * 按仓分页查({@code /v2/inventory/get_inventory_by_page})、 + * 变动流水({@code /v1/inventory/task/query})。 + */ +class HengjianInventoryTest { + + 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", java.time.Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC)); + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + // ================================================================ 按 SKU 查 + + private static final String BY_SKU_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":[" + + "{\"warehouseCode\":\"EFCA\",\"lineName\":\"Klineo\",\"sku\":\"K150002Y\"," + + "\"inventoryType\":0,\"inventoryAvailable\":12,\"inventoryReserved\":3," + + "\"inventoryTransport\":0,\"inventoryCurrent\":15," + + "\"updatedAt\":\"2026-11-15 02:19:56\"}]}"; + + private static RecordingTransport bySku() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INVENTORY_BY_SKU, req -> Responses.ok(BY_SKU_BODY)); + } + + @Test + void bySkuPostsSkus() { + RecordingTransport transport = bySku(); + adapter(transport).query(CTX, InventoryQuery.builder().sku("K150002Y").build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inventory/getInventory", + transport.lastDataRequest().url()); + assertTrue(transport.lastDataRequest().body().contains("\"skus\":[\"K150002Y\"]")); + } + + @Test + void bySkuMapsSnapshot() { + List items = adapter(bySku()) + .query(CTX, InventoryQuery.builder().sku("K150002Y").build()).items(); + + assertEquals(1, items.size()); + InventorySnapshot s = items.get(0); + assertEquals("EFCA", s.warehouseCode()); + assertEquals("K150002Y", s.providerSku()); + assertEquals(12, s.available()); + assertEquals(3, s.reserved()); + assertEquals(0, s.inTransit()); + assertEquals(15, s.onHand()); + assertEquals(0, s.inventoryType()); + // 文档未标时区,按 UTC 解析(与订单接口同口径假设) + assertEquals(Instant.parse("2026-11-15T02:19:56Z"), s.asOfUtc()); + } + + /** 按 SKU 查不分页:结果是末页。 */ + @Test + void bySkuIsNotPaginated() { + Page page = adapter(bySku()) + .query(CTX, InventoryQuery.builder().sku("K150002Y").build()); + + assertFalse(page.hasMore()); + } + + /** 两个过滤条件都没给时本地拒绝,不退化成「整仓全量」。 */ + @Test + void requiresSkuOrWarehouse() { + RecordingTransport transport = bySku(); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).query(CTX, InventoryQuery.builder().build())); + + assertTrue(ex.getMessage().contains("providerSkus or warehouseCodes"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + // ================================================================ 按仓分页查 + + /** 文档字段表写 snake_case,示例却给 camelCase —— 两种都要接住。 */ + private static final String PAGE_SNAKE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{" + + "\"last\":true,\"numberOfElements\":1,\"number\":0,\"size\":100," + + "\"content\":[{\"warehouse_code\":\"EFCA\",\"line_name\":\"项目A\"," + + "\"sku\":\"SKU-A\",\"inventory_type\":1,\"inventory_available\":5," + + "\"inventory_reserved\":1,\"inventory_transport\":0," + + "\"inventory_current\":6,\"updated_at\":\"2026-11-15 01:00:00\"}]}}"; + + private static RecordingTransport byPage(String body) { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INVENTORY_PAGE, req -> Responses.ok(body)); + } + + @Test + void byPageSendsRequiredQueryParams() { + RecordingTransport transport = byPage(PAGE_SNAKE_BODY); + adapter(transport).query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); + + assertEquals("GET", transport.lastDataRequest().method()); + String url = transport.lastDataRequest().url(); + assertTrue(url.contains("/v2/inventory/get_inventory_by_page?"), url); + assertTrue(url.contains("warehouseCodes=EFCA"), url); + assertTrue(url.contains("page=1"), url); + assertTrue(url.contains("sidx=" + HengjianConstants.ORDER_LIST_DEFAULT_SIDX), url); + assertTrue(url.contains("sort=" + HengjianConstants.ORDER_LIST_DEFAULT_SORT), url); + } + + /** 没给仓时用账户仓。 */ + @Test + void byPageFallsBackToAccountWarehouse() { + RecordingTransport transport = byPage(PAGE_SNAKE_BODY); + adapter(transport).query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); + + assertTrue(transport.lastDataRequest().url().contains("warehouseCodes=EFCA")); + } + + /** snake_case 与 camelCase 两种字段名都要能反序列化。 */ + @Test + void byPageAcceptsSnakeCaseFields() { + List items = adapter(byPage(PAGE_SNAKE_BODY)) + .query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()).items(); + + assertEquals(1, items.size()); + InventorySnapshot s = items.get(0); + assertEquals("EFCA", s.warehouseCode()); + assertEquals("SKU-A", s.providerSku()); + assertEquals(1, s.inventoryType()); + assertEquals(5, s.available()); + assertEquals(1, s.reserved()); + assertEquals(6, s.onHand()); + assertEquals(Instant.parse("2026-11-15T01:00:00Z"), s.asOfUtc()); + } + + /** 文档示例的 data 是数组(不是分页对象):也要接住,按末页处理。 */ + @Test + void byPageAcceptsArrayShapedData() { + RecordingTransport transport = byPage( + "{\"code\":200,\"message\":\"ok\",\"data\":[{\"warehouseCode\":\"EFCA\"," + + "\"sku\":\"SKU-A\",\"inventoryAvailable\":1,\"inventoryReserved\":0," + + "\"inventoryTransport\":0,\"inventoryCurrent\":1," + + "\"updatedAt\":\"2026-11-15 01:00:00\"}]}"); + + Page page = adapter(transport) + .query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); + + assertEquals(1, page.size()); + assertFalse(page.hasMore(), "数组形状没有分页信息,按末页处理"); + } + + /** 分页未到末页时给出下一页游标。 */ + @Test + void byPageAdvancesCursor() { + RecordingTransport transport = byPage( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":false,\"number\":0," + + "\"content\":[{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\"," + + "\"inventoryAvailable\":1,\"updatedAt\":\"2026-11-15 01:00:00\"}]}}"); + + Page page = adapter(transport) + .query(CTX, InventoryQuery.builder().warehouseCode("EFCA").pageSize(1).build()); + + assertTrue(page.hasMore()); + assertEquals("2", page.nextCursor()); + } + + /** 行数超过文档明写的 500 时拒绝,不静默截断。 */ + @Test + void byPageRejectsRowsAboveLimit() { + RecordingTransport transport = byPage(PAGE_SNAKE_BODY); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).query(CTX, + InventoryQuery.builder().warehouseCode("EFCA").pageSize(1000).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + // ================================================================ 分流与拒绝 + + /** 两个过滤条件都给:恒健没有这种接口,拒绝而不是丢掉一个。 */ + @Test + void rejectsSkuAndWarehouseTogether() { + RecordingTransport transport = bySku(); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).query(CTX, InventoryQuery.builder() + .sku("SKU-A").warehouseCode("EFCA").build())); + + assertTrue(ex.getMessage().contains("combining both"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 更新时间过滤恒健不支持:拒绝(策略是全量比对)。 */ + @Test + void rejectsUpdatedAfter() { + RecordingTransport transport = bySku(); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).query(CTX, InventoryQuery.builder() + .sku("SKU-A").updatedAfter(Instant.parse("2026-11-01T00:00:00Z")).build())); + + assertTrue(ex.getMessage().contains("updatedAfter"), ex.getMessage()); + } + + /** 库存类型 / 零库存过滤恒健都不支持:拒绝而不是静默忽略。 */ + @Test + void rejectsUnsupportedFilters() { + RecordingTransport t1 = bySku(); + assertThrows(RuntimeException.class, () -> adapter(t1).query(CTX, + InventoryQuery.builder().sku("SKU-A").inventoryType(1).build())); + + RecordingTransport t2 = bySku(); + assertThrows(RuntimeException.class, () -> adapter(t2).query(CTX, + InventoryQuery.builder().sku("SKU-A").includeZeroStock(true).build())); + } + + @Test + void syncStrategyIsFullPullDiff() { + assertEquals(InventorySyncStrategy.FULL_PULL_DIFF, + adapter(RecordingTransport.create()).syncStrategy()); + } + + // ================================================================ 变动流水 + + private static final String MOVEMENT_BODY = + "{\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{" + + "\"totalElements\":1,\"totalPages\":1,\"size\":10,\"first\":true,\"last\":true," + + "\"content\":[{\"warehouseCode\":\"EFCA\",\"lineName\":\"项目A\"," + + "\"channel\":\"CH-A\",\"sku\":\"SKU-A\",\"sellerSku\":\"SELLER-A\"," + + "\"productType\":1,\"inventoryType\":0,\"planOrderNo\":\"1001\"," + + "\"sourceNo\":\"1001-2001\",\"executeOrderNo\":\"DELIVER-2001\"," + + "\"platformOrderNo\":\"ORDER-1001\",\"saleOrderNo\":\"CHANNEL-ORDER-1001\"," + + "\"poNumber\":\"PO-1001\",\"documentType\":\"销售出库\",\"adjustReason\":null," + + "\"inventoryChangeType\":\"出库\",\"changeQty\":5," + + "\"createTime\":\"2026-10-10 09:00:00\"," + + "\"updateTime\":\"2026-10-10 09:00:00\"," + + "\"businessTime\":\"2026-10-09 18:00:00\"}]}}"; + + private static RecordingTransport movements() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok(MOVEMENT_BODY)); + } + + private static InventoryMovementQuery.Builder movementQuery() { + return InventoryMovementQuery.builder() + .sku("SKU-A") + .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-20")); + } + + @Test + void movementsPostRequiredFields() { + RecordingTransport transport = movements(); + adapter(transport).queryMovements(CTX, movementQuery().pageSize(10).build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inventory/task/query", + transport.lastDataRequest().url()); + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"skus\":[\"SKU-A\"]"), body); + assertTrue(body.contains("\"beginDateTime\":\"2026-10-01\""), body); + assertTrue(body.contains("\"endDateTime\":\"2026-10-20\""), body); + assertTrue(body.contains("\"page\":1"), body); + assertTrue(body.contains("\"rows\":10"), body); + } + + @Test + void movementsMapAllFields() { + List items = adapter(movements()) + .queryMovements(CTX, movementQuery().build()).items(); + + assertEquals(1, items.size()); + InventoryMovement m = items.get(0); + assertEquals(WarehouseProvider.HENGJIAN, m.sourceProvider()); + assertEquals("EFCA", m.warehouseCode()); + assertEquals("SKU-A", m.providerSku()); + assertEquals("SELLER-A", m.sellerSku()); + assertEquals("项目A", m.productName()); + assertEquals(Integer.valueOf(0), m.inventoryType()); + assertEquals("销售出库", m.documentType()); + assertEquals("出库", m.changeType()); + assertEquals(5, m.changeQuantity()); + assertEquals("1001", m.planOrderNo()); + assertEquals("1001-2001", m.sourceNo()); + assertEquals("DELIVER-2001", m.executeOrderNo()); + assertEquals("ORDER-1001", m.platformOrderNo()); + assertEquals("CHANNEL-ORDER-1001", m.saleOrderNo()); + assertEquals("PO-1001", m.poNumber()); + assertEquals(Instant.parse("2026-10-10T09:00:00Z"), m.createdAt()); + assertEquals(Instant.parse("2026-10-09T18:00:00Z"), m.businessAt()); + } + + /** 文档与真机都写:日期跨度最多 30 个自然日。 */ + @Test + void movementsRejectWindowOver30Days() { + RecordingTransport transport = movements(); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).queryMovements(CTX, InventoryMovementQuery.builder() + .sku("SKU-A") + .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")) + .build())); + + assertTrue(ex.getMessage().contains("30"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 正好 30 天要放行。 */ + @Test + void movementsAcceptExactly30Days() { + RecordingTransport transport = movements(); + adapter(transport).queryMovements(CTX, InventoryMovementQuery.builder() + .sku("SKU-A") + .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-30")) + .build()); + + assertEquals(1, transport.dataRequests().size()); + } + + @Test + void movementsRejectRowsAboveLimit() { + RecordingTransport transport = movements(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).queryMovements(CTX, + movementQuery().pageSize(500).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + @Test + void movementsRequireSkus() { + RecordingTransport transport = movements(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).queryMovements(CTX, + InventoryMovementQuery.builder() + .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-20")) + .build())); + } + + /** 单行数据不完整时跳过该行,不整页失败。 */ + @Test + void movementsSkipIncompleteRows() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,\"content\":[" + + "{\"warehouseCode\":\"EFCA\"}," + + "{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\"," + + "\"changeQty\":1,\"createTime\":\"2026-10-10 09:00:00\"}]}}")); + + List items = adapter(transport) + .queryMovements(CTX, movementQuery().build()).items(); + + assertEquals(1, items.size(), "缺 sku 的行应被跳过,另一行保留"); + } + + /** 未到末页时给出下一页游标。 */ + @Test + void movementsAdvanceCursor() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":false,\"content\":[" + + "{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\",\"changeQty\":1," + + "\"createTime\":\"2026-10-10 09:00:00\"}]}}")); + + Page page = adapter(transport).queryMovements(CTX, + movementQuery().pageSize(1).build()); + + assertTrue(page.hasMore()); + assertEquals("2", page.nextCursor()); + } + + @Test + void declaresInventoryCapability() { + assertTrue(adapter(RecordingTransport.create()).capabilities() + .contains(WarehouseCapability.INVENTORY_QUERY)); + } +}