Browse Source

feat(hengjian): 对接入库计划详情 /v1/inbound/getInboundPlanInfo 与列表 getInboundPlanPage

- 两个接口回的对象字段完全一致,共用一份 DTO 与映射
- 详情:真机确认 orderNo 必填;单号既可是仓方计划单号也可是来源单号;
  data 为空返回 null
- 列表:状态过滤转数字码,认不出的状态拒绝不猜;时间区间是单值字符串
  "yyyy-MM-dd ~ yyyy-MM-dd";页大小上限 200 超限拒绝
- 新增 HengjianInboundStatus:计划单码表 0/5/6/8/10/15/20/25/70/100,
  同时认数字串与中文名;收货单的 0/70/90 是另一套码表,不混用
- core 新增 InboundQuery(仓/状态/单号/三种时间窗/库存类型/shipmentId)
  与 InboundCapable.queryInbounds() + 门面 queryInbounds();
  InboundCapable.query(cursor) 共用同一实现
- 数量三层 plan/packed/received 直接搬运不重算;可售/不可售分开映射,
  缺失时按可售兜底但总数一致
- 收货单 inboundOrderList 落成 INBOUNDED 阶段批次,库存类型保持 null

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

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 5 days ago
parent
commit
8f7d703f2f
  1. 7
      README.md
  2. 61
      docs-warehouse/hengjian/README.md
  3. 15
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java
  4. 303
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundQuery.java
  5. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 21
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  7. 67
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  8. 449
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryMapper.java
  9. 357
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundQueryDtos.java
  10. 106
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianInboundStatus.java
  11. 9
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  12. 341
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryTest.java

7
README.md

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

61
docs-warehouse/hengjian/README.md

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

15
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java

@ -36,6 +36,21 @@ public interface InboundCapable extends WarehouseAdapter { @@ -36,6 +36,21 @@ public interface InboundCapable extends WarehouseAdapter {
*/
Page<InboundOrder> query(WarehouseContext ctx, String cursor);
/**
* 多条件分页查入库单。
*
* <p>与 {@link #query(WarehouseContext, String)} 的区别:那个只有游标
* (没有列表接口的仓拿单号当游标),这个支持仓 / 状态 / 单号 / 时间窗等条件。
* 不支持的维度由适配器<b>显式拒绝</b>,不静默忽略。</p>
*
* <p>默认不支持——只有提供列表接口的仓才覆盖。</p>
*/
default Page<InboundOrder> queryInbounds(WarehouseContext ctx,
common.ecommerce.warehouse.model.InboundQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND);
}
/** BOL 文档;无此能力的仓返回空列表。 */
default List<String> bols(WarehouseContext ctx, String inboundRef) {
return Collections.emptyList();

303
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundQuery.java

@ -0,0 +1,303 @@ @@ -0,0 +1,303 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.InboundStatus;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 入库计划列表查询条件。
*
* <p>与 {@code InboundCapable.query(ctx, cursor)} 的区别:那个只有游标(
* 运去哪 / 信仓没有列表接口,只能用单号当游标),这个是<b>真正的多条件分页查询</b>。</p>
*
* <p>各仓支持的维度不同:不支持的维度由适配器<b>显式拒绝</b>,不静默忽略——
* 忽略一个过滤条件会让调用方以为「这段时间就这么多入库单」。</p>
*/
public final class InboundQuery {
private final List<String> warehouseCodes;
private final List<String> providerOrderNos;
private final List<String> sourceNos;
private final List<InboundStatus> statuses;
/** 库存类型:null 不限 / 0 可售 / 1 不可售。 */
private final Integer inventoryType;
/** 创建时间窗起点(UTC 日期);与 {@link #createdBefore()} 成对。 */
private final LocalDate createdAfter;
private final LocalDate createdBefore;
/** 更新时间窗(UTC 日期)。 */
private final LocalDate updatedAfter;
private final LocalDate updatedBefore;
/** 完成时间窗。 */
private final LocalDate completedAfter;
private final LocalDate completedBefore;
/** Amazon 货件号。 */
private final String shipmentId;
private final int pageSize;
private final String cursor;
private InboundQuery(Builder b) {
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes));
this.providerOrderNos = Collections.unmodifiableList(new ArrayList<String>(b.providerOrderNos));
this.sourceNos = Collections.unmodifiableList(new ArrayList<String>(b.sourceNos));
this.statuses = Collections.unmodifiableList(new ArrayList<InboundStatus>(b.statuses));
this.inventoryType = b.inventoryType;
requirePair(b.createdAfter, b.createdBefore, "createdAfter", "createdBefore");
requirePair(b.updatedAfter, b.updatedBefore, "updatedAfter", "updatedBefore");
requirePair(b.completedAfter, b.completedBefore, "completedAfter", "completedBefore");
this.createdAfter = b.createdAfter;
this.createdBefore = b.createdBefore;
this.updatedAfter = b.updatedAfter;
this.updatedBefore = b.updatedBefore;
this.completedAfter = b.completedAfter;
this.completedBefore = b.completedBefore;
this.shipmentId = b.shipmentId;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 仓 code 列表;空表示用账户配置的仓。 */
public List<String> warehouseCodes() {
return warehouseCodes;
}
/** 仓方入库计划单号列表。 */
public List<String> providerOrderNos() {
return providerOrderNos;
}
/** 来源单号(我们下发的入库单号)列表。 */
public List<String> sourceNos() {
return sourceNos;
}
/** 状态过滤;空表示不限。 */
public List<InboundStatus> statuses() {
return statuses;
}
/** 库存类型:null 不限 / 0 可售 / 1 不可售。 */
public Integer inventoryType() {
return inventoryType;
}
public LocalDate createdAfter() {
return createdAfter;
}
public LocalDate createdBefore() {
return createdBefore;
}
/** 是否给了创建时间窗。 */
public boolean hasCreatedRange() {
return createdAfter != null;
}
public LocalDate updatedAfter() {
return updatedAfter;
}
public LocalDate updatedBefore() {
return updatedBefore;
}
/** 是否给了更新时间窗。 */
public boolean hasUpdatedRange() {
return updatedAfter != null;
}
public LocalDate completedAfter() {
return completedAfter;
}
public LocalDate completedBefore() {
return completedBefore;
}
/** 是否给了完成时间窗。 */
public boolean hasCompletedRange() {
return completedAfter != null;
}
public String shipmentId() {
return shipmentId;
}
public int pageSize() {
return pageSize;
}
/** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
/** 翻页时只改游标。 */
public Builder toBuilder() {
Builder b = builder()
.warehouseCodes(warehouseCodes)
.providerOrderNos(providerOrderNos)
.sourceNos(sourceNos)
.statuses(statuses)
.inventoryType(inventoryType)
.shipmentId(shipmentId)
.pageSize(pageSize)
.cursor(cursor);
if (hasCreatedRange()) {
b.createdRange(createdAfter, createdBefore);
}
if (hasUpdatedRange()) {
b.updatedRange(updatedAfter, updatedBefore);
}
if (hasCompletedRange()) {
b.completedRange(completedAfter, completedBefore);
}
return b;
}
private static void requirePair(LocalDate after, LocalDate before, String an, String bn) {
if ((after == null) != (before == null)) {
throw new IllegalArgumentException(an + " and " + bn + " must be set together");
}
if (after != null && after.isAfter(before)) {
throw new IllegalArgumentException(an + " must not be after " + bn);
}
}
public static final class Builder {
private final List<String> warehouseCodes = new ArrayList<String>();
private final List<String> providerOrderNos = new ArrayList<String>();
private final List<String> sourceNos = new ArrayList<String>();
private final List<InboundStatus> statuses = new ArrayList<InboundStatus>();
private Integer inventoryType;
private LocalDate createdAfter;
private LocalDate createdBefore;
private LocalDate updatedAfter;
private LocalDate updatedBefore;
private LocalDate completedAfter;
private LocalDate completedBefore;
private String shipmentId;
private int pageSize = 100;
private String cursor;
public Builder warehouseCode(String v) {
if (v != null && !v.trim().isEmpty()) {
this.warehouseCodes.add(v.trim());
}
return this;
}
public Builder warehouseCodes(List<String> v) {
if (v != null) {
for (String one : v) {
warehouseCode(one);
}
}
return this;
}
/** 仓方入库计划单号。 */
public Builder providerOrderNo(String v) {
if (v != null && !v.trim().isEmpty()) {
this.providerOrderNos.add(v.trim());
}
return this;
}
public Builder providerOrderNos(List<String> v) {
if (v != null) {
for (String one : v) {
providerOrderNo(one);
}
}
return this;
}
/** 来源单号(我们下发的入库单号)。 */
public Builder sourceNo(String v) {
if (v != null && !v.trim().isEmpty()) {
this.sourceNos.add(v.trim());
}
return this;
}
public Builder sourceNos(List<String> v) {
if (v != null) {
for (String one : v) {
sourceNo(one);
}
}
return this;
}
public Builder status(InboundStatus v) {
if (v != null) {
this.statuses.add(v);
}
return this;
}
public Builder statuses(List<InboundStatus> v) {
if (v != null) {
for (InboundStatus one : v) {
status(one);
}
}
return this;
}
/** 库存类型:0 可售 / 1 不可售;null 不限。 */
public Builder inventoryType(Integer v) {
this.inventoryType = v;
return this;
}
/** 创建时间窗;两端成对。 */
public Builder createdRange(LocalDate after, LocalDate before) {
this.createdAfter = after;
this.createdBefore = before;
return this;
}
/** 更新时间窗;两端成对。 */
public Builder updatedRange(LocalDate after, LocalDate before) {
this.updatedAfter = after;
this.updatedBefore = before;
return this;
}
/** 完成时间窗;两端成对。 */
public Builder completedRange(LocalDate after, LocalDate before) {
this.completedAfter = after;
this.completedBefore = before;
return this;
}
public Builder shipmentId(String v) {
this.shipmentId = v;
return this;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public InboundQuery build() {
return new InboundQuery(this);
}
}
}

18
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -483,6 +483,24 @@ public final class WarehouseOperations { @@ -483,6 +483,24 @@ public final class WarehouseOperations {
}
/**
* 多条件分页查入库单。只读。
*
* <p>与 {@link #query(String)} 的区别:那个只有游标,这个支持仓 / 状态 / 单号 / 时间窗。</p>
*/
public Page<InboundOrder> queryInbounds(
final common.ecommerce.warehouse.model.InboundQuery query) {
require(WarehouseCapability.INBOUND, InboundCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.inbound.queryInbounds",
CallSupport.params("warehouseCount", query.warehouseCodes().size(),
"statusCount", query.statuses().size(),
"sourceNoCount", query.sourceNos().size(),
"pageSize", query.pageSize(),
"cursor", query.cursor()),
p -> p.size(),
() -> ((InboundCapable) adapter).queryInbounds(ctx, query));
}
/**
* 完善入库单资料。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + inboundRef + improve}。
*/

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

@ -203,6 +203,27 @@ public final class HengjianConstants { @@ -203,6 +203,27 @@ public final class HengjianConstants {
public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
/**
* 入库计划详情({@code POST})。
*
* <p>真机确认:{@code orderNo} 必填(空 body 回「单号不能为空」)。</p>
*/
public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo";
/**
* 入库计划列表({@code POST},分页)。
*
* <p>真机确认:{@code page} / {@code size} 不传也能过参数校验(只停在鉴权),
* 但文档标必填,适配器仍按文档下发。</p>
*/
public static final String PATH_INBOUND_PAGE = "/v1/inbound/getInboundPlanPage";
/** 入库计划列表默认页大小。 */
public static final int INBOUND_PAGE_SIZE_DEFAULT = 20;
/** 入库计划列表单页上限:文档没写,取 200;超限拒绝不截断。 */
public static final int INBOUND_PAGE_SIZE_MAX = 200;
/**
* {@code btChargeAt} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

67
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -8,6 +8,7 @@ import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; @@ -8,6 +8,7 @@ import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos;
import common.ecommerce.hengjian.dto.HengjianInventoryDtos;
import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos;
import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos;
import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos;
import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
@ -58,6 +59,7 @@ import common.ecommerce.warehouse.model.FeeEstimateResult; @@ -58,6 +59,7 @@ import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundQuery;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryMovement;
import common.ecommerce.warehouse.model.InventoryMovementQuery;
@ -118,6 +120,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -118,6 +120,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_INVENTORY_QUERY = "warehouse.inventory.query";
private static final String OP_INVENTORY_MOVEMENTS = "warehouse.inventory.movements";
private static final String OP_INBOUND_CREATE = "warehouse.inbound.create";
private static final String OP_INBOUND_GET = "warehouse.inbound.get";
private static final String OP_INBOUND_QUERY = "warehouse.inbound.query";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -184,26 +188,65 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -184,26 +188,65 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
return InboundReceipt.of(cmd.inboundRequestNo(), null);
}
/** 入库查询未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */
/**
* 查入库计划详情({@code POST /v1/inbound/getInboundPlanInfo})。
*
* <p>恒健只按<b>单号</b>查,且这个单号可以是仓方计划单号,也可以是来源单号
* (详情响应同时回 {@code inboundPlanOrderNo} 与 {@code sourceNo})。</p>
*
* <p>查不到({@code data} 为空)返回 null——与其它仓一致。</p>
*/
@Override
public InboundOrder get(WarehouseContext ctx, String inboundRef) {
throw unsupportedInbound("warehouse.inbound.get", ctx);
String orderNo = trimToNull(inboundRef);
if (orderNo == null) {
throw new IllegalArgumentException("hengjian inbound get requires an order number");
}
HengjianInboundQueryDtos.FindOneRequest body =
HengjianInboundQueryMapper.toFindOneRequest(orderNo);
String raw = execute(ctx, HengjianConstants.PATH_INBOUND_GET, body, OP_INBOUND_GET);
JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
HengjianInboundQueryDtos.InboundPlan plan =
json.fromJson(data.toString(), HengjianInboundQueryDtos.InboundPlan.class);
return HengjianInboundQueryMapper.toOrder(plan, fallbackWarehouse(ctx));
}
/**
* 按游标分页查入库单。
*
* <p>统一模型这个入口只有一个游标,恒健的列表接口支持多条件;这里把游标当页码,
* 其余条件为空——需要按状态 / 时间窗筛时用
* {@link #queryInbounds(WarehouseContext, InboundQuery)}。</p>
*/
@Override
public Page<InboundOrder> query(WarehouseContext ctx, String cursor) {
throw unsupportedInbound("warehouse.inbound.query", ctx);
return queryInbounds(ctx, InboundQuery.builder().cursor(cursor).build());
}
private WarehouseException unsupportedInbound(String operation, WarehouseContext ctx) {
return WarehouseException.builder()
.message("hengjian does not implement " + operation + " yet")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
/**
* 多条件分页查入库计划({@code POST /v1/inbound/getInboundPlanPage})。
*
* <p>恒健列表支持的维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 /
* 七种时间区间(创建 / 更新 / 完成 / 期望到货 / 预计发货 / 预计入库 / 首次接收)/
* Amazon shipmentId。</p>
*
* <p>统一模型只表达其中三种时间窗(创建 / 更新 / 完成)。其余四种恒健独有,
* 模型里没有——需要时再经 {@code InboundQuery} 扩字段,不在这里硬塞。</p>
*
* <p><b>未支持的维度直接拒绝</b>:见 {@link #queryInbounds} 里的校验。</p>
*/
@Override
public Page<InboundOrder> queryInbounds(WarehouseContext ctx, InboundQuery query) {
HengjianInboundQueryDtos.PageRequest body =
HengjianInboundQueryMapper.toPageRequest(query, ctx.providerWarehouseId());
String raw = execute(ctx, HengjianConstants.PATH_INBOUND_PAGE, body, OP_INBOUND_QUERY);
HengjianInboundQueryDtos.PageResponse resp =
json.fromJson(raw, HengjianInboundQueryDtos.PageResponse.class);
return HengjianInboundQueryMapper.toPage(resp == null ? null : resp.data,
fallbackWarehouse(ctx), query.cursor());
}
// ------------------------------------------------------------------ 库存

449
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryMapper.java

@ -0,0 +1,449 @@ @@ -0,0 +1,449 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos;
import common.ecommerce.hengjian.enums.HengjianInboundStatus;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.InboundStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundOrderBatch;
import common.ecommerce.warehouse.model.InboundOrderBox;
import common.ecommerce.warehouse.model.InboundOrderLine;
import common.ecommerce.warehouse.model.InboundQuery;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 恒健入库计划报文映射(详情 / 列表共用)。
*
* <h2>两个接口一个行模型</h2>
* <p>{@code getInboundPlanInfo} 与 {@code getInboundPlanPage} 回的对象字段完全一致,
* 只有外层形状不同(对象 vs 分页信封),所以映射只有一份。</p>
*
* <h2>状态码表</h2>
* <p>计划单状态用 {@link HengjianInboundStatus};{@code inboundOrderList[]} 里的
* {@code inboundOrderStatus} 是<b>收货单</b>的码表(0/70/90),与计划单不同,不混用。</p>
*
* <h2>数量三层</h2>
* <p>{@code planQty} / {@code packedQty} / {@code receivedQty} 分别落
* {@code plannedQuantity} / {@code packedQuantity} / {@code receivedQuantity},
* 短少与溢装靠比对它们发现,<b>不重算</b>——仓方给的就是准的。</p>
*/
public final class HengjianInboundQueryMapper {
/** 时间格式(文档未标时区;与其它接口同口径按 UTC 解析)。 */
private static final DateTimeFormatter DATE_TIME =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private HengjianInboundQueryMapper() {
}
// ================================================================ 详情 / 列表请求
/** 详情请求:只按单号。 */
public static HengjianInboundQueryDtos.FindOneRequest toFindOneRequest(String orderNo) {
HengjianInboundQueryDtos.FindOneRequest req = new HengjianInboundQueryDtos.FindOneRequest();
req.orderNo = orderNo;
return req;
}
/**
* 列表请求。
*
* <p>恒健的列表参数都很直接,只需要注意两点:</p>
* <ul>
* <li>状态过滤要转成<b>数字码</b>({@code inboundPlanOrderStatusList} 是 int 数组);</li>
* <li>时间区间是<b>单值字符串</b> {@code yyyy-MM-dd ~ yyyy-MM-dd},不是一个 start/end 对。</li>
* </ul>
*
* @throws IllegalArgumentException 状态无法映射成恒健码(认不出的状态不能猜)
*/
public static HengjianInboundQueryDtos.PageRequest toPageRequest(InboundQuery query,
String defaultWarehouseCode) {
HengjianInboundQueryDtos.PageRequest req = new HengjianInboundQueryDtos.PageRequest();
req.page = pageOf(query.cursor());
req.size = sizeOf(query.pageSize());
req.inventoryType = query.inventoryType();
if (!query.providerOrderNos().isEmpty()) {
req.inboundPlanOrderNoList = new ArrayList<String>(query.providerOrderNos());
}
if (!query.sourceNos().isEmpty()) {
req.sourceNoList = new ArrayList<String>(query.sourceNos());
}
if (!query.statuses().isEmpty()) {
List<Integer> codes = new ArrayList<Integer>(query.statuses().size());
for (InboundStatus status : query.statuses()) {
Integer code = codeOf(status);
if (code == null) {
// 认不出的状态不能猜:猜错会拉回一大堆无关单
throw new IllegalArgumentException(
"hengjian inbound list cannot filter by status " + status);
}
codes.add(code);
}
req.inboundPlanOrderStatusList = codes;
}
// 仓过滤:调用方给了就用,否则用账户仓
if (!query.warehouseCodes().isEmpty()) {
req.orgWarehouseCodeList = new ArrayList<String>(query.warehouseCodes());
} else if (defaultWarehouseCode != null && !defaultWarehouseCode.trim().isEmpty()) {
req.orgWarehouseCodeList = Collections.singletonList(defaultWarehouseCode.trim());
}
if (query.hasCreatedRange()) {
req.btCreatedDate = rangeOf(query.createdAfter(), query.createdBefore());
}
if (query.hasUpdatedRange()) {
req.btUpdatedDate = rangeOf(query.updatedAfter(), query.updatedBefore());
}
if (query.hasCompletedRange()) {
req.btCompleteDate = rangeOf(query.completedAfter(), query.completedBefore());
}
if (query.shipmentId() != null && !query.shipmentId().trim().isEmpty()) {
req.shipmentId = query.shipmentId().trim();
}
return req;
}
/** 核心状态 → 恒健数字码;认不出返回 null。 */
static Integer codeOf(InboundStatus status) {
if (status == null) {
return null;
}
switch (status) {
case DRAFT:
return 0;
case PENDING_REVIEW:
return 5;
case REJECTED:
return 6;
case PENDING_PACKING:
return 8;
case PENDING_SHIPMENT:
return 10;
case IN_TRANSIT:
return 15;
case PENDING_STORAGE:
return 20;
case STORING:
return 25;
case COMPLETED:
return 70;
case CANCELLED:
return 100;
default:
// RECEIVING / RECEIVED / UNKNOWN 等恒健没有对应码
return null;
}
}
/** 日期区间 → {@code yyyy-MM-dd ~ yyyy-MM-dd}。 */
static String rangeOf(LocalDate start, LocalDate end) {
return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end;
}
/** 页码:游标是字符串化页码,空游标表示第 1 页(入参 1 基)。 */
static int pageOf(String cursor) {
String v = trimToNull(cursor);
if (v == null) {
return 1;
}
try {
int page = Integer.parseInt(v);
return page < 1 ? 1 : page;
} catch (NumberFormatException e) {
throw new IllegalArgumentException(
"hengjian inbound list cursor must be a page number, got " + v);
}
}
/** 页大小:未指定用默认;上限没有文档依据,取 200 并拒绝超标(不静默截断)。 */
static int sizeOf(int requested) {
if (requested <= 0) {
return HengjianConstants.INBOUND_PAGE_SIZE_DEFAULT;
}
if (requested > HengjianConstants.INBOUND_PAGE_SIZE_MAX) {
throw new IllegalArgumentException(
"hengjian inbound page size must not exceed "
+ HengjianConstants.INBOUND_PAGE_SIZE_MAX + ", got " + requested);
}
return requested;
}
// ================================================================ 响应
/** 一个入库计划 → 统一模型。 */
public static InboundOrder toOrder(HengjianInboundQueryDtos.InboundPlan plan,
String warehouseCode) {
String sourceNo = trimToNull(plan.sourceNo);
String planNo = trimToNull(plan.inboundPlanOrderNo);
// 双号:来源单号是我们下发的,仓单号是仓方生成的。
// 来源单号缺失时(老单可能没回填)退回仓单号,避免构造期因空值失败
String requestNo = sourceNo != null ? sourceNo : planNo;
if (requestNo == null) {
throw new IllegalArgumentException(
"hengjian inbound plan has neither sourceNo nor inboundPlanOrderNo");
}
InboundStatus status = HengjianInboundStatus.toCore(plan.inboundPlanOrderStatus);
InboundOrder.Builder builder = InboundOrder.builder()
.inboundRequestNo(requestNo)
.providerInboundId(planNo)
.warehouseCode(firstNonBlank(plan.orgWarehouseCode, warehouseCode))
.status(status)
.rawStatus(trimToNull(plan.inboundPlanOrderStatus))
.rawStatusName(firstNonBlank(plan.inboundPlanOrderStatusName, null))
.sourceProvider(WarehouseProvider.HENGJIAN)
.inventoryType(inventoryTypeOf(plan.inventoryType))
.boxCount(intOf(plan.cartonQty))
.plannedQuantity(intOf(plan.planQty))
.packedQuantity(intOf(plan.packedQty))
.receivedQuantity(intOf(plan.receivedQty))
.lineName(trimToNull(plan.lineName))
.shipmentId(trimToNull(plan.shipmentId))
.referenceId(trimToNull(plan.referenceId))
.shipmentNo(trimToNull(plan.shipmentNo))
.goodsType(trimToNull(plan.goodsType))
.actualShippedAt(parseDate(plan.actualShipDate))
.cartonTotalWeightKg(positiveOrNull(plan.cartonTotalWeight))
.cartonTotalVolumeCbm(positiveOrNull(plan.cartonTotalVolume))
.packingLabelUrl(trimToNull(plan.packingLabelUrl))
// 创建时间:详情与列表都回 createdAt,与运去哪不同(那边没有)
.createdAt(parseTime(plan.createdAt))
.receivedAt(parseTime(firstNonNull(plan.firstReceptionTime, plan.firstReceptionDate)))
.estimatedArrivalAt(parseTime(plan.estimateArriveTime))
.actualArrivalAt(parseTime(plan.actualArriveTime))
.shipperName(trimToNull(plan.shipperName))
.shipperContact(trimToNull(plan.shipperContact))
.shipperPhone(trimToNull(plan.shipperPhone))
.shipperAddress(trimToNull(plan.shipperAddress))
.totalWeightKg(positiveOrNull(plan.totalWeight))
.totalVolumeCbm(positiveOrNull(plan.totalVolume))
.remark(trimToNull(plan.remark))
.modifiedAt(parseTime(plan.updatedAt));
addContainers(builder, plan);
builder.lines(toLines(plan.planProductDetailParamList));
addReceivedOrders(builder, plan.inboundOrderList);
return builder.build();
}
/** 列表 → 统一 Page。 */
public static Page<InboundOrder> toPage(HengjianInboundQueryDtos.PageData data,
String warehouseCode, String cursor) {
if (data == null) {
return Page.last(new ArrayList<InboundOrder>());
}
List<InboundOrder> out = new ArrayList<InboundOrder>();
if (data.content != null) {
for (HengjianInboundQueryDtos.InboundPlan plan : data.content) {
if (plan != null) {
out.add(toOrder(plan, warehouseCode));
}
}
}
// 响应 number 是 0 基,请求 page 是 1 基:下一页 = number + 2
boolean last = data.last != null ? data.last
: (data.numberOfElements != null && data.number == null);
if (last) {
return Page.last(out);
}
int next = (data.number == null ? 0 : data.number) + 2;
return Page.of(out, String.valueOf(next));
}
// ================================================================ 组件
/** 柜型:恒健把四种规格拆成独立字段,这里按有数量的规格逐个建 ContainerInfo。 */
private static void addContainers(InboundOrder.Builder builder,
HengjianInboundQueryDtos.InboundPlan plan) {
addContainer(builder, InboundOrder.ContainerType.GP20, plan.gpQuantity20, plan.gpCartonNo20);
addContainer(builder, InboundOrder.ContainerType.GP40, plan.gpQuantity40, plan.gpCartonNo40);
addContainer(builder, InboundOrder.ContainerType.HQ40, plan.hqQuantity40, plan.hqCartonNo40);
addContainer(builder, InboundOrder.ContainerType.HQ45, plan.hqQuantity45, plan.hqCartonNo45);
}
private static void addContainer(InboundOrder.Builder builder, InboundOrder.ContainerType type,
String quantity, String cartonNo) {
Integer qty = intOrNull(quantity);
if (qty == null || qty <= 0) {
return;
}
builder.container(InboundOrder.ContainerInfo.builder()
.type(type)
.quantity(qty)
.containerNo(trimToNull(cartonNo))
.rawType(type.name())
.build());
}
/**
* 产品明细。
*
* <p>数量缺失或非正的行跳过:{@link InboundOrderLine} 要求计划数量为正,
* 保留会在构造期抛异常,把「一条坏数据」放大成「整单查不出来」。</p>
*/
static List<InboundOrderLine> toLines(List<HengjianInboundQueryDtos.InboundPlan.ProductDetail> details) {
List<InboundOrderLine> out = new ArrayList<InboundOrderLine>();
if (details == null) {
return out;
}
for (HengjianInboundQueryDtos.InboundPlan.ProductDetail detail : details) {
if (detail == null) {
continue;
}
String sku = trimToNull(detail.sku);
int planned = intOf(detail.qty);
if (sku == null || planned <= 0) {
continue;
}
int received = intOf(detail.qtyReceived);
int saleable = intOf(detail.qtyReceivedSaleable);
int unsaleable = intOf(detail.qtyReceivedUnsaleable);
// 仓方把可售 / 不可售分开给;没有细分时按可售兜底(总数一致,不编造拆分)
if (saleable == 0 && unsaleable == 0 && received > 0) {
saleable = received;
}
out.add(InboundOrderLine.builder()
.providerSku(sku)
.plannedQuantity(planned)
.packedQuantity(intOf(detail.qtyPacked))
.receivedQuantity(received)
.receivedSaleableQuantity(saleable)
.receivedUnsaleableQuantity(unsaleable)
.build());
}
return out;
}
/**
* 实际收货单 → 批次明细。
*
* <p>恒健的 {@code inboundOrderList} 是「实际收货单」,每张单有独立的码表
* (0 草稿 / 70 已完成 / 90 已关闭)与行明细。落成
* {@link InboundOrderBatch} 的 {@code INBOUNDED} 阶段——它与「计划批次」是两段数据。</p>
*/
private static void addReceivedOrders(InboundOrder.Builder builder,
List<HengjianInboundQueryDtos.InboundPlan.InboundOrderInfo> orders) {
if (orders == null) {
return;
}
for (HengjianInboundQueryDtos.InboundPlan.InboundOrderInfo order : orders) {
if (order == null || order.inboundOrderItemList == null) {
continue;
}
for (HengjianInboundQueryDtos.InboundPlan.InboundOrderInfo.InboundOrderItem item
: order.inboundOrderItemList) {
if (item == null) {
continue;
}
String sku = trimToNull(item.sku);
int qty = intOf(item.qty);
if (sku == null || qty <= 0) {
continue;
}
builder.batch(InboundOrderBatch.builder()
.phase(InboundOrderBatch.Phase.INBOUNDED)
.providerSku(sku)
.quantity(qty)
// 箱唛号:收货单粒度,每行没有独立箱号
.cartonNo(trimToNull(order.inboundOrderNo))
// 库存类型:收货单层面没有细分,保持 null(未知,不猜)
.inventoryType(null)
.build());
}
}
}
// ================================================================ 工具
/** 库存类型:文字「可售库存 / 不可售库存」与数字 {@code "0"/"1"} 都要认。 */
static int inventoryTypeOf(String raw) {
String v = trimToNull(raw);
if (v == null) {
return 0;
}
if (v.contains("不可售")) {
return 1;
}
Integer n = intOrNull(v);
return n == null ? 0 : n;
}
static Instant parseTime(String value) {
String v = trimToNull(value);
if (v == null) {
return null;
}
try {
return LocalDateTime.parse(v, DATE_TIME).toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException e) {
// 有些字段只给日期(yyyy-MM-dd),按当天 00:00:00 解释
try {
return LocalDate.parse(v, DATE).atStartOfDay().toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException ignored) {
try {
return Instant.parse(v);
} catch (DateTimeParseException alsoIgnored) {
return null;
}
}
}
}
static Instant parseDate(String value) {
return parseTime(value);
}
static int intOf(Integer value) {
return value == null ? 0 : value;
}
/** 文本转 int;空 / 非数字返回 0(仓方有些数量字段标 STRING 却可能给空串)。 */
static int intOf(String value) {
Integer n = intOrNull(value);
return n == null ? 0 : n;
}
static Integer intOrNull(String value) {
String v = trimToNull(value);
if (v == null) {
return null;
}
try {
return Integer.valueOf(v);
} catch (NumberFormatException e) {
return null;
}
}
private static Double positiveOrNull(Double v) {
return v == null || v <= 0 ? null : v;
}
private static String firstNonNull(String a, String b) {
String x = trimToNull(a);
return x != null ? x : trimToNull(b);
}
private static String firstNonBlank(String a, String b) {
return firstNonNull(a, b);
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

357
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianInboundQueryDtos.java

@ -0,0 +1,357 @@ @@ -0,0 +1,357 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:入库计划查询(详情与列表共用)。
*
* <p>两个接口({@code getInboundPlanInfo} / {@code getInboundPlanPage})回的对象
* <b>字段完全一致</b>,只有外层形状不同:详情是 {@code data} 对象,列表是
* {@code data.content[]} 分页信封。所以行模型共用。</p>
*
* <p><b>类型怪癖</b>:同一个字段在不同接口 / 不同示例里类型不一致——</p>
* <ul>
* <li>{@code inboundPlanOrderStatus}:字段表标 STRING,示例给 {@code "70"}(数字的字符串),
* 而列表的请求参数又是数字数组。</li>
* <li>{@code inventoryType}:详情示例给中文「可售库存」,列表示例给 {@code "0"}。</li>
* <li>{@code gpQuantity20} 等柜数:字段表标 STRING,示例给数字。</li>
* </ul>
* <p>统一按文本读,解析时再转——这样两种形态都能接住,不会因类型漂移炸掉整单。</p>
*/
public final class HengjianInboundQueryDtos {
private HengjianInboundQueryDtos() {
}
/** 详情请求:只按入库计划单号。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class FindOneRequest {
/** 入库计划单号(我们下发时是来源单号 orderNo)。 */
public String orderNo;
}
/** 详情响应。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class FindOneResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public InboundPlan plan;
}
/**
* 列表请求。
*
* <p>所有过滤条件都可选;{@code page} / {@code size} 文档标必填,
* 但真机不传也能过校验(只停在鉴权),适配器仍按文档发。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PageRequest {
/** 第几页,默认 1。 */
public Integer page;
/** 每页几条,默认 10。 */
public Integer size;
/** 库存类型:0 可售 / 1 不可售。 */
public Integer inventoryType;
/** 入库计划单号列表。 */
public List<String> inboundPlanOrderNoList;
/** 来源单号列表。 */
public List<String> sourceNoList;
/** 状态码列表(数字码,见 {@code HengjianInboundStatus})。 */
public List<Integer> inboundPlanOrderStatusList;
/** 仓库 code 列表。 */
public List<String> orgWarehouseCodeList;
/** 时间区间过滤,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。 */
public String btUpdatedDate;
public String btCreatedDate;
public String btCompleteDate;
public String btExpectArriveDate;
public String btPredictionShipDate;
public String btEstimateArriveDate;
public String btFirstReceptionDate;
/** Amazon shipmentId。 */
public String shipmentId;
}
/** 列表响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PageResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public PageData data;
}
/** 分页数据。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PageData {
@JsonProperty("content")
public List<InboundPlan> content;
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("totalPages")
public Integer totalPages;
@JsonProperty("numberOfElements")
public Integer numberOfElements;
/** 当前页码,<b>0 基</b>(与订单 / 库存列表同口径)。 */
@JsonProperty("number")
public Integer number;
@JsonProperty("size")
public Integer size;
@JsonProperty("last")
public Boolean last;
}
/**
* 一个入库计划。
*
* <p>字段名与类型都照抄文档与示例;不确定类型的一律用 String 接。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class InboundPlan {
/** 仓 code。 */
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
/** 项目名称。 */
@JsonProperty("lineName")
public String lineName;
/** 库存类型:可能回 {@code "0"} / {@code "1"} 或中文「可售库存」。 */
@JsonProperty("inventoryType")
public String inventoryType;
/** 库存类型名(示例里有,字段表没列)。 */
@JsonProperty("inventoryTypeName")
public String inventoryTypeName;
/** 入库计划单号(仓方单号)。 */
@JsonProperty("inboundPlanOrderNo")
public String inboundPlanOrderNo;
/** 单据状态:数字码的字符串形式(如 {@code "70"})或中文名。 */
@JsonProperty("inboundPlanOrderStatus")
public String inboundPlanOrderStatus;
/** 状态名(示例里有,字段表没列)。 */
@JsonProperty("inboundPlanOrderStatusName")
public String inboundPlanOrderStatusName;
/** 来源单号(我们下发的 orderNo)。 */
@JsonProperty("sourceNo")
public String sourceNo;
@JsonProperty("shipmentId")
public String shipmentId;
@JsonProperty("referenceId")
public String referenceId;
@JsonProperty("shipmentNo")
public String shipmentNo;
/** 关联单号。 */
@JsonProperty("associatedOrderNo")
public String associatedOrderNo;
/** 预计到仓日期(示例里有字段表没列的两个日期)。 */
@JsonProperty("expectArriveDate")
public String expectArriveDate;
@JsonProperty("predictionShipDate")
public String predictionShipDate;
@JsonProperty("estimateArriveTime")
public String estimateArriveTime;
@JsonProperty("actualArriveTime")
public String actualArriveTime;
@JsonProperty("firstReceptionDate")
public String firstReceptionDate;
/** 首次接收时刻(示例里有)。 */
@JsonProperty("firstReceptionTime")
public String firstReceptionTime;
/** 到仓时刻(示例里有)。 */
@JsonProperty("warehouseArriveDate")
public String warehouseArriveDate;
/** 完成时间(示例里有)。 */
@JsonProperty("completeAt")
public String completeAt;
/** 创建 / 更新时间(示例里有)。 */
@JsonProperty("createdAt")
public String createdAt;
@JsonProperty("updatedAt")
public String updatedAt;
@JsonProperty("shipperName")
public String shipperName;
@JsonProperty("shipperAddress")
public String shipperAddress;
@JsonProperty("shipperContact")
public String shipperContact;
@JsonProperty("shipperPhone")
public String shipperPhone;
/** 货物形态:{@code container} 集装箱 / {@code truck} 卡车(示例里也可能是数字)。 */
@JsonProperty("goodsType")
public String goodsType;
/** 各规格柜数与柜号。 */
@JsonProperty("gpQuantity20")
public String gpQuantity20;
@JsonProperty("gpCartonNo20")
public String gpCartonNo20;
@JsonProperty("gpQuantity40")
public String gpQuantity40;
@JsonProperty("gpCartonNo40")
public String gpCartonNo40;
@JsonProperty("hqQuantity40")
public String hqQuantity40;
@JsonProperty("hqCartonNo40")
public String hqCartonNo40;
@JsonProperty("hqQuantity45")
public String hqQuantity45;
@JsonProperty("hqCartonNo45")
public String hqCartonNo45;
/** 纸箱数。 */
@JsonProperty("cartonQty")
public String cartonQty;
/** 计划 / 装箱 / 接收数量。 */
@JsonProperty("planQty")
public Integer planQty;
@JsonProperty("packedQty")
public Integer packedQty;
@JsonProperty("receivedQty")
public Integer receivedQty;
/** 总重量(KG)/ 总体积(CBM)。 */
@JsonProperty("totalWeight")
public Double totalWeight;
@JsonProperty("totalVolume")
public Double totalVolume;
/** 实际发运日期。 */
@JsonProperty("actualShipDate")
public String actualShipDate;
/** 总纸箱重(KG)/ 总纸箱体积(CBM)。 */
@JsonProperty("cartonTotalWeight")
public Double cartonTotalWeight;
@JsonProperty("cartonTotalVolume")
public Double cartonTotalVolume;
/** 纸箱 Label 标签文件地址。 */
@JsonProperty("packingLabelUrl")
public String packingLabelUrl;
@JsonProperty("remark")
public String remark;
/** 异常状态码 / 异常信息。 */
@JsonProperty("errorStatus")
public String errorStatus;
@JsonProperty("errorMessage")
public String errorMessage;
/** 标签生成状态。 */
@JsonProperty("labelCreateStatus")
public String labelCreateStatus;
/** 是否短收:0 否 / 1 是。 */
@JsonProperty("isShortReceipt")
public String isShortReceipt;
/** 产品明细。 */
@JsonProperty("planProductDetailParamList")
public List<ProductDetail> planProductDetailParamList;
/** 接收入库信息(实际收货单)。 */
@JsonProperty("inboundOrderList")
public List<InboundOrderInfo> inboundOrderList;
/** 产品明细行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductDetail {
@JsonProperty("sku")
public String sku;
@JsonProperty("qty")
public Integer qty;
@JsonProperty("qtyPacked")
public Integer qtyPacked;
@JsonProperty("qtyReceived")
public Integer qtyReceived;
@JsonProperty("qtyReceivedSaleable")
public Integer qtyReceivedSaleable;
@JsonProperty("qtyReceivedUnsaleable")
public Integer qtyReceivedUnsaleable;
}
/**
* 实际收货单。
*
* <p>{@code inboundOrderStatus} 的码表与计划单<b>不同</b>:
* 0 草稿 / 70 已完成 / 90 已关闭。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class InboundOrderInfo {
@JsonProperty("inboundOrderNo")
public String inboundOrderNo;
@JsonProperty("sourceNo")
public String sourceNo;
@JsonProperty("inboundOrderStatus")
public String inboundOrderStatus;
@JsonProperty("confirmedAt")
public String confirmedAt;
@JsonProperty("qty")
public Integer qty;
@JsonProperty("remark")
public String remark;
@JsonProperty("inboundOrderItemList")
public List<InboundOrderItem> inboundOrderItemList;
/** 收货单明细行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class InboundOrderItem {
@JsonProperty("inboundOrderNo")
public String inboundOrderNo;
@JsonProperty("sku")
public String sku;
@JsonProperty("qty")
public Integer qty;
}
}
}
}

106
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianInboundStatus.java

@ -0,0 +1,106 @@ @@ -0,0 +1,106 @@
package common.ecommerce.hengjian.enums;
import common.ecommerce.warehouse.enums.InboundStatus;
/**
* 恒健入库计划单状态。
*
* <p>两套码表要分清:</p>
* <ul>
* <li><b>列表接口</b>({@code getInboundPlanPage})的过滤参数
* {@code inboundPlanOrderStatusList} 用<b>数字码</b>:
* 0 草稿 / 5 待审核 / 6 审核拒回 / 8 待装箱 / 10 待发货 / 15 待接收 /
* 20 待入库 / 25 入库中 / 70 已完成 / 100 已取消。</li>
* <li><b>详情</b>与<b>列表响应</b>的 {@code inboundPlanOrderStatus} 回的是
* 上面这些数字的<b>字符串形式</b>(示例里 {@code "70"}),偶尔也可能是中文名。</li>
* </ul>
* <p>所以 {@link #of(String)} 同时认数字串与中文名;两者都对不上归 {@link #UNKNOWN}。</p>
*
* <p><b>不是</b> {@code inboundOrderList[].inboundOrderStatus}——那是<b>入库单</b>
* (实际收货单)的状态,码表是 0 草稿 / 70 已完成 / 90 已关闭,与计划单不同。
* 两者不能混用。</p>
*/
public enum HengjianInboundStatus {
/** 0 草稿。 */
DRAFT("0", "草稿", InboundStatus.DRAFT),
/** 5 待审核。 */
PENDING_REVIEW("5", "待审核", InboundStatus.PENDING_REVIEW),
/** 6 审核拒回。 */
// 注意:core 叫 REJECTED(审核拒绝),这里是「拒回」,语义相同
REJECTED("6", "审核拒回", InboundStatus.REJECTED),
/** 8 待装箱。 */
PENDING_PACKING("8", "待装箱", InboundStatus.PENDING_PACKING),
/** 10 待发货。 */
PENDING_SHIPMENT("10", "待发货", InboundStatus.PENDING_SHIPMENT),
/** 15 待接收(货未到仓)。 */
PENDING_RECEIVING("15", "待接收", InboundStatus.IN_TRANSIT),
/** 20 待入库(已收货,待上架)。 */
PENDING_STORAGE("20", "待入库", InboundStatus.PENDING_STORAGE),
/** 25 入库中(上架中)。 */
STORING("25", "入库中", InboundStatus.STORING),
/** 70 已完成。 */
COMPLETED("70", "已完成", InboundStatus.COMPLETED),
/** 100 已取消。 */
CANCELLED("100", "已取消", InboundStatus.CANCELLED),
/** 无法识别。 */
UNKNOWN(null, null, InboundStatus.UNKNOWN);
private final String rawCode;
private final String rawName;
private final InboundStatus core;
HengjianInboundStatus(String rawCode, String rawName, InboundStatus core) {
this.rawCode = rawCode;
this.rawName = rawName;
this.core = core;
}
/** 仓方数字码(字符串形式);UNKNOWN 为 null。 */
public String rawCode() {
return rawCode;
}
/** 仓方中文名;UNKNOWN 为 null。 */
public String rawName() {
return rawName;
}
/** 下发给列表接口时用的数字码;UNKNOWN 返回 null。 */
public Integer codeForQuery() {
return rawCode == null ? null : Integer.valueOf(rawCode);
}
public InboundStatus toCore() {
return core;
}
/**
* 仓方原值 → 平台枚举。
*
* <p>先按数字串精确匹配,再按中文名精确匹配;都认不出归 {@link #UNKNOWN},<b>不猜</b>。</p>
*/
public static HengjianInboundStatus of(String raw) {
if (raw == null) {
return UNKNOWN;
}
String s = raw.trim();
if (s.isEmpty()) {
return UNKNOWN;
}
for (HengjianInboundStatus v : values()) {
if (v == UNKNOWN) {
continue;
}
if (s.equals(v.rawCode) || s.equals(v.rawName)) {
return v;
}
}
return UNKNOWN;
}
/** 仓方原值 → 底层状态。 */
public static InboundStatus toCore(String raw) {
return of(raw).toCore();
}
}

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

@ -74,15 +74,6 @@ class HengjianAdapterTest { @@ -74,15 +74,6 @@ class HengjianAdapterTest {
common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND));
}
/** 入库创建已接、查询未接:适配器对未实现的 get 显式抛异常。 */
@Test
void unimplementedInboundGetIsRejected() {
WarehouseSdk sdk = sdk();
assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
() -> sdk.warehouses(WH, conn()).inbound().get("IB-1"));
}
/** 退货仍未接入:门面按能力位直接拒绝。 */
@Test
void undeclaredCapabilityIsRejected() {

341
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianInboundQueryTest.java

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