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} |
+ * | 方法 | POST | GET |
+ * | 过滤 | 只按 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));
+ }
+}