Browse Source

feat(hengjian): 对接库存查询 / 批量分页 / 库存变动流水

三个接口真机均确认存在(无 token 时返回各自的 Unauthorized 文案,
与 404 对照组可区分)。

按 SKU 查 /v1/inventory/getInventory、批量分页 /v2/inventory/get_inventory_by_page
- 恒健有两个库存接口且能力不同,统一模型只有一个 query(),按条件分流:
  给 providerSkus 走按 SKU(不分页),只给 warehouseCodes 走分页
- 两个都给 → 拒绝(恒健无此接口);都不给 → 拒绝(不退化成整仓全量);
  给 updatedAfter / inventoryType / includeZeroStock → 拒绝(不支持)
- 分页接口 rows 上限 500(文档明写),超过拒绝不截断
- 字段名两套:字段表写 snake_case、示例写 camelCase,DTO 用 @JsonAlias 同时接住
- data 形状两套:对象(含 content)与数组,用 JsonNode 判形状后分流
- updatedAt 缺失时报错而非填 EPOCH——快照时间是对账对齐依据
- syncStrategy = FULL_PULL_DIFF:两个接口都没有增量入参

库存变动流水 /v1/inventory/task/query
- 真机确认 skus / beginDateTime / endDateTime 必填,缺项回 MethodArgumentNotValidException
- 日期跨度按「含首尾」口径算:10-01~10-30 合法(30 天),10-01~10-31 非法
- rows 上限 100(文档明写)
- 新增 core 模型 InventoryMovement / InventoryMovementQuery / queryMovements()
- changeQty 按原值保留不转符号;单据类型与变动方向保留仓方原文不归一
- 单行缺 sku / createTime 时跳过该行而非整页失败

验证:mvn test 全量通过,恒健 203 个用例(+23)通过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 5 days ago
parent
commit
d126757e80
  1. 8
      README.md
  2. 54
      docs-warehouse/hengjian/README.md
  3. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
  4. 277
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovement.java
  5. 148
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryMovementQuery.java
  6. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  7. 40
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  8. 115
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  9. 366
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInventoryMapper.java
  10. 124
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryDtos.java
  11. 189
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInventoryMovementDtos.java
  12. 7
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  13. 4
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java
  14. 4
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java
  15. 402
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInventoryTest.java

8
README.md

@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性) | | `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水) |
依赖方向: 依赖方向:
``` ```
@ -380,14 +380,16 @@ common.ecommerce
│ HengjianAdapterFactory / HengjianDirectoryMapper / │ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper / │ HengjianProductMapper / HengjianOutboundMapper /
│ HengjianOrderMapper / HengjianTrackingChangeMapper / │ HengjianOrderMapper / HengjianTrackingChangeMapper /
│ HengjianFeeMapper / HengjianEstimateMapper │ HengjianFeeMapper / HengjianEstimateMapper /
│ HengjianInventoryMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos /
│ HengjianCancelOrderDtos / HengjianTrackingChangeDtos / │ HengjianCancelOrderDtos / HengjianTrackingChangeDtos /
│ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos / │ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos /
│ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos / │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos /
│ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos /
│ HengjianInventoryDtos / HengjianInventoryMovementDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建 │ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter

54
docs-warehouse/hengjian/README.md

@ -75,7 +75,10 @@
| 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ | | 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ |
| 14 | 运费测算 | `POST /v2/api/shipping/calculate` | `FEE_ESTIMATE` | ✅ | | 14 | 运费测算 | `POST /v2/api/shipping/calculate` | `FEE_ESTIMATE` | ✅ |
| 15 | 地址属性识别 | `POST /v2/api/shipping/addressClassification` | `ADDRESS_CLASSIFICATION` | ✅ | | 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/...` 为主。 预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/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`) #### 运费测算(`/v2/api/shipping/calculate`)
@ -478,7 +524,8 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型 │ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
│ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型 │ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型
│ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射 │ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射
│ │ └── HengjianEstimateMapper.java 运费测算 + 地址属性映射 │ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射
│ │ └── HengjianInventoryMapper.java 库存两个接口 + 变动流水
│ ├── dto/ │ ├── dto/
│ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
@ -509,13 +556,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态 ├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态
├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过 ├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过
├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射 ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射
├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举 ├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径 ├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性 ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true └── 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. 探针用法 ## 5. 探针用法

17
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); common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY);
} }
/**
* 查库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。
*
* <p>与 {@link #query} 是两回事:那个给<b>当前余额</b>,这个给<b>变动明细</b>。
* 流水是按业务单据产生的,带一堆单号,用于对账与追溯。</p>
*
* <p>默认不支持——只有提供流水接口的仓才覆盖。</p>
*
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不提供流水查询
*/
default Page<common.ecommerce.warehouse.model.InventoryMovement> 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}。 */ /** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */
default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) { default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(

277
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;
/**
* 一条库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。
*
* <p><b>这是流水,不是余额</b>:{@link #changeQuantity()} 是单笔变动量,
* 按仓方原值返回、<b>不转正负号</b>(方向看 {@link #changeType()}),
* 也不代表当前库存。当前库存用 {@link InventorySnapshot}。</p>
*
* <p>流水是按<b>业务单据</b>产生的,所以带一堆单号:
* {@link #planOrderNo()} / {@link #sourceNo()} / {@link #executeOrderNo()} /
* {@link #platformOrderNo()} / {@link #saleOrderNo()} / {@link #poNumber()}。
* 各仓填哪几个不一样,未填的为 null。</p>
*/
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;
/** 单据类型,<b>仓方原值</b>(如「采购入库」「销售出库」);不归一,跨仓口径不同。 */
private final String documentType;
/** 变动方向,<b>仓方原值</b>(如「入库」「出库」)。 */
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);
}
}
}

148
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;
/**
* 库存变动流水查询条件。
*
* <p>与 {@link InventoryQuery} 的区别:那个查<b>当前库存余额</b>,这个查<b>流水</b>
* (每条是一次入库 / 出库 / 调整)。流水必须限定日期区间——不限定会拉到全部历史。</p>
*
* <p>各仓约束不同(恒健要求 SKU + 日期区间都必填、区间 ≤ 30 天),
* 由适配器在拼请求时按自己的协议校验。</p>
*/
public final class InventoryMovementQuery {
private final List<String> providerSkus;
private final List<String> 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<String>(b.providerSkus));
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(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<String> providerSkus() {
return providerSkus;
}
/** 仓 code 列表;空表示用账户配置的仓(按仓支持的仓)。 */
public List<String> 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<String> providerSkus = new ArrayList<String>();
private final List<String> warehouseCodes = new ArrayList<String>();
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<String> 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<String> 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);
}
}
}

18
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)); () -> ((InventoryCapable) adapter).queryAges(ctx, query));
} }
/**
* 查库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。
*
* <p>只读。与 {@link #query(InventoryQuery)} 不同:那个给当前余额,这个给变动明细。</p>
*/
public Page<common.ecommerce.warehouse.model.InventoryMovement> 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<InventorySnapshot> query(InventoryQuery query) { public Page<InventorySnapshot> query(InventoryQuery query) {
require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class); require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);

40
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java

@ -155,6 +155,46 @@ public final class HengjianConstants {
"/v2/api/shipping/addressClassification"; "/v2/api/shipping/addressClassification";
/** /**
* 按 SKU 查库存({@code POST},<b>不分页</b>)。
*
* <p>真机确认:{@code skus} 必填且不能是空数组。</p>
*/
public static final String PATH_INVENTORY_BY_SKU = "/v1/inventory/getInventory";
/**
* 批量查库存({@code GET},分页)。
*
* <p>真机确认 {@code warehouseCodes} 是<b>必填</b>的 List 参数;
* {@code page / rows / sidx / sort} 也必填,{@code rows} 默认最高 500。</p>
*/
public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page";
/**
* 库存变动流水({@code POST},分页)。
*
* <p>真机确认 {@code skus} / {@code beginDateTime} / {@code endDateTime} 都必填;
* 日期跨度最多 30 个自然日。</p>
*/
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;
/**
* 库存流水的日期跨度上限(自然日)。
*
* <p>文档与真机一致:{@code 2026-10-01}~{@code 2026-10-30} 合法,
* {@code ~2026-10-31} 不合法(真机回 {@code 查询日期最多包含30个自然日})。</p>
*/
public static final int INVENTORY_MOVEMENT_MAX_DAYS = 30;
/**
* {@code btChargeAt} 的日期区间分隔符。 * {@code btChargeAt} 的日期区间分隔符。
* *
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p> * <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

115
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.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos; 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.HengjianOperationFeeDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos; 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.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.AddressClassificationCapable; import common.ecommerce.warehouse.capability.AddressClassificationCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable; 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.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.AddressType; import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseCapability; 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.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult; import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery; 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.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
@ -84,7 +92,7 @@ import java.util.Map;
*/ */
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable,
WarehouseFeeEstimateCapable, AddressClassificationCapable { WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers"; 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_OPERATION = "warehouse.fee.operation";
private static final String OP_FEE_ESTIMATE = "warehouse.fee.estimate"; 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_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 之分,仓方也不回是哪种。 */ /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED"; private static final String SAVED = "SAVED";
@ -133,6 +143,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.OUTBOUND, WarehouseCapability.OUTBOUND,
WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.PLATFORM_LABEL_DELIVERY,
WarehouseCapability.TRACKING_CHANGE, WarehouseCapability.TRACKING_CHANGE,
WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_SETTLEMENT,
WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.ADDRESS_CLASSIFICATION, WarehouseCapability.ADDRESS_CLASSIFICATION,
@ -140,6 +151,108 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.LOGISTICS_PRODUCT); WarehouseCapability.LOGISTICS_PRODUCT);
} }
// ------------------------------------------------------------------ 库存
/**
* 库存同步策略。
*
* <p>恒健的两个库存接口都<b>不支持按更新时间增量</b>:按 SKU 的全量返回、
* 按仓的分页返回,都没有 {@code updatedAfter} 入参。所以策略是
* {@link InventorySyncStrategy#FULL_PULL_DIFF}——宿主全量拉后自己做差异比对。</p>
*
* <p>流水接口({@code movements})能按日期查,但那是<b>变动明细</b>,
* 不是余额,不能拿来重建当前库存。</p>
*/
@Override
public InventorySyncStrategy syncStrategy() {
return InventorySyncStrategy.FULL_PULL_DIFF;
}
/**
* 查库存。
*
* <p>恒健有两个接口,统一模型只有一个方法,按「给了什么」分流:</p>
* <ul>
* <li><b>给了 SKU</b> → {@code POST /v1/inventory/getInventory}(不分页,一次返回全部匹配行);</li>
* <li><b>只给仓</b> → {@code GET /v2/inventory/get_inventory_by_page}(分页)。</li>
* </ul>
*
* <p>两者都给的场景(按仓 + SKU 过滤)恒健没有对应接口,<b>本地拒绝</b>——
* 静默丢掉一个条件会让调用方以为过滤生效了。</p>
*
* <p>{@code updatedAfter} 恒健不支持,传了就拒绝(同上理由)。</p>
*/
@Override
public Page<InventorySnapshot> 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<InventorySnapshot> 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<HengjianInventoryDtos.InventoryRow> rows =
json.listAt(raw, "data", HengjianInventoryDtos.InventoryRow.class);
return Page.last(HengjianInventoryMapper.toSnapshots(rows, fallbackWarehouse(ctx)));
}
/** 按仓分页查。 */
private Page<InventorySnapshot> queryByPage(WarehouseContext ctx, InventoryQuery query) {
Map<String, List<String>> 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})。
*
* <p>真机确认:SKU 与日期区间都必填,区间 ≤ 30 个自然日,rows 1~100。</p>
*/
@Override
public Page<InventoryMovement> 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;
}
// ------------------------------------------------------------------ 试算与地址属性 // ------------------------------------------------------------------ 试算与地址属性
/** /**

366
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;
/**
* 恒健库存报文映射(库存查询 / 批量分页 / 变动流水)。
*
* <h2>两个库存接口的差异</h2>
* <table border="1">
* <tr><th></th><th>{@code getInventory}</th><th>{@code get_inventory_by_page}</th></tr>
* <tr><td>方法</td><td>POST</td><td>GET</td></tr>
* <tr><td>过滤</td><td>只按 SKU</td><td>只按仓({@code warehouseCodes} 必填)</td></tr>
* <tr><td>分页</td><td>不分页</td><td>分页,rows 上限 500</td></tr>
* </table>
* <p>统一模型是一个 {@code query()},所以:<b>给了 SKU 走按 SKU 查(无分页);
* 只给仓走分页查</b>。两条路都给的场景(按仓 + SKU 过滤)恒健没有对应接口,
* 本地拒绝而不是静默丢掉一个条件。</p>
*
* <h2>响应形状</h2>
* <p>分页接口的文档字段表说 {@code data} 是对象,返回示例却是数组;
* 这里用 JsonNode 判形状后分流,两种都接住。</p>
*/
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<String> 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<String>(skus);
return req;
}
/**
* 批量查库存的 GET 参数。
*
* <p>{@code warehouseCodes} 真机必填:调用方指定优先,否则用账户仓;
* 都没有就拒绝,避免把整个租户的库存拉下来。</p>
*
* @throws IllegalArgumentException 没有仓 code
*/
public static Map<String, List<String>> toPageParams(InventoryQuery query,
String defaultWarehouseCode) {
List<String> 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<String, List<String>> params = new LinkedHashMap<String, List<String>>();
params.put("warehouseCodes", new ArrayList<String>(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<InventorySnapshot> toPage(JsonNode data, String fallbackWarehouseCode,
int requestedRows, JacksonJsonCodec json) {
if (data == null || data.isNull() || data.isMissingNode()) {
return Page.last(new ArrayList<InventorySnapshot>());
}
List<HengjianInventoryDtos.InventoryRow> rows = new ArrayList<HengjianInventoryDtos.InventoryRow>();
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<InventorySnapshot> out = new ArrayList<InventorySnapshot>(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<InventorySnapshot> toSnapshots(List<HengjianInventoryDtos.InventoryRow> rows,
String fallbackWarehouseCode) {
List<InventorySnapshot> out = new ArrayList<InventorySnapshot>();
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<String>(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<InventoryMovement> toMovementPage(HengjianInventoryMovementDtos.PageData data,
String fallbackWarehouseCode,
int requestedRows, String cursor) {
if (data == null) {
return Page.last(new ArrayList<InventoryMovement>());
}
List<InventoryMovement> out = new ArrayList<InventoryMovement>();
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;
}
}

124
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;
/**
* 恒健报文结构:库存查询(两个接口共用行模型)。
*
* <p><b>两个接口的字段命名不一致,且文档与示例互相矛盾</b>(真机/文档双向核对):</p>
* <ul>
* <li>{@code /v1/inventory/getInventory}:请求 {@code {skus:[...]}},<b>不分页</b>;
* 行是 camelCase({@code warehouseCode} / {@code inventoryAvailable})。</li>
* <li>{@code /v2/inventory/get_inventory_by_page}:GET,<b>分页</b>;
* 字段表写 snake_case({@code warehouse_code} / {@code inventory_available}),
* 但同一页的返回示例又是 camelCase。</li>
* </ul>
* <p>因此行字段用 {@link JsonAlias} 同时接两种写法——不多花钱,却能防一次真机翻车。</p>
*
* <p><b>{@code data} 的形状两个接口也不一致</b>:分页接口的字段表说 {@code data} 是对象
* (含 {@code content} / {@code totalElements}),返回示例却是数组。
* 适配器用 JsonNode 判形状后分流,见 {@code HengjianInventoryMapper}。</p>
*/
public final class HengjianInventoryDtos {
private HengjianInventoryDtos() {
}
/** 按 SKU 查询的请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class QueryBySkuRequest {
/** 产品 SKU 列表;真机确认必填且不能为空数组。 */
public List<String> 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;
/**
* 在途库存。
*
* <p>文档标 STRING、示例给数字;用 String 接住,解析时再转 int。</p>
*/
@JsonProperty("inventoryTransport")
@JsonAlias("inventory_transport")
public String inventoryTransport;
/** 当前总库存;同样按 String 接。 */
@JsonProperty("inventoryCurrent")
@JsonAlias("inventory_current")
public String inventoryCurrent;
/**
* 最近更新时间。
*
* <p>文档没写时区。示例形如 {@code 2017-03-24 02:19:56}。按 UTC 解析,
* 待真机确认(与订单时间同口径假设)。</p>
*/
@JsonProperty("updatedAt")
@JsonAlias("updated_at")
public String updatedAt;
}
/** 分页信封。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PageData {
@JsonProperty("content")
public List<InventoryRow> content;
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("totalPages")
public Integer totalPages;
/** 当前页码,<b>0 基</b>(与订单列表同口径)。 */
@JsonProperty("number")
public Integer number;
@JsonProperty("size")
public Integer size;
@JsonProperty("last")
public Boolean last;
@JsonProperty("numberOfElements")
public Integer numberOfElements;
}
}

189
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})。
*
* <p><b>真机确认的必填项</b>:{@code skus}(非空数组)、{@code beginDateTime}、
* {@code endDateTime}({@code yyyy-MM-dd})。缺任一项回
* {@code MethodArgumentNotValidException} 并列出所有缺的字段。</p>
*
* <p><b>真机确认的约束</b>:日期范围最多 30 个自然日,超了回
* {@code 查询日期最多包含30个自然日}。</p>
*
* <p>这是<b>流水</b>,不是库存余额:{@code changeQty} 是单笔变动量,
* 按原值返回、不转正负号,也不代表当前库存。</p>
*/
public final class HengjianInventoryMovementDtos {
private HengjianInventoryMovementDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class QueryRequest {
/** 产品 SKU 列表;必填,元素不能为 null / 空串 / 纯空格。 */
public List<String> 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<MovementRow> 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;
/** 单笔流水数量;按原值返回,<b>不转正负号</b>,不代表当前库存余额。 */
@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;
}
}

7
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java

@ -74,13 +74,13 @@ class HengjianAdapterTest {
common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND)); common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND));
} }
/** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ /** 入库 / 退货仍未接入:门面按能力位直接拒绝。 */
@Test @Test
void undeclaredCapabilityIsRejected() { void undeclaredCapabilityIsRejected() {
WarehouseSdk sdk = sdk(); WarehouseSdk sdk = sdk();
assertThrows(WarehouseUnsupportedCapabilityException.class, assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> sdk.warehouses(WH, conn()).inventory().query(null)); () -> sdk.warehouses(WH, conn()).inbound().get("IB-1"));
} }
/** 能力矩阵查询本身可用(不触发真实 API)。 */ /** 能力矩阵查询本身可用(不触发真实 API)。 */
@ -88,8 +88,9 @@ class HengjianAdapterTest {
void capabilityQueryIsOffline() { void capabilityQueryIsOffline() {
HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec()); HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec());
// 库存已接入;入库 / 退货仍是未接状态
assertTrue(!adapter.capabilities().contains( assertTrue(!adapter.capabilities().contains(
common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY)); common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND));
} }
@Test @Test

4
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java

@ -484,7 +484,7 @@ class HengjianCreateOrderTest {
.outboundRequestNo("OB-1").build())); .outboundRequestNo("OB-1").build()));
} }
/** 未声明的能力位仍然被门面挡住(INVENTORY_QUERY 还没接)。 */ /** 未声明的能力位仍然被门面挡住(INBOUND 还没接)。 */
@Test @Test
void undeclaredCapabilityIsRejectedByFacade() { void undeclaredCapabilityIsRejectedByFacade() {
WarehouseSdk sdk = WarehouseSdk.builder() WarehouseSdk sdk = WarehouseSdk.builder()
@ -504,6 +504,6 @@ class HengjianCreateOrderTest {
HengjianConstants.TEST_BASE_URL, HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("t").build(), ChannelSecret.builder().appSecret("t").build(),
ZoneOffset.UTC)) ZoneOffset.UTC))
.inventory().query(null)); .inbound().get("IB-1"));
} }
} }

4
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.LOGISTICS_PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); 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.INBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.WEBHOOK)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.WEBHOOK));

402
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<InventorySnapshot> 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<InventorySnapshot> 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<InventorySnapshot> 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<InventorySnapshot> 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<InventorySnapshot> 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<InventoryMovement> 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<InventoryMovement> 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<InventoryMovement> 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));
}
}
Loading…
Cancel
Save