Browse Source

feat(hengjian): 对接调拨计划创建 / 查询 / 取消

三个接口真机均确认存在:create 的参数校验可逐步推进、cancel 缺 sourceNo 回
"Required String parameter 'sourceNo' is not present"、findByPage 无参数回 403。

- 创建:真机确认必填 outOrgWarehouseCode / inOrgWarehouseCode /
  estimateOutboundTime / estimateInboundTime;文档另标的 projectUnicode /
  transportationType / inventoryType / isLabel / receiveStore / shipTo* 真机不校验,
  按选填实现
- details[].qty 文档标 STRING:按字符串下发;查询响应是数字,两个 DTO 各声明
- 统一模型是 LocalDate,恒健要 yyyy-MM-dd HH:mm:ss:补当天 00:00:00 不编造时刻
- inOrgWarehouseCode=Other 表示外部仓库,映射 TransferType.OUTBOUND
- 响应 data 是字符串单号,拿不到即报错;创建不回状态,status 保持 UNKNOWN
- 查询:分页四件套必填、rows 上限 100 拒绝不截断;过滤参数都是单值,多给只取首个
- 取消走 GET + query,落在 deleteTransfer;仓方拒绝原样抛业务异常
- 新增 HengjianTransferStatus:13 个值精确匹配,100 取消中与 110 已取消不合并
- core 补 TransferQuery 模型 + TransferCapable.queryTransfers + 门面,
  TransferCommand 补 5 字段、TransferOrder 补 projectCode/attachments

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

Co-Authored-By: Claude Code <noreply@anthropic.com>
feature/Walmart
lml 4 days ago
parent
commit
94b69a021d
  1. 7
      README.md
  2. 68
      docs-warehouse/hengjian/README.md
  3. 14
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
  4. 93
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  5. 43
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  6. 180
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferQuery.java
  7. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  8. 20
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  9. 90
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  10. 359
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTransferMapper.java
  11. 294
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTransferDtos.java
  12. 86
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianTransferStatus.java
  13. 371
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTransferTest.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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨创建查询取消) |
依赖方向:
```
@ -382,7 +382,7 @@ common.ecommerce @@ -382,7 +382,7 @@ common.ecommerce
│ HengjianOrderMapper / HengjianTrackingChangeMapper /
│ HengjianFeeMapper / HengjianEstimateMapper /
│ HengjianInventoryMapper / HengjianInboundMapper /
│ HengjianInboundQueryMapper
│ HengjianInboundQueryMapper / HengjianTransferMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
@ -391,7 +391,8 @@ common.ecommerce @@ -391,7 +391,8 @@ common.ecommerce
│ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos /
│ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos /
│ HengjianInventoryDtos / HengjianInventoryMovementDtos /
│ HengjianInboundCreateDtos / HengjianInboundQueryDtos
│ HengjianInboundCreateDtos / HengjianInboundQueryDtos /
│ HengjianTransferDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter

68
docs-warehouse/hengjian/README.md

@ -81,7 +81,10 @@ @@ -81,7 +81,10 @@
| 19 | 入库计划创建 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | ✅ |
| 20 | 入库计划详情 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` | ✅ |
| 21 | 入库计划列表 | `POST /v1/inbound/getInboundPlanPage` | `INBOUND` | ✅ |
| 22 | 回调 | — | — | ❌ 文档无回调页 |
| 22 | 调拨计划创建 | `POST /v1/transferPlan/create` | `TRANSFER` | ✅ |
| 23 | 调拨计划查询 | `GET /v1/transferPlan/findByPage` | `TRANSFER` | ✅ |
| 24 | 调拨计划取消 | `GET /v1/transferPlan/cancel` | `TRANSFER` | ✅ |
| 25 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@ -421,6 +424,63 @@ productItems(入库产品明细必须填写) @@ -421,6 +424,63 @@ productItems(入库产品明细必须填写)
**未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。
### 调拨(`TRANSFER`)—— 已接入
#### 创建(`POST /v1/transferPlan/create`)
**真机确认的必填项**(按校验顺序):`outOrgWarehouseCode` → `inOrgWarehouseCode` →
`estimateOutboundTime` → `estimateInboundTime`。
文档另标了 `projectUnicode` / `transportationType` / `inventoryType` / `isLabel` /
`receiveStore` / 六个 `shipTo*` 为必填,但**真机校验里没有它们**——不传也能过(只停在鉴权)。
按选填实现,与入库创建的 `currency` 是同一类情况。
| 项 | 处理 |
|---|---|
| `details[].qty` | 文档标 **STRING**(不是 INTEGER),按字符串下发;查询响应里是数字,两个 DTO 各声明 |
| 日期 | 统一模型是 `LocalDate`,恒健要 `yyyy-MM-dd HH:mm:ss`:补当天 `00:00:00`,**不编造具体时刻** |
| `refferenceId` | 文档里就是**三个 f**,照抄 |
| `inOrgWarehouseCode=Other` | 外部仓库的固定代号;此时统一模型的 `type` 映射为 `OUTBOUND` |
| `transportationType` | 1 客户安排 / 2 仓库安排;未指定(0)按「仓库安排」兜底并在文档注明;其它值拒绝 |
| 响应 | `data` 是**字符串单号**(不是对象);拿不到单号即报错,不当创建成功 |
创建接口**不回状态**:`TransferOrder.status` 保持 `UNKNOWN`,不拿请求侧的值冒充。
#### 查询(`GET /v1/transferPlan/findByPage`)
- `page` / `rows` / `sidx` / `sort` 必填(`sidx=id`、`sort=desc`);`rows` 默认最高 **100**,超限拒绝。
- 过滤参数都是**单值**(`sourceNo` / `transferOutboundPlanNo` / `projectUnicode` /
`outOrgWarehouseCode` / `inOrgWarehouseCode`)——与其它接口不同,这里给多个单号时
只下发第一个(语义是「按这个单号查」,多给没有意义),文档已注明。
- 响应 `data` 是标准分页信封;游标换算同订单 / 库存列表(`number + 2`)。
#### 取消(`GET /v1/transferPlan/cancel`)
- **参数在 query,不是 body**;真机确认 `sourceNo` 必填
(缺了回 `Required String parameter 'sourceNo' is not present`)。
- 统一模型里落在 `TransferCapable.deleteTransfer`——恒健叫「取消」,语义等价于撤销。
- 恒健**没有取消费概念**;仓方拒绝时原样抛业务异常(如「未查询到对应调拨计划数据」),
不伪装成成功。
#### 状态枚举(`HengjianTransferStatus`)
13 个值:0 草稿 / 3 已驳回 / 5 待审核 / 7 审核通过 / 8 待确认 / 10 待出库 /
15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / 90 已关闭 / 100 取消中 / 110 已取消。
**精确匹配**,未知归 `UNKNOWN` 不猜。`100`(取消中)与 `110`(已取消)**不合并**——
合并就分不出「取消请求已发出」和「仓方已确认取消」。
#### 只为这些接口给 core 加的字段
`TransferCommand`:`projectCode` / `relabelProducts` / `referenceId` / `deliveryDate` /
`externalDestination`
`TransferOrder`:`projectCode` / `attachments`
`TransferQuery`(新增模型)+ `TransferCapable.queryTransfers()` + 门面 `queryTransfers()`
#### 未接入
`approve`(审核)与 `getTransfer`(按单号查详情)恒健没有对应接口,保持默认拒绝。
### 入库计划详情 / 列表(`INBOUND`)—— 已接入
两个接口回的对象**字段完全一致**,只有外层形状不同(`data` 对象 vs `data.content[]` 分页信封),
@ -624,7 +684,8 @@ warehouse-sdk-hengjian/ @@ -624,7 +684,8 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射
│ │ ├── HengjianInventoryMapper.java 库存两个接口 + 变动流水
│ │ ├── HengjianInboundMapper.java 入库计划创建
│ │ └── HengjianInboundQueryMapper.java 入库详情 / 列表
│ │ ├── HengjianInboundQueryMapper.java 入库详情 / 列表
│ │ └── HengjianTransferMapper.java 调拨创建 / 查询 / 取消
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
@ -658,13 +719,14 @@ warehouse-sdk-hengjian/ @@ -658,13 +719,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射
├── adapter/HengjianInboundCreateTest.java 17 个:必填 / 柜型 / 装箱 / 无仓单号
├── adapter/HengjianInboundQueryTest.java 18 个:详情映射 / 状态码表 / 列表过滤 / 分页
├── adapter/HengjianTransferTest.java 21 个:必填 / 字符串数量 / 外部仓 / 13 状态 / 取消
├── 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` 全部通过(238 个 + 4 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(259 个 + 4 个跳过)。
## 5. 探针用法

14
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java

@ -55,6 +55,20 @@ public interface TransferCapable extends WarehouseAdapter { @@ -55,6 +55,20 @@ public interface TransferCapable extends WarehouseAdapter {
}
/**
* 多条件分页查调拨单。
*
* <p>与 {@link #getTransfer} 的区别:那个按单号查单条,这个支持仓 / 单号 / 项目
* 等条件分页。不支持的维度由适配器显式拒绝。</p>
*
* <p>默认不支持——只有提供列表接口的仓才覆盖。</p>
*/
default common.ecommerce.shared.support.Page<TransferOrder> queryTransfers(
WarehouseContext ctx, common.ecommerce.warehouse.model.TransferQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
}
/**
* 删除(撤销)调拨单。<b>写操作</b>,幂等键
* {@code warehouseCode + providerTransferNo + "delete"}。
*

93
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java

@ -90,6 +90,34 @@ public final class TransferCommand { @@ -90,6 +90,34 @@ public final class TransferCommand {
/** 快递面单打印份数;null 表示不传。 */
private final Integer expressLabelCopies;
// ---- 恒健调拨协议字段(其它仓不用)----
/**
* 项目编号。
*
* <p>恒健 {@code projectUnicode},文档标必填;用于仓方按项目分账 / 路由。</p>
*/
private final String projectCode;
/**
* 是否更换产品标;null 表示不传(由仓方按默认否处理)。
*
* <p>恒健 {@code isLabel}(1 是 / 0 否)。与 {@link #labelRequirements()} 不同:
* 那个是「需要哪些标签」的清单,这个是「是否换标」的布尔开关。</p>
*/
private final Boolean relabelProducts;
/** Amazon referenceId;恒健 {@code refferenceId}(<b>文档里就是三个 f</b>,照抄)。 */
private final String referenceId;
/** 提货日期;恒健 {@code deliveryDate}({@code yyyy-MM-dd})。 */
private final java.time.LocalDate deliveryDate;
/**
* 该调拨是否为「发往外部地址」。
*
* <p>恒健要求仓外调拨时 {@code inOrgWarehouseCode} 固定填 {@code Other};
* 统一模型用 {@code toWarehouseCode} 表达,值为 {@code Other} 时即外部。
* 该标志只用于适配器判断是否走外部地址分支,不单独下发。</p>
*/
private final boolean externalDestination;
private TransferCommand(Builder b) {
if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) {
throw new IllegalArgumentException("transferRequestNo must not be blank");
@ -158,6 +186,11 @@ public final class TransferCommand { @@ -158,6 +186,11 @@ public final class TransferCommand {
this.bolAttachments = java.util.Collections.unmodifiableList(
new java.util.ArrayList<TransferAttachment>(b.bolAttachments));
this.expressLabelCopies = b.expressLabelCopies;
this.projectCode = b.projectCode;
this.relabelProducts = b.relabelProducts;
this.referenceId = b.referenceId;
this.deliveryDate = b.deliveryDate;
this.externalDestination = b.externalDestination;
}
public static Builder builder() {
@ -326,6 +359,31 @@ public final class TransferCommand { @@ -326,6 +359,31 @@ public final class TransferCommand {
return expressLabelCopies;
}
/** 项目编号;null 表示不传。 */
public String projectCode() {
return projectCode;
}
/** 是否更换产品标;null 表示不传。 */
public Boolean relabelProducts() {
return relabelProducts;
}
/** Amazon referenceId;null 表示不传。 */
public String referenceId() {
return referenceId;
}
/** 提货日期;null 表示不传。 */
public java.time.LocalDate deliveryDate() {
return deliveryDate;
}
/** 是否发往外部地址({@code toWarehouseCode} 为 Other 时为 true)。 */
public boolean externalDestination() {
return externalDestination;
}
public java.util.List<InboundBatch> batches() {
return batches;
}
@ -434,6 +492,11 @@ public final class TransferCommand { @@ -434,6 +492,11 @@ public final class TransferCommand {
private final java.util.List<TransferAttachment> bolAttachments =
new java.util.ArrayList<TransferAttachment>();
private Integer expressLabelCopies;
private String projectCode;
private Boolean relabelProducts;
private String referenceId;
private java.time.LocalDate deliveryDate;
private boolean externalDestination;
public Builder transferRequestNo(String v) {
this.transferRequestNo = v;
@ -649,6 +712,36 @@ public final class TransferCommand { @@ -649,6 +712,36 @@ public final class TransferCommand {
return this;
}
/** 项目编号。 */
public Builder projectCode(String v) {
this.projectCode = v;
return this;
}
/** 是否更换产品标;null 表示不传。 */
public Builder relabelProducts(Boolean v) {
this.relabelProducts = v;
return this;
}
/** Amazon referenceId。 */
public Builder referenceId(String v) {
this.referenceId = v;
return this;
}
/** 提货日期。 */
public Builder deliveryDate(java.time.LocalDate v) {
this.deliveryDate = v;
return this;
}
/** 是否发往外部地址({@code toWarehouseCode} 为 Other 时为 true)。 */
public Builder externalDestination(boolean v) {
this.externalDestination = v;
return this;
}
public TransferCommand build() {
return new TransferCommand(this);
}

43
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java

@ -118,6 +118,18 @@ public final class TransferOrder { @@ -118,6 +118,18 @@ public final class TransferOrder {
private final Instant createdAt;
/** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */
private final Instant modifiedAt;
/**
* 调拨单附件(面单 / 装箱单 / BOL / 其他)。
*
* <p>恒健字段:{@code attachesEntityList}(findByPage)。其它仓未提供时为空列表。</p>
*/
private final List<WarehouseAttachment> attachments;
/**
* 项目编号 / 项目名称(仓方按项目分账)。
*
* <p>恒健 {@code projectUnicode}(findByPage)。其它仓未提供时为 null。</p>
*/
private final String projectCode;
/** 商品明细;查询详情时回填,创建返回时通常为空。 */
private final List<TransferLine> lines;
@ -167,6 +179,10 @@ public final class TransferOrder { @@ -167,6 +179,10 @@ public final class TransferOrder {
this.totalAmount = b.totalAmount;
this.createdAt = b.createdAt;
this.modifiedAt = b.modifiedAt;
this.projectCode = b.projectCode;
this.attachments = b.attachments == null ? java.util.Collections.<WarehouseAttachment>emptyList()
: java.util.Collections.unmodifiableList(
new java.util.ArrayList<WarehouseAttachment>(b.attachments));
this.lines = b.lines == null ? java.util.Collections.<TransferLine>emptyList()
: java.util.Collections.unmodifiableList(new java.util.ArrayList<TransferLine>(b.lines));
}
@ -396,6 +412,16 @@ public final class TransferOrder { @@ -396,6 +412,16 @@ public final class TransferOrder {
return createdAt;
}
/** 项目编号;null 表示仓方未给。 */
public String projectCode() {
return projectCode;
}
/** 调拨单附件;不可变,空表示没有。 */
public List<WarehouseAttachment> attachments() {
return attachments;
}
/** 最后修改时间(UTC)。 */
public Instant modifiedAt() {
return modifiedAt;
@ -628,6 +654,8 @@ public final class TransferOrder { @@ -628,6 +654,8 @@ public final class TransferOrder {
private Money totalAmount;
private Instant createdAt;
private Instant modifiedAt;
private List<WarehouseAttachment> attachments = new java.util.ArrayList<WarehouseAttachment>();
private String projectCode;
private List<TransferLine> lines;
public Builder transferRequestNo(String v) {
@ -875,6 +903,21 @@ public final class TransferOrder { @@ -875,6 +903,21 @@ public final class TransferOrder {
}
/** 最后修改时间(信仓 {@code gmt_modify})。 */
public Builder projectCode(String v) {
this.projectCode = v;
return this;
}
public Builder attachment(WarehouseAttachment v) {
if (this.attachments == null) {
this.attachments = new java.util.ArrayList<WarehouseAttachment>();
}
if (v != null) {
this.attachments.add(v);
}
return this;
}
public Builder modifiedAt(Instant v) {
this.modifiedAt = v;
return this;

180
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferQuery.java

@ -0,0 +1,180 @@ @@ -0,0 +1,180 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 调拨单查询条件(多条件分页)。
*
* <p>各仓支持的维度不同:不支持的维度由适配器<b>显式拒绝</b>,
* 不静默忽略——忽略一个过滤条件会让调用方以为「这段时间就这么多调拨单」。</p>
*/
public final class TransferQuery {
private final List<String> warehouseCodes;
private final String fromWarehouseCode;
private final String toWarehouseCode;
private final List<String> sourceNos;
private final List<String> providerTransferNos;
private final String projectCode;
private final int pageSize;
private final String cursor;
private TransferQuery(Builder b) {
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes));
this.fromWarehouseCode = b.fromWarehouseCode;
this.toWarehouseCode = b.toWarehouseCode;
this.sourceNos = Collections.unmodifiableList(new ArrayList<String>(b.sourceNos));
this.providerTransferNos = Collections.unmodifiableList(
new ArrayList<String>(b.providerTransferNos));
this.projectCode = b.projectCode;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 仓 code 列表;空表示用账户配置的仓。 */
public List<String> warehouseCodes() {
return warehouseCodes;
}
/** 调出仓 code;null 表示不限。 */
public String fromWarehouseCode() {
return fromWarehouseCode;
}
/** 调入仓 code;null 表示不限。 */
public String toWarehouseCode() {
return toWarehouseCode;
}
/** 来源单号列表(我们下发的调拨单号)。 */
public List<String> sourceNos() {
return sourceNos;
}
/** 仓方调拨单号列表。 */
public List<String> providerTransferNos() {
return providerTransferNos;
}
/** 项目编号;null 表示不限。 */
public String projectCode() {
return projectCode;
}
public int pageSize() {
return pageSize;
}
/** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
/** 翻页时只改游标。 */
public Builder toBuilder() {
return builder()
.warehouseCodes(warehouseCodes)
.fromWarehouseCode(fromWarehouseCode)
.toWarehouseCode(toWarehouseCode)
.sourceNos(sourceNos)
.providerTransferNos(providerTransferNos)
.projectCode(projectCode)
.pageSize(pageSize)
.cursor(cursor);
}
public static final class Builder {
private final List<String> warehouseCodes = new ArrayList<String>();
private String fromWarehouseCode;
private String toWarehouseCode;
private final List<String> sourceNos = new ArrayList<String>();
private final List<String> providerTransferNos = new ArrayList<String>();
private String projectCode;
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 fromWarehouseCode(String v) {
this.fromWarehouseCode = v;
return this;
}
public Builder toWarehouseCode(String v) {
this.toWarehouseCode = v;
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 providerTransferNo(String v) {
if (v != null && !v.trim().isEmpty()) {
this.providerTransferNos.add(v.trim());
}
return this;
}
public Builder providerTransferNos(List<String> v) {
if (v != null) {
for (String one : v) {
providerTransferNo(one);
}
}
return this;
}
public Builder projectCode(String v) {
this.projectCode = v;
return this;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public TransferQuery build() {
return new TransferQuery(this);
}
}
}

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

@ -167,6 +167,24 @@ public final class WarehouseOperations { @@ -167,6 +167,24 @@ public final class WarehouseOperations {
}
/**
* 多条件分页查调拨单。只读。
*
* <p>与 {@link #getTransfer(String)} 的区别:那个按单号查单条,这个支持条件分页。</p>
*/
public common.ecommerce.shared.support.Page<TransferOrder> queryTransfers(
final common.ecommerce.warehouse.model.TransferQuery query) {
require(WarehouseCapability.TRANSFER, TransferCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.transfer.query",
CallSupport.params("fromWarehouseCode", query.fromWarehouseCode(),
"toWarehouseCode", query.toWarehouseCode(),
"sourceNoCount", query.sourceNos().size(),
"pageSize", query.pageSize(),
"cursor", query.cursor()),
p -> p.size(),
() -> ((TransferCapable) adapter).queryTransfers(ctx, query));
}
/**
* 删除(撤销)调拨单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + providerTransferNo + delete}。
*

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

@ -224,6 +224,26 @@ public final class HengjianConstants { @@ -224,6 +224,26 @@ public final class HengjianConstants {
public static final int INBOUND_PAGE_SIZE_MAX = 200;
/**
* 调拨计划创建({@code POST})。
*
* <p>真机确认必填:{@code outOrgWarehouseCode} / {@code inOrgWarehouseCode} /
* {@code estimateOutboundTime} / {@code estimateInboundTime}。响应 {@code data}
* 是<b>字符串单号</b>。</p>
*/
public static final String PATH_TRANSFER_CREATE = "/v1/transferPlan/create";
/** 调拨计划查询({@code GET},分页;rows 默认最高 100)。 */
public static final String PATH_TRANSFER_PAGE = "/v1/transferPlan/findByPage";
/**
* 调拨计划取消({@code GET},参数在 query)。
*
* <p>真机确认 {@code sourceNo} 必填(缺了回
* {@code Required String parameter 'sourceNo' is not present})。</p>
*/
public static final String PATH_TRANSFER_CANCEL = "/v1/transferPlan/cancel";
/**
* {@code btChargeAt} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

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

@ -10,6 +10,7 @@ import common.ecommerce.hengjian.dto.HengjianInventoryDtos; @@ -10,6 +10,7 @@ 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.HengjianTransferDtos;
import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
@ -32,6 +33,7 @@ import common.ecommerce.shared.support.Page; @@ -32,6 +33,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.AddressClassificationCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
@ -65,6 +67,9 @@ import common.ecommerce.warehouse.model.InventoryMovement; @@ -65,6 +67,9 @@ 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.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferQuery;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
@ -100,7 +105,7 @@ import java.util.Map; @@ -100,7 +105,7 @@ import java.util.Map;
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable,
WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable,
InboundCapable {
InboundCapable, TransferCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers";
@ -122,6 +127,9 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -122,6 +127,9 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
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";
private static final String OP_TRANSFER_CREATE = "warehouse.transfer.create";
private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query";
private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -156,6 +164,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -156,6 +164,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.TRACKING_CHANGE,
WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.INBOUND,
WarehouseCapability.TRANSFER,
WarehouseCapability.FEE_SETTLEMENT,
WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.ADDRESS_CLASSIFICATION,
@ -163,6 +172,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -163,6 +172,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.LOGISTICS_PRODUCT);
}
// ------------------------------------------------------------------ 调拨
/**
* 创建调拨计划({@code POST /v1/transferPlan/create})。
*
* <p>真机确认必填:调出 / 调入仓、期望出库 / 入库时间。
* 响应 {@code data} 是<b>字符串单号</b>(不是对象)。</p>
*
* <p>外部仓库用仓代码 {@code Other} 表达——恒健的约定,适配器不猜。</p>
*/
@Override
public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) {
HengjianTransferDtos.CreateRequest body = HengjianTransferMapper.toRequest(cmd);
String raw = execute(ctx, HengjianConstants.PATH_TRANSFER_CREATE, body, OP_TRANSFER_CREATE);
String planNo = json.stringAt(raw, "data");
if (trimToNull(planNo) == null) {
// 拿不到单号不能当成功:后续查询 / 取消都要它
throw WarehouseException.builder()
.message("hengjian transfer returned no data (plan no): " + safeRelay(raw))
.operation(OP_TRANSFER_CREATE)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.rawResponse(safeRelay(raw))
.build();
}
return HengjianTransferMapper.toCreated(cmd, planNo.trim());
}
/**
* 多条件分页查调拨计划({@code GET /v1/transferPlan/findByPage})。
*
* <p>恒健的过滤参数都是<b>单值</b>(不是数组),所以统一模型里给了多个单号时
* 只下发第一个——这与其它接口「拒绝多值」的做法不同,因为这里的语义是
* 「按这个单号查」,多给没有意义。文档已注明。</p>
*/
@Override
public Page<TransferOrder> queryTransfers(WarehouseContext ctx, TransferQuery query) {
Map<String, Object> params = HengjianTransferMapper.toPageParams(query, query.cursor());
rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_PAGE, HengjianConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(),
HengjianConstants.PATH_TRANSFER_PAGE, params, ctx.secret(), ctx, OP_TRANSFER_QUERY);
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_QUERY,
ctx.warehouseCode(), ctx.requestId()).body();
HengjianTransferDtos.PageResponse resp =
json.fromJson(raw, HengjianTransferDtos.PageResponse.class);
return HengjianTransferMapper.toPage(resp == null ? null : resp.data, query.cursor());
}
/**
* 取消调拨计划({@code GET /v1/transferPlan/cancel})。
*
* <p>这是统一模型里 {@link TransferCapable#deleteTransfer} 的落点:恒健叫「取消」,
* 语义等价于「撤销这张调拨单」。<b>取消要收费</b>是运去哪的概念,恒健没有。</p>
*
* <p>参数在 <b>query</b>(不是 body);真机确认 {@code sourceNo} 必填。</p>
*/
@Override
public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) {
String sourceNo = trimToNull(providerTransferNo);
if (sourceNo == null) {
throw new IllegalArgumentException("hengjian transfer cancel requires sourceNo");
}
Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("sourceNo", sourceNo);
rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_CANCEL, HengjianConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(),
HengjianConstants.PATH_TRANSFER_CANCEL, params, ctx.secret(), ctx, OP_TRANSFER_CANCEL);
try {
HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_CANCEL,
ctx.warehouseCode(), ctx.requestId());
} catch (PlatformBusinessException e) {
// 取消失败只有 message(如「未查询到对应调拨计划数据」);
// 不能细分成状态错还是参数错,原样抛出业务异常
throw e;
}
}
// ------------------------------------------------------------------ 入库
/**

359
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTransferMapper.java

@ -0,0 +1,359 @@ @@ -0,0 +1,359 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianTransferDtos;
import common.ecommerce.hengjian.enums.HengjianTransferStatus;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferQuery;
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.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 恒健调拨计划映射(创建 / 查询)。
*
* <h2>真机确认的必填项</h2>
* <p>{@code outOrgWarehouseCode} / {@code inOrgWarehouseCode} /
* {@code estimateOutboundTime} / {@code estimateInboundTime}。文档另标了
* {@code projectUnicode} / {@code transportationType} / {@code inventoryType} /
* {@code isLabel} / {@code receiveStore} / 六个 {@code shipTo*},
* 但真机校验里没有——按选填实现。</p>
*
* <h2>数量类型</h2>
* <p>创建的 {@code details[].qty} 是 <b>STRING</b>(不是 INTEGER),
* 查询响应里是 INTEGER。两个 DTO 各自声明,互不干扰。</p>
*/
public final class HengjianTransferMapper {
/** 恒健日期时间格式(文档写 {@code yyyy-mm-dd h24:mi:ss})。 */
private static final DateTimeFormatter DATE_TIME =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
/** 外部仓库的固定代号。 */
static final String OTHER_WAREHOUSE = "Other";
/** 运输方式:1 客户安排。 */
static final int TRANSPORT_CUSTOMER = 1;
/** 运输方式:2 仓库安排。 */
static final int TRANSPORT_WAREHOUSE = 2;
/** 恒健列表单页上限(文档:默认最高 100)。 */
static final int MAX_ROWS = 100;
private HengjianTransferMapper() {
}
// ================================================================ 创建
/**
* 统一命令 → 恒健创建请求。
*
* @param ctx 用于取期望出库 / 入库时间(统一模型只有日期)
* @throws IllegalArgumentException 缺必填项
*/
public static HengjianTransferDtos.CreateRequest toRequest(TransferCommand cmd) {
String from = requireText(cmd.fromWarehouseCode(), "fromWarehouseCode");
String to = requireText(cmd.toWarehouseCode(), "toWarehouseCode");
LocalDate outDate = cmd.estimateOutboundDate();
LocalDate inDate = cmd.estimateInboundDate();
if (outDate == null || inDate == null) {
// 恒健只要「期望出库 / 入库时间」,统一模型里是日期;缺一个都发不出去
throw new IllegalArgumentException(
"hengjian transfer requires estimateOutboundDate and estimateInboundDate");
}
HengjianTransferDtos.CreateRequest req = new HengjianTransferDtos.CreateRequest();
req.projectUnicode = trimToNull(cmd.projectCode());
req.outOrgWarehouseCode = from;
req.inOrgWarehouseCode = to;
req.transportationType = transportationTypeOf(cmd.transportationType());
req.inventoryType = cmd.inventoryType();
req.isLabel = flagOf(cmd.relabelProducts());
req.sourceNo = cmd.transferRequestNo();
// 统一模型只有日期,恒健要日期时间:按当天 00:00:00 补全(不编造具体时刻)
req.estimateOutboundTime = dateTimeOf(outDate);
req.estimateInboundTime = dateTimeOf(inDate);
req.shipmentId = trimToNull(cmd.shipmentId());
req.refferenceId = trimToNull(cmd.referenceId());
req.receiveStore = trimToNull(cmd.receiveStore());
req.remark = trimToNull(cmd.remark());
req.deliveryDate = cmd.deliveryDate() == null ? null : cmd.deliveryDate().toString();
if (cmd.shipTo() != null) {
req.shipToCountry = trimToNull(cmd.shipTo().countryCode());
req.shipToState = trimToNull(cmd.shipTo().stateOrProvince());
req.shipToCity = trimToNull(cmd.shipTo().city());
req.shipToPostal = trimToNull(cmd.shipTo().postalCode());
req.shipToAddress1 = trimToNull(cmd.shipTo().addressLine1());
req.shipToAddress2 = trimToNull(cmd.shipTo().addressLine2());
req.shipToContact = trimToNull(cmd.shipTo().name());
req.shipToTelephone = trimToNull(cmd.shipTo().phone());
}
req.details = toDetails(cmd.lines());
return req;
}
/** 产品明细:数量按<b>字符串</b>下发(恒健该字段标 STRING)。 */
private static List<HengjianTransferDtos.CreateRequest.Detail> toDetails(
List<TransferCommand.TransferLine> lines) {
List<HengjianTransferDtos.CreateRequest.Detail> out =
new ArrayList<HengjianTransferDtos.CreateRequest.Detail>(lines.size());
for (TransferCommand.TransferLine line : lines) {
HengjianTransferDtos.CreateRequest.Detail detail =
new HengjianTransferDtos.CreateRequest.Detail();
detail.sku = line.providerSku();
detail.qty = String.valueOf(line.quantity());
out.add(detail);
}
return out;
}
/**
* 运输方式映射。
*
* <p>恒健 1 客户安排 / 2 仓库安排。统一模型的 {@code transportationType} 是
* <b>仓方口径的裸数字</b>,所以直接透传 1 / 2;其它值拒绝而不是猜——
* 猜错会让客户被误收运费。</p>
*/
static Integer transportationTypeOf(int raw) {
if (raw == TRANSPORT_CUSTOMER || raw == TRANSPORT_WAREHOUSE) {
return raw;
}
// 0 表示未指定:按「仓库安排」下发(恒健的常用默认),并在文档里注明
if (raw == 0) {
return TRANSPORT_WAREHOUSE;
}
throw new IllegalArgumentException(
"hengjian transfer transportationType must be 1 (customer) or 2 (warehouse), got " + raw);
}
/** 日期 → {@code yyyy-MM-dd HH:mm:ss}(当天 00:00:00,不编造时刻)。 */
static String dateTimeOf(LocalDate date) {
return date.atStartOfDay().format(DATE_TIME);
}
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? 1 : 0);
}
private static String requireText(String value, String field) {
String v = trimToNull(value);
if (v == null) {
throw new IllegalArgumentException("hengjian transfer requires " + field);
}
return v;
}
// ================================================================ 查询
/** 查询参数(GET)。 */
public static Map<String, Object> toPageParams(TransferQuery query, String cursor) {
Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("page", pageOf(cursor));
params.put("rows", rowsOf(query.pageSize()));
params.put("sidx", "id");
params.put("sort", "desc");
// 恒健这几个过滤参数都是单值,不是数组;多个时只取第一个并说明
putFirst(params, "sourceNo", query.sourceNos());
putFirst(params, "transferOutboundPlanNo", query.providerTransferNos());
putIfPresent(params, "projectUnicode", query.projectCode());
putIfPresent(params, "outOrgWarehouseCode", query.fromWarehouseCode());
putIfPresent(params, "inOrgWarehouseCode", query.toWarehouseCode());
return params;
}
private static void putFirst(Map<String, Object> params, String key, List<String> values) {
if (values != null && !values.isEmpty()) {
params.put(key, values.get(0));
}
}
private static void putIfPresent(Map<String, Object> params, String key, String value) {
String v = trimToNull(value);
if (v != null) {
params.put(key, v);
}
}
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 transfer cursor must be a page number, got " + v);
}
}
/** 单页行数:文档明写默认最高 100,超限拒绝不截断。 */
static int rowsOf(int requested) {
if (requested <= 0) {
return MAX_ROWS;
}
if (requested > MAX_ROWS) {
throw new IllegalArgumentException(
"hengjian transfer rows must not exceed " + MAX_ROWS + ", got " + requested);
}
return requested;
}
/** 创建响应 {@code data} 是字符串单号 → 回执。 */
public static TransferOrder toCreated(TransferCommand cmd, String providerTransferNo) {
return TransferOrder.builder()
.transferRequestNo(cmd.transferRequestNo())
.providerTransferNo(providerTransferNo)
.fromWarehouseCode(cmd.fromWarehouseCode())
.toWarehouseCode(cmd.toWarehouseCode())
.type(cmd.type())
// 创建接口不回状态:保持 UNKNOWN,不拿请求侧的值冒充
.status(common.ecommerce.warehouse.enums.TransferStatus.UNKNOWN)
.sourceProvider(WarehouseProvider.HENGJIAN)
.totalQuantity(totalQuantityOf(cmd))
.remark(cmd.remark())
.build();
}
private static int totalQuantityOf(TransferCommand cmd) {
int total = 0;
for (TransferCommand.TransferLine line : cmd.lines()) {
total += line.quantity();
}
return total;
}
/** 查询行 → 统一模型。 */
public static TransferOrder toOrder(HengjianTransferDtos.TransferRow row) {
String sourceNo = trimToNull(row.sourceNo);
String planNo = trimToNull(row.transferOutboundPlanNo);
String requestNo = sourceNo != null ? sourceNo : planNo;
if (requestNo == null) {
throw new IllegalArgumentException(
"hengjian transfer row has neither sourceNo nor transferOutboundPlanNo");
}
String from = trimToNull(row.outOrgWarehouseCode);
String to = trimToNull(row.inOrgWarehouseCode);
TransferOrder.Builder builder = TransferOrder.builder()
.transferRequestNo(requestNo)
.providerTransferNo(planNo)
.providerId(row.id == null ? null : String.valueOf(row.id))
.fromWarehouseCode(from == null ? OTHER_WAREHOUSE : from)
.toWarehouseCode(to == null ? OTHER_WAREHOUSE : to)
// 恒健的调拨都是仓到仓;外部仓库用 toWarehouseCode=Other 表达
.type(OTHER_WAREHOUSE.equalsIgnoreCase(to)
? TransferType.OUTBOUND : TransferType.WAREHOUSE_TO_WAREHOUSE)
.status(HengjianTransferStatus.toCore(row.transferOutboundPlanStatus))
.rawStatus(trimToNull(row.transferOutboundPlanStatus))
.sourceProvider(WarehouseProvider.HENGJIAN)
.totalQuantity(totalQuantityOf(row))
.estimatedOutboundAt(parseTime(row.estimateOutboundTime))
.estimatedInboundAt(parseTime(row.estimateInboundTime))
.remark(trimToNull(row.remark))
.projectCode(trimToNull(row.projectUnicode));
addAttachments(builder, row.attachesEntityList);
return builder.build();
}
private static int totalQuantityOf(HengjianTransferDtos.TransferRow row) {
int total = 0;
if (row.details != null) {
for (HengjianTransferDtos.TransferRow.Detail detail : row.details) {
if (detail != null && detail.qty != null) {
total += detail.qty;
}
}
}
return total;
}
/** 附件:类型保留仓方原值(0/1/2/3 或 Shippinglabel 等)。 */
private static void addAttachments(TransferOrder.Builder builder,
List<HengjianTransferDtos.TransferRow.Attachment> attachments) {
if (attachments == null) {
return;
}
for (HengjianTransferDtos.TransferRow.Attachment attachment : attachments) {
if (attachment == null) {
continue;
}
builder.attachment(common.ecommerce.warehouse.model.WarehouseAttachment.builder()
.name(trimToNull(attachment.name))
.type(trimToNull(attachment.type))
.url(trimToNull(attachment.url))
.build());
}
}
/** 列表 → 统一 Page。 */
public static Page<TransferOrder> toPage(HengjianTransferDtos.PageData data,
String cursor) {
if (data == null) {
return Page.last(new ArrayList<TransferOrder>());
}
List<TransferOrder> out = new ArrayList<TransferOrder>();
if (data.content != null) {
for (HengjianTransferDtos.TransferRow row : data.content) {
if (row != null) {
out.add(toOrder(row));
}
}
}
boolean last = data.last != null ? data.last
: (data.numberOfElements != null && data.numberOfElements < rowsOf(0));
if (last) {
return Page.last(out);
}
// 响应 number 是 0 基,请求 page 是 1 基:下一页 = number + 2
int next = (data.number == null ? 0 : data.number) + 2;
return Page.of(out, String.valueOf(next));
}
// ================================================================ 工具
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) {
try {
return LocalDate.parse(v, DATE).atStartOfDay().toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException ignored) {
try {
return Instant.parse(v);
} catch (DateTimeParseException alsoIgnored) {
return null;
}
}
}
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

294
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTransferDtos.java

@ -0,0 +1,294 @@ @@ -0,0 +1,294 @@
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><b>创建接口真机确认的必填项</b>(按校验顺序):</p>
* <pre>
* outOrgWarehouseCode(调出仓库不能为空)
* inOrgWarehouseCode(调入仓库不能为空)
* estimateOutboundTime(期望出库日期不能为空)
* estimateInboundTime(期望入库日期不能为空)
* </pre>
* <p>文档还标了 {@code projectUnicode} / {@code transportationType} / {@code inventoryType} /
* {@code isLabel} / {@code receiveStore} / 六个 {@code shipTo*} 为必填,但<b>真机校验里没有它们</b>
* ——不传都能过参数校验(只停在鉴权处)。按选填实现,与 {@code currency}(入库创建)
* 是同一类情况。</p>
*
* <p><b>响应 {@code data} 是字符串</b>(调拨计划单号),不是对象。</p>
*/
public final class HengjianTransferDtos {
private HengjianTransferDtos() {
}
// ================================================================ 创建
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateRequest {
/** 项目编号;文档标必填,真机不校验。 */
public String projectUnicode;
/** 调出仓库;必填。外部仓库填 {@code Other}。 */
public String outOrgWarehouseCode;
/** 调入仓库;必填。外部仓库填 {@code Other}。 */
public String inOrgWarehouseCode;
/** 运输方式:1 客户安排 / 2 仓库安排。 */
public Integer transportationType;
/** 库存类型:0 可售 / 1 不可售。 */
public Integer inventoryType;
/** 是否更换产品标:1 是 / 0 否。 */
public Integer isLabel;
/** 来源单号(参考字段);我们下发时用 transferRequestNo。 */
public String sourceNo;
/** 期望出库日期 {@code yyyy-MM-dd HH:mm:ss};必填。 */
public String estimateOutboundTime;
/** 期望入库日期 {@code yyyy-MM-dd HH:mm:ss};必填。 */
public String estimateInboundTime;
/** Amazon ShipmentId(参考字段)。 */
public String shipmentId;
/** Amazon referenceId(参考字段);<b>文档里就是三个 f</b>,照抄。 */
public String refferenceId;
/** 目的地址 CODE,默认等于调入仓库。 */
public String receiveStore;
public String shipToCountry;
public String shipToState;
public String shipToCity;
public String shipToPostal;
public String shipToAddress1;
public String shipToAddress2;
public String shipToContact;
public String shipToTelephone;
/** 提货日期 {@code yyyy-MM-dd}。 */
public String deliveryDate;
public String remark;
/** 产品明细;必填。 */
public List<Detail> details;
/** 产品明细行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Detail {
/** 调拨产品 SKU;必填。 */
public String sku;
/** 数量;<b>文档标 STRING</b>(不是 INTEGER),照抄。 */
public String qty;
}
}
/** 创建响应:{@code data} 是调拨计划单号字符串。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CreateResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
/** 调拨计划单号(字符串,不是对象)。 */
@JsonProperty("data")
public String data;
}
// ================================================================ 查询
/** 查询响应外层(分页信封)。 */
@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<TransferRow> 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;
}
/** 一行调拨计划。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferRow {
/** 仓方内部 id。 */
@JsonProperty("id")
public Long id;
@JsonProperty("projectUnicode")
public String projectUnicode;
/** 调拨计划单号。 */
@JsonProperty("transferOutboundPlanNo")
public String transferOutboundPlanNo;
/**
* 单据状态:数字(0/3/5/7/8/10/15/20/25/70/90/100/110)。
*
* <p>用 String 接住——文档标 INTEGER,但同站的其它接口出现过数字串,
* 两种都能解析。</p>
*/
@JsonProperty("transferOutboundPlanStatus")
public String transferOutboundPlanStatus;
@JsonProperty("outOrgWarehouseCode")
public String outOrgWarehouseCode;
@JsonProperty("inOrgWarehouseCode")
public String inOrgWarehouseCode;
/** 运输方式:1 客户安排 / 2 仓库安排。 */
@JsonProperty("transportationType")
public Integer transportationType;
/** 库存类型:0 可售 / 1 不可售。 */
@JsonProperty("inventoryType")
public Integer inventoryType;
/** 是否更换产品标:1 是 / 0 否。 */
@JsonProperty("isLabel")
public Integer isLabel;
@JsonProperty("sourceNo")
public String sourceNo;
/** 期望出库 / 入库时间 {@code yyyy-MM-dd HH:mm:ss}。 */
@JsonProperty("estimateOutboundTime")
public String estimateOutboundTime;
@JsonProperty("estimateInboundTime")
public String estimateInboundTime;
/** 实际出库时间(示例里有,字段表没列)。 */
@JsonProperty("actualOutboundTime")
public String actualOutboundTime;
@JsonProperty("shipmentId")
public String shipmentId;
/** referenceId;文档拼成 {@code refferenceId},照抄。 */
@JsonProperty("refferenceId")
public String refferenceId;
@JsonProperty("receiveStore")
public String receiveStore;
@JsonProperty("shipToCountry")
public String shipToCountry;
@JsonProperty("shipToState")
public String shipToState;
@JsonProperty("shipToCity")
public String shipToCity;
@JsonProperty("shipToPostal")
public String shipToPostal;
@JsonProperty("shipToAddress1")
public String shipToAddress1;
@JsonProperty("shipToAddress2")
public String shipToAddress2;
@JsonProperty("shipToContact")
public String shipToContact;
@JsonProperty("shipToTelephone")
public String shipToTelephone;
@JsonProperty("remark")
public String remark;
/** 产品明细。 */
@JsonProperty("details")
public List<Detail> details;
/** 附件。 */
@JsonProperty("attachesEntityList")
public List<Attachment> attachesEntityList;
/** 产品明细行(查询响应)。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Detail {
@JsonProperty("sku")
public String sku;
@JsonProperty("sellerSku")
public String sellerSku;
@JsonProperty("parentSku")
public String parentSku;
@JsonProperty("gtin")
public String gtin;
@JsonProperty("qty")
public Integer qty;
@JsonProperty("remark")
public String remark;
/** 出库数量。 */
@JsonProperty("qtyOutbound")
public Integer qtyOutbound;
/** 入库数量。 */
@JsonProperty("qtyInbound")
public Integer qtyInbound;
}
/** 附件行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Attachment {
@JsonProperty("attachmentId")
public Long attachmentId;
/** 附件类型:0 Shippinglabel / 1 Packinglist / 2 BOL / 3 Other。 */
@JsonProperty("type")
public String type;
@JsonProperty("transPlanId")
public Long transPlanId;
/** 调拨计划单号(示例里有,字段表也有)。 */
@JsonProperty("transferOutboundPlanNo")
public String transferOutboundPlanNo;
@JsonProperty("sourceNo")
public String sourceNo;
@JsonProperty("name")
public String name;
@JsonProperty("url")
public String url;
}
}
}

86
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianTransferStatus.java

@ -0,0 +1,86 @@ @@ -0,0 +1,86 @@
package common.ecommerce.hengjian.enums;
import common.ecommerce.warehouse.enums.TransferStatus;
/**
* 恒健调拨计划单状态({@code transferOutboundPlanStatus})。
*
* <p>码表来自《调拨计划单查询接口》:0 草稿 / 3 已驳回 / 5 待审核 / 7 审核通过 /
* 8 待确认 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 /
* 90 已关闭 / 100 取消中 / 110 已取消。</p>
*
* <p><b>精确匹配</b>,未知归 {@link #UNKNOWN} 不猜;原值同时写进
* {@code TransferOrder.rawStatus}。</p>
*
* <p>注意 {@code 100}(取消中)与 {@code 110}(已取消)是两个状态——
* 合并就分不出「取消请求已发出」和「仓方已确认取消」。</p>
*/
public enum HengjianTransferStatus {
/** 0 草稿。 */
DRAFT("0", TransferStatus.DRAFT),
/** 3 已驳回。 */
REJECTED("3", TransferStatus.REJECTED),
/** 5 待审核。 */
PENDING_REVIEW("5", TransferStatus.PENDING_REVIEW),
/** 7 审核通过。 */
APPROVED("7", TransferStatus.APPROVED),
/** 8 待确认。 */
PENDING_CONFIRM("8", TransferStatus.PENDING_CONFIRM),
/** 10 待出库。 */
PENDING_OUTBOUND("10", TransferStatus.PENDING_OUTBOUND),
/** 15 出库中。 */
OUTBOUNDING("15", TransferStatus.OUTBOUNDING),
/** 20 待入库。 */
PENDING_INBOUND("20", TransferStatus.PENDING_INBOUND),
/** 25 入库中。 */
INBOUNDING("25", TransferStatus.INBOUNDING),
/** 70 已完成。 */
COMPLETED("70", TransferStatus.COMPLETED),
/** 90 已关闭。 */
CLOSED("90", TransferStatus.CLOSED),
/** 100 取消中。 */
CANCELLING("100", TransferStatus.CANCELLING),
/** 110 已取消。 */
CANCELLED("110", TransferStatus.CANCELLED),
/** 无法识别。 */
UNKNOWN(null, TransferStatus.UNKNOWN);
private final String rawCode;
private final TransferStatus core;
HengjianTransferStatus(String rawCode, TransferStatus core) {
this.rawCode = rawCode;
this.core = core;
}
/** 恒健原始码;null 表示无法识别。 */
public String rawCode() {
return rawCode;
}
public TransferStatus toCore() {
return core;
}
/** 精确匹配(忽略首尾空白);空值 / 未收录归 {@link #UNKNOWN}。 */
public static HengjianTransferStatus of(String raw) {
if (raw == null) {
return UNKNOWN;
}
String s = raw.trim();
if (s.isEmpty()) {
return UNKNOWN;
}
for (HengjianTransferStatus v : values()) {
if (v.rawCode != null && s.equals(v.rawCode)) {
return v;
}
}
return UNKNOWN;
}
public static TransferStatus toCore(String raw) {
return of(raw).toCore();
}
}

371
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTransferTest.java

@ -0,0 +1,371 @@ @@ -0,0 +1,371 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.enums.HengjianTransferStatus;
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.TransferStatus;
import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferQuery;
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.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 调拨计划创建 / 查询 / 取消契约测试。
*/
class HengjianTransferTest {
private static final WarehouseContext CTX = WarehouseContext.of(
"HJ-EFGA", WarehouseProvider.HENGJIAN, "EFGA",
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 TransferCommand.Builder command() {
return TransferCommand.builder()
.transferRequestNo("TF-2026-0001")
.type(TransferType.WAREHOUSE_TO_WAREHOUSE)
.fromWarehouseCode("EFGA")
.toWarehouseCode("EFCA")
.inventoryType(0)
.transportationType(2)
.estimateOutboundDate(LocalDate.parse("2026-12-01"))
.estimateInboundDate(LocalDate.parse("2026-12-10"))
.projectCode("P-1")
.relabelProducts(false)
.line("SKU-A", 3);
}
// ================================================================ 创建
private static RecordingTransport creating() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_CREATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,"
+ "\"message\":\"创建调拨计划单成功\",\"data\":\"HI-TF2212089091\"}"));
}
@Test
void createPostsToTransferPlan() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/transferPlan/create",
transport.lastDataRequest().url());
}
/** 真机确认的四个必填项都要有。 */
@Test
void createSendsMandatoryFields() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"outOrgWarehouseCode", "inOrgWarehouseCode",
"estimateOutboundTime", "estimateInboundTime", "details"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
}
/** 日期补成 yyyy-MM-dd HH:mm:ss(当天 00:00:00,不编造时刻)。 */
@Test
void createFormatsDatesWithMidnight() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command().build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"estimateOutboundTime\":\"2026-12-01 00:00:00\""), body);
assertTrue(body.contains("\"estimateInboundTime\":\"2026-12-10 00:00:00\""), body);
}
/** 数量按字符串下发(恒健该字段标 STRING)。 */
@Test
void detailsQuantityIsString() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command().build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"qty\":\"3\""), "数量必须是字符串,body=" + body);
assertFalse(body.contains("\"qty\":3"), "不能发成数字");
}
/** 外部仓库用 Other;收货地址整组下发。 */
@Test
void createSendsExternalDestination() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command()
.toWarehouseCode("Other")
.externalDestination(true)
.shipTo(ShipTo.builder()
.name("Recv").phone("555").countryCode("US").stateOrProvince("GA")
.city("Atlanta").addressLine1("1 St").addressLine2("Suite 2")
.postalCode("30349").build())
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"inOrgWarehouseCode\":\"Other\""), body);
assertTrue(body.contains("\"shipToCity\":\"Atlanta\""), body);
assertTrue(body.contains("\"shipToContact\":\"Recv\""), body);
assertTrue(body.contains("\"shipToPostal\":\"30349\""), body);
}
/** 未指定运输方式(0)按「仓库安排」兜底并说明;其它值拒绝。 */
@Test
void transportationTypeMapping() {
RecordingTransport transport = creating();
adapter(transport).create(CTX, command().transportationType(0).build());
assertTrue(transport.lastDataRequest().body().contains("\"transportationType\":2"));
RecordingTransport customer = creating();
adapter(customer).create(CTX, command().transportationType(1).build());
assertTrue(customer.lastDataRequest().body().contains("\"transportationType\":1"));
RecordingTransport bad = creating();
assertThrows(IllegalArgumentException.class,
() -> adapter(bad).create(CTX, command().transportationType(9).build()));
}
/** 缺出库 / 入库日期时本地拒绝:恒健必填,发出去也会被抓。 */
@Test
void createRequiresBothDates() {
RecordingTransport transport = creating();
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).create(CTX, TransferCommand.builder()
.transferRequestNo("TF-X").type(TransferType.WAREHOUSE_TO_WAREHOUSE)
.fromWarehouseCode("EFGA").toWarehouseCode("EFCA")
.line("SKU-A", 1)
.build()));
assertTrue(transport.dataRequests().isEmpty());
}
/** 拿不到单号不能当成功。 */
@Test
void createRejectsResponseWithoutPlanNo() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_CREATE, req -> Responses.ok(
"{\"code\":200,\"message\":\"OK\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).create(CTX, command().build()));
assertTrue(ex.getMessage().contains("plan no"), ex.getMessage());
}
@Test
void createdOrderCarriesProviderNo() {
TransferOrder order = adapter(creating()).create(CTX, command().build());
assertEquals("TF-2026-0001", order.transferRequestNo());
assertEquals("HI-TF2212089091", order.providerTransferNo());
assertEquals("EFGA", order.fromWarehouseCode());
assertEquals("EFCA", order.toWarehouseCode());
assertEquals(3, order.totalQuantity());
// 创建接口不回状态:保持 UNKNOWN,不拿请求侧的值冒充
assertEquals(TransferStatus.UNKNOWN, order.status());
assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider());
}
// ================================================================ 查询
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\":[{"
+ "\"id\":45595,\"transferOutboundPlanNo\":\"XH-TF2604100004\","
+ "\"projectUnicode\":\"德姆勒-分销\",\"transferOutboundPlanStatus\":70,"
+ "\"outOrgWarehouseCode\":\"EFGA\",\"inOrgWarehouseCode\":\"Other\","
+ "\"transportationType\":2,\"inventoryType\":0,\"isLabel\":0,"
+ "\"sourceNo\":\"TF-2026-0001\","
+ "\"estimateOutboundTime\":\"2026-12-01 00:00:00\","
+ "\"estimateInboundTime\":\"2026-12-10 00:00:00\","
+ "\"details\":[{\"sku\":\"SKU-A\",\"qty\":3,\"qtyOutbound\":3,\"qtyInbound\":0}],"
+ "\"attachesEntityList\":[{\"attachmentId\":1,\"type\":\"Other\","
+ "\"name\":\"test.jpg\",\"url\":\"https://cdn/x.jpg\"}]}]}}";
private static RecordingTransport paging() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_PAGE, req -> Responses.ok(PAGE_BODY));
}
@Test
void querySendsPagingAndFilters() {
RecordingTransport transport = paging();
adapter(transport).queryTransfers(CTX, TransferQuery.builder()
.sourceNo("TF-2026-0001")
.providerTransferNo("XH-TF2604100004")
.projectCode("P-1")
.fromWarehouseCode("EFGA")
.toWarehouseCode("Other")
.pageSize(10)
.build());
String url = transport.lastDataRequest().url();
assertEquals("GET", transport.lastDataRequest().method());
assertTrue(url.contains("page=1"), url);
assertTrue(url.contains("rows=10"), url);
assertTrue(url.contains("sidx=id"), url);
assertTrue(url.contains("sort=desc"), url);
assertTrue(url.contains("sourceNo=TF-2026-0001"), url);
assertTrue(url.contains("transferOutboundPlanNo=XH-TF2604100004"), url);
assertTrue(url.contains("outOrgWarehouseCode=EFGA"), url);
assertTrue(url.contains("inOrgWarehouseCode=Other"), url);
}
@Test
void queryMapsOrder() {
Page<TransferOrder> page = adapter(paging()).queryTransfers(CTX,
TransferQuery.builder().pageSize(10).build());
assertEquals(1, page.size());
assertFalse(page.hasMore());
TransferOrder order = page.items().get(0);
assertEquals("TF-2026-0001", order.transferRequestNo(), "来源单号优先");
assertEquals("XH-TF2604100004", order.providerTransferNo());
assertEquals("45595", order.providerId());
assertEquals(TransferStatus.COMPLETED, order.status());
assertEquals("70", order.rawStatus());
// 调入仓是 Other → 调拨出库
assertEquals(TransferType.OUTBOUND, order.type());
assertEquals("德姆勒-分销", order.projectCode());
assertEquals(3, order.totalQuantity());
assertEquals(Instant.parse("2026-12-01T00:00:00Z"), order.estimatedOutboundAt());
assertEquals(1, order.attachments().size());
assertEquals("test.jpg", order.attachments().get(0).name());
}
/** 页大小超 100(文档明写)拒绝,不截断。 */
@Test
void queryRejectsRowsAboveLimit() {
RecordingTransport transport = paging();
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).queryTransfers(CTX,
TransferQuery.builder().pageSize(500).build()));
assertTrue(transport.dataRequests().isEmpty());
}
/** 未到末页时给出下一页游标。 */
@Test
void queryAdvancesCursor() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_PAGE, req -> Responses.ok(
"{\"code\":200,\"data\":{\"last\":false,\"number\":0,\"content\":[{"
+ "\"sourceNo\":\"TF-1\",\"transferOutboundPlanNo\":\"XH-1\","
+ "\"transferOutboundPlanStatus\":5,\"outOrgWarehouseCode\":\"EFGA\","
+ "\"inOrgWarehouseCode\":\"EFCA\"}]}}"));
Page<TransferOrder> page = adapter(transport).queryTransfers(CTX,
TransferQuery.builder().pageSize(1).build());
assertTrue(page.hasMore());
assertEquals("2", page.nextCursor());
}
/** 文档里的 13 个状态值都要映射对。 */
@Test
void allDocumentedStatusesMap() {
assertEquals(TransferStatus.DRAFT, HengjianTransferStatus.toCore("0"));
assertEquals(TransferStatus.REJECTED, HengjianTransferStatus.toCore("3"));
assertEquals(TransferStatus.PENDING_REVIEW, HengjianTransferStatus.toCore("5"));
assertEquals(TransferStatus.APPROVED, HengjianTransferStatus.toCore("7"));
assertEquals(TransferStatus.PENDING_CONFIRM, HengjianTransferStatus.toCore("8"));
assertEquals(TransferStatus.PENDING_OUTBOUND, HengjianTransferStatus.toCore("10"));
assertEquals(TransferStatus.OUTBOUNDING, HengjianTransferStatus.toCore("15"));
assertEquals(TransferStatus.PENDING_INBOUND, HengjianTransferStatus.toCore("20"));
assertEquals(TransferStatus.INBOUNDING, HengjianTransferStatus.toCore("25"));
assertEquals(TransferStatus.COMPLETED, HengjianTransferStatus.toCore("70"));
assertEquals(TransferStatus.CLOSED, HengjianTransferStatus.toCore("90"));
assertEquals(TransferStatus.CANCELLING, HengjianTransferStatus.toCore("100"));
assertEquals(TransferStatus.CANCELLED, HengjianTransferStatus.toCore("110"));
}
/** 100(取消中)与 110(已取消)不能合并。 */
@Test
void cancellingIsNotCancelled() {
assertEquals(TransferStatus.CANCELLING, HengjianTransferStatus.toCore("100"));
assertEquals(TransferStatus.CANCELLED, HengjianTransferStatus.toCore("110"));
}
@Test
void unknownStatusIsNotGuessed() {
assertEquals(TransferStatus.UNKNOWN, HengjianTransferStatus.toCore("999"));
assertEquals(TransferStatus.UNKNOWN, HengjianTransferStatus.toCore(null));
}
// ================================================================ 取消
@Test
void cancelSendsSourceNoAsQueryParam() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_CANCEL, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"调拨计划取消成功\"}"));
adapter(transport).deleteTransfer(CTX, "TF-2026-0001");
assertEquals("GET", transport.lastDataRequest().method());
String url = transport.lastDataRequest().url();
assertTrue(url.contains("/v1/transferPlan/cancel?"), url);
assertTrue(url.contains("sourceNo=TF-2026-0001"), url);
}
@Test
void cancelRequiresSourceNo() {
assertThrows(IllegalArgumentException.class,
() -> adapter(RecordingTransport.create()).deleteTransfer(CTX, " "));
}
/** 仓方拒绝取消时原样抛业务异常(不伪装成成功)。 */
@Test
void cancelFailureIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRANSFER_CANCEL, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"调拨计划取消失败 test001:未查询到对应调拨计划数据\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).deleteTransfer(CTX, "test001"));
assertTrue(ex.getMessage().contains("未查询到对应调拨计划数据"), ex.getMessage());
}
// ================================================================ 能力位
@Test
void declaresTransferCapability() {
assertTrue(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.TRANSFER));
}
/** 审核 / 详情接口恒健没有:默认拒绝。 */
@Test
void approveAndGetTransferUnsupported() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertThrows(RuntimeException.class, () -> adapter.approve(CTX, "TF-1"));
assertThrows(RuntimeException.class, () -> adapter.getTransfer(CTX, "TF-1"));
}
}
Loading…
Cancel
Save