Browse Source

feat(hengjian): 对接退货详情 / 列表 / 处理单列表 / 填写处理方式

四个接口真机均确认存在,但都不做参数校验(thirdParty 那两个回 403,
handlePage / handlingMethod 回 500+999999),必填项按文档实现。

- 请求形态两套:thirdParty 两个是双层包裹 params,handlePage 与
  handlingMethod 是平铺;发错形态仓方当成空请求
- 详情:SKU 明细落 lines,换标明细 changeSku 落 newSku;
  待处理 / 已处理列表不塞进 lines(那是 SKU 维度)
- sourceType 两页文档顺序相反(创建页 1 无来源、详情页 1 销售),
  适配器不解释,原值保留在 type()
- 列表:page/size 文档标 string 转字符串下发;状态过滤是单值,多给即拒绝;
  仓库 code 收逗号拼接;RETURNING 对应 20 或 35,无法唯一映射返回 null
- 处理单列表:过滤条件全是数组;返回仓方处理行(无对应统一模型);
  时间戳是 ISO 带时区,解析转换后使用
- 处理方式:四项定位(returnPlanNo+returnNo+erpSku+tracking)不用行 id;
  两级处理方式;继续拍照必须给 photosQuantity
- core ReturnProcessCommand:lineId 改 Long 可空、disposition 改可空
  (与 primaryHandlingMethod 至少给一个)、补 6 个字段;运去哪缺 lineId 时
  在适配器里显式拒绝,已加守卫

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

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 4 days ago
parent
commit
5169fb3107
  1. 8
      README.md
  2. 91
      docs-warehouse/hengjian/README.md
  3. 143
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java
  4. 31
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  5. 121
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  6. 486
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java
  7. 252
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnDetailDtos.java
  8. 214
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnHandleDtos.java
  9. 152
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnListDtos.java
  10. 368
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
  11. 6
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java

8
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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货计划创建查询处理) |
依赖方向:
```
@ -383,7 +383,7 @@ common.ecommerce @@ -383,7 +383,7 @@ common.ecommerce
│ HengjianFeeMapper / HengjianEstimateMapper /
│ HengjianInventoryMapper / HengjianInboundMapper /
│ HengjianInboundQueryMapper / HengjianTransferMapper /
│ HengjianReturnMapper
│ HengjianReturnMapper / HengjianReturnQueryMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
@ -393,7 +393,9 @@ common.ecommerce @@ -393,7 +393,9 @@ common.ecommerce
│ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos /
│ HengjianInventoryDtos / HengjianInventoryMovementDtos /
│ HengjianInboundCreateDtos / HengjianInboundQueryDtos /
│ HengjianTransferDtos / HengjianReturnPlanCreateDtos
│ HengjianTransferDtos / HengjianReturnPlanCreateDtos /
│ HengjianReturnDetailDtos / HengjianReturnListDtos /
│ HengjianReturnHandleDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter

91
docs-warehouse/hengjian/README.md

@ -85,7 +85,11 @@ @@ -85,7 +85,11 @@
| 23 | 调拨计划查询 | `GET /v1/transferPlan/findByPage` | `TRANSFER` | ✅ |
| 24 | 调拨计划取消 | `GET /v1/transferPlan/cancel` | `TRANSFER` | ✅ |
| 25 | 退货计划创建 | `POST /v1/saleReturn/thirdParty/saveReturnPlan` | `RETURN` | ✅ |
| 26 | 回调 | — | — | ❌ 文档无回调页 |
| 26 | 退货计划详情 | `POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo` | `RETURN` | ✅ |
| 27 | 退货计划列表 | `POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage` | `RETURN` | ✅ |
| 28 | 退货处理单列表 | `POST /v1/saleReturn/getReturnPlanHandlePage` | `RETURN` | ✅ |
| 29 | 填写退货处理方式 | `POST /v1/saleReturn/handlingMethod` | `RETURN` | ✅ |
| 30 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@ -425,6 +429,85 @@ productItems(入库产品明细必须填写) @@ -425,6 +429,85 @@ productItems(入库产品明细必须填写)
**未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。
### 退货查询与处理方式 —— 已接入
#### 请求形态有两套,不能混
| 接口 | 形态 |
|---|---|
| `getReturnPlanOrderInfo` | **双层包裹** `{"params":{"orderNo"}}` |
| `getReturnPlanOrderPage` | **双层包裹**,`page` / `size` 文档标 **string** |
| `getReturnPlanHandlePage` | **平铺**(无 `params`) |
| `handlingMethod` | **平铺** |
发错形态仓方会当成空请求。
无 token 的表现也不同:thirdParty 那两个直接用 `403`,
`getReturnPlanHandlePage` / `handlingMethod` 回 `500 + 999999 + "查询失败/处理失败:Unauthorized"`。
**这四个接口都不做参数校验**,必填项只能按文档实现。
#### 三套码表,别混
| 码表 | 取值 |
|---|---|
| 计划状态 `returnPlanStatus` | 0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 / 25 已完成 / 30 已取消 / 35 处理中 |
| 处理状态 `handlingStatus` | 5 待处理 / 10 处理中 / 15 已完成 / 20 已取消 |
| 主要处理方式 `primaryHandlingMethod` | 101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / 201 销毁 / 202 上架良品 / 203 换标上架 / 204 卖家自提 / 205 重新包装 / 206 仓库拆箱判断 |
同一个 `20`:计划状态是「待处理」,处理状态是「已取消」。三套互不通用。
#### 详情(`getReturnPlanOrderInfo`)
- 单号既可是计划单号,也可是来源单号——响应同时回 `returnPlanNo` 与 `sourceOrderNo`。
- 双号映射:`returnRequestNo = sourceOrderNo`(缺失时退回计划单号)、
`providerReturnId = returnPlanNo`。
- SKU 明细 `returnPlanSkuList` → `WarehouseReturn.lines()`;
换标上架明细 `relabelShelfSkuItems[].changeSku` → `newSku`。
- `returnPlanHandleList` / `returnPlanExecuteDetails`(待处理 / 已处理)
**不塞进 `lines`**(那是 SKU 维度),需要处理单时用处理单列表接口查。
- `sourceType` **两页文档顺序相反**:创建页写「1 无来源 2 销售」,详情页写「1 销售 2 无来源」。
适配器不解释,原值保留在 `type()`。
- `data` 为空 → 返回 `null`。
#### 列表(`getReturnPlanOrderPage`)
- `page` / `size` 文档标 **string**,下发转字符串。
- **状态过滤是单值**(`returnPlanStatus` 不是数组);给多个时**拒绝**,
静默只取一个会让调用方以为筛全了。
- `queryDataType`(1 创建 / 2 修改 / 4 完成)+ 时间区间,与
`queryType`(1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking)+ `queryValue`
是两组独立的过滤口径。
- 仓库 code 收**逗号拼接的字符串**,不是数组。
- `RETURNING` 无法唯一映射回恒健状态(对应 20 或 35),映射函数返回 null,
调用方要明确选一个。
#### 处理单列表(`getReturnPlanHandlePage`)
- 过滤条件**全是数组**;`handlingStatusList` 用 5/10/15/20 那套码。
- 恒健没有对应的统一模型,适配器直接返回仓方的处理单行
(`HengjianReturnHandleDtos.HandleRow`),供宿主填写处理方式与回收照片。
- 时间戳是 ISO 带时区(`2025-08-14T01:32:32.000+0000`),解析时转换成 `Z` 再解析。
#### 填写处理方式(`handlingMethod`)
- 用 **`returnPlanNo + returnNo + erpSku + tracking` 四项定位**,不用行 id——
与运去哪的条目处理接口不同(那个只认 `items[].id`)。
- **两级处理方式**:`handlingMethod`(1 继续拍照 / 2 处理方式)是开关,
`primaryHandlingMethod`(101~206)是具体动作。
- `handlingMethod=1`(继续拍照)必须给正的 `photosQuantity`,本地先挡。
- core 的 `ReturnProcessDisposition` 只能映射 4 个:销毁 201 / 上架良品 202 /
换标上架 203 / 卖家自提 204。**拍照类(101~103)、重新包装(205)、
仓库拆箱判断(206)必须显式给仓方原值**——core 没有对应语义,强行归一会丢信息。
#### 为这四个接口给 core 改的东西
`ReturnProcessCommand`:
- `lineId` 从 `long` 改为 `Long` 且可空(恒健按四项定位,不用行 id);
需要行 id 的仓(运去哪)在适配器里显式校验,已加守卫。
- `disposition` 改为可空,与 `primaryHandlingMethod` **至少给一个**。
- 新增 `returnNo` / `erpSku` / `tracking` / `handlingMethod` /
`primaryHandlingMethod` / `photosQuantity`。
### 退货计划创建(`/v1/saleReturn/thirdParty/saveReturnPlan`)—— 已接入
**请求是双层包裹**:所有业务字段都在 `params` 下,不是顶层。发错层级仓方会当成空请求。
@ -725,7 +808,8 @@ warehouse-sdk-hengjian/ @@ -725,7 +808,8 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianInboundMapper.java 入库计划创建
│ │ ├── HengjianInboundQueryMapper.java 入库详情 / 列表
│ │ ├── HengjianTransferMapper.java 调拨创建 / 查询 / 取消
│ │ └── HengjianReturnMapper.java 退货计划创建
│ │ ├── HengjianReturnMapper.java 退货计划创建
│ │ └── HengjianReturnQueryMapper.java 退货详情 / 列表 / 处理单 / 处理方式
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
@ -761,13 +845,14 @@ warehouse-sdk-hengjian/ @@ -761,13 +845,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianInboundQueryTest.java 18 个:详情映射 / 状态码表 / 列表过滤 / 分页
├── adapter/HengjianTransferTest.java 21 个:必填 / 字符串数量 / 外部仓 / 13 状态 / 取消
├── adapter/HengjianReturnCreateTest.java 16 个:params 包裹 / 行级四项 / 跟踪号回退 / 8 状态
├── adapter/HengjianReturnQueryTest.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` 全部通过(275 个 + 4 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(293 个 + 4 个跳过)。
## 5. 探针用法

143
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java

@ -12,36 +12,84 @@ public final class ReturnProcessCommand { @@ -12,36 +12,84 @@ public final class ReturnProcessCommand {
private final String providerReturnNo;
/**
* 仓侧明细行 id。
* 仓侧明细行 id;<b>可为 null</b>。
*
* <p>只来自「退货查询接口」的 items[].id。<b>运去哪没有这个接口</b>,
* 其回调(API 142)也不带 id,因此该仓实际无法构造本命令。</p>
*
* <p>恒健的「填写退货处理方式」不用行 id,而是用
* {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位,所以这里允许为空;
* <b>需要行 id 的仓(运去哪)由适配器显式校验</b>,不在构造期一刀切。</p>
*/
private final long lineId;
private final Long lineId;
private final ReturnProcessDisposition disposition;
/** 换标上架时的新 SKU;其它处理方式必须为 null。 */
private final String newSku;
private final String remark;
// ---- 恒健「填写退货处理方式」协议字段(其它仓不用)----
/**
* 退货处理单号 / 退货编码。
*
* <p>恒健 {@code returnNo}(来自「退货计划待处理列表」的 {@code returnNo})。
* 与 {@link #providerReturnNo()}(计划单号)是两个号。</p>
*/
private final String returnNo;
/** ERP SKU;恒健 {@code erpSku},定位待处理行的四项之一。 */
private final String erpSku;
/** 跟踪号;恒健 {@code tracking},定位待处理行的四项之一。 */
private final String tracking;
/**
* 处理方式:1 继续拍照 / 2 处理方式。
*
* <p>恒健 {@code handlingMethod}。<b>与 {@link #disposition()} 不是一回事</b>:
* 这个是「先拍照还是直接处理」的开关,那个是具体怎么处理。</p>
*/
private final Integer handlingMethod;
/**
* 主要处理方式(仓方原值):101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 /
* 201 销毁 / 202 上架(良品)/ 203 换标上架(良品)/ 204 卖家自提 /
* 205 重新包装 / 206 仓库拆箱判断。
*
* <p>保留仓方原值:101~103 是「拍照」类动作,core 的
* {@link ReturnProcessDisposition} 没有对应值,强行归一会丢信息。</p>
*/
private final String primaryHandlingMethod;
/** 拍照数量;恒健 {@code photosQuantity}。null 表示不传。 */
private final Integer photosQuantity;
private ReturnProcessCommand(Builder b) {
if (b.providerReturnNo == null || b.providerReturnNo.trim().isEmpty()) {
throw new IllegalArgumentException("providerReturnNo must not be blank");
}
this.providerReturnNo = b.providerReturnNo.trim();
if (b.lineId <= 0) {
throw new IllegalArgumentException("lineId must be positive");
if (b.lineId != null && b.lineId <= 0) {
throw new IllegalArgumentException("lineId must be positive when given");
}
this.lineId = b.lineId;
this.disposition = java.util.Objects.requireNonNull(b.disposition, "disposition");
// disposition 与 primaryHandlingMethod 至少给一个:
// 运去哪只有统一枚举,恒健只有仓方原值(101~206),两者覆盖的能力不同
if (b.disposition == null && !hasText(b.primaryHandlingMethod)) {
throw new IllegalArgumentException(
"either disposition or primaryHandlingMethod is required");
}
this.disposition = b.disposition;
boolean needsSku = b.disposition == ReturnProcessDisposition.RESTOCK_RELABEL;
if (needsSku && (b.newSku == null || b.newSku.trim().isEmpty())) {
throw new IllegalArgumentException("newSku is required when disposition is RESTOCK_RELABEL");
}
if (!needsSku && b.newSku != null && !b.newSku.trim().isEmpty()) {
if (!needsSku && b.disposition != null && hasText(b.newSku)) {
throw new IllegalArgumentException("newSku is only valid when disposition is RESTOCK_RELABEL");
}
this.newSku = b.newSku;
this.remark = b.remark;
this.returnNo = b.returnNo;
this.erpSku = b.erpSku;
this.tracking = b.tracking;
this.handlingMethod = b.handlingMethod;
this.primaryHandlingMethod = b.primaryHandlingMethod;
this.photosQuantity = b.photosQuantity;
}
public static Builder builder() {
@ -53,11 +101,42 @@ public final class ReturnProcessCommand { @@ -53,11 +101,42 @@ public final class ReturnProcessCommand {
return providerReturnNo;
}
/** 仓侧明细行 id。 */
public long lineId() {
/** 仓侧明细行 id;可能为 null(恒健按四项定位,不用行 id)。 */
public Long lineId() {
return lineId;
}
/** 退货编码 / 处理单号;null 表示不传。 */
public String returnNo() {
return returnNo;
}
/** ERP SKU;null 表示不传。 */
public String erpSku() {
return erpSku;
}
/** 跟踪号;null 表示不传。 */
public String tracking() {
return tracking;
}
/** 处理方式:1 继续拍照 / 2 处理方式;null 表示不传。 */
public Integer handlingMethod() {
return handlingMethod;
}
/** 主要处理方式(仓方原值);null 表示不传。 */
public String primaryHandlingMethod() {
return primaryHandlingMethod;
}
/** 拍照数量;null 表示不传。 */
public Integer photosQuantity() {
return photosQuantity;
}
/** 检验后的处理方式(统一枚举);null 表示只给了仓方原值。 */
public ReturnProcessDisposition disposition() {
return disposition;
}
@ -70,10 +149,20 @@ public final class ReturnProcessCommand { @@ -70,10 +149,20 @@ public final class ReturnProcessCommand {
return remark;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
public static final class Builder {
private String providerReturnNo;
private long lineId;
private Long lineId;
private ReturnProcessDisposition disposition;
private String returnNo;
private String erpSku;
private String tracking;
private Integer handlingMethod;
private String primaryHandlingMethod;
private Integer photosQuantity;
private String newSku;
private String remark;
@ -102,6 +191,42 @@ public final class ReturnProcessCommand { @@ -102,6 +191,42 @@ public final class ReturnProcessCommand {
return this;
}
/** 退货编码 / 处理单号。 */
public Builder returnNo(String v) {
this.returnNo = v;
return this;
}
/** ERP SKU。 */
public Builder erpSku(String v) {
this.erpSku = v;
return this;
}
/** 跟踪号。 */
public Builder tracking(String v) {
this.tracking = v;
return this;
}
/** 处理方式:1 继续拍照 / 2 处理方式。 */
public Builder handlingMethod(Integer v) {
this.handlingMethod = v;
return this;
}
/** 主要处理方式(仓方原值)。 */
public Builder primaryHandlingMethod(String v) {
this.primaryHandlingMethod = v;
return this;
}
/** 拍照数量。 */
public Builder photosQuantity(Integer v) {
this.photosQuantity = v;
return this;
}
public ReturnProcessCommand build() {
return new ReturnProcessCommand(this);
}

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

@ -253,6 +253,37 @@ public final class HengjianConstants { @@ -253,6 +253,37 @@ public final class HengjianConstants {
"/v1/saleReturn/thirdParty/saveReturnPlan";
/**
* 退货计划详情({@code POST},请求双层包裹 {@code {"params":{"orderNo"}}})。
*
* <p>无 token 时直接 403、不做参数校验。</p>
*/
public static final String PATH_RETURN_PLAN_DETAIL =
"/v1/saleReturn/thirdParty/getReturnPlanOrderInfo";
/**
* 退货计划列表({@code POST},请求双层包裹)。
*
* <p>{@code page} / {@code size} 文档标 <b>string</b>;状态是<b>单值</b>不是数组。</p>
*/
public static final String PATH_RETURN_PLAN_PAGE =
"/v1/saleReturn/thirdParty/getReturnPlanOrderPage";
/**
* 退货处理单列表({@code POST},请求<b>平铺</b>、无 params 包裹)。
*
* <p>过滤条件全是数组;无 token 时回 500 + 999999 而非 403。</p>
*/
public static final String PATH_RETURN_HANDLE_PAGE = "/v1/saleReturn/getReturnPlanHandlePage";
/**
* 填写退货处理方式({@code POST},请求<b>平铺</b>)。
*
* <p>用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位处理行,
* <b>不用行 id</b>——与运去哪的条目处理接口不同。</p>
*/
public static final String PATH_RETURN_HANDLING_METHOD = "/v1/saleReturn/handlingMethod";
/**
* {@code btChargeAt} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

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

@ -10,6 +10,9 @@ import common.ecommerce.hengjian.dto.HengjianInventoryDtos; @@ -10,6 +10,9 @@ 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.HengjianReturnDetailDtos;
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos;
import common.ecommerce.hengjian.dto.HengjianReturnListDtos;
import common.ecommerce.hengjian.dto.HengjianReturnPlanCreateDtos;
import common.ecommerce.hengjian.dto.HengjianTransferDtos;
import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
@ -47,6 +50,7 @@ import common.ecommerce.warehouse.capability.WarehouseProductCapable; @@ -47,6 +50,7 @@ import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
@ -136,6 +140,14 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -136,6 +140,14 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query";
private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel";
private static final String OP_RETURN_CREATE = "warehouse.return.create";
private static final String OP_RETURN_GET = "warehouse.return.get";
private static final String OP_RETURN_QUERY = "warehouse.return.query";
private static final String OP_RETURN_HANDLES = "warehouse.return.handles";
private static final String OP_RETURN_PROCESS = "warehouse.return.process";
/** 退货列表默认页大小(文档没写,按同站惯例 100)。 */
private static final int PAGE_SIZE_DEFAULT = 100;
/** 退货处理单列表默认页大小(文档写默认 20)。 */
private static final int HANDLE_PAGE_SIZE_DEFAULT = 20;
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -214,31 +226,110 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -214,31 +226,110 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
return HengjianReturnMapper.toCreated(cmd, resp.data);
}
/** 退货查询未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */
/**
* 查退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。
*
* <p>请求是<b>双层包裹</b>({@code {"params":{"orderNo"}}})。单号既可是计划单号,
* 也可是来源单号——详情响应同时回 {@code returnPlanNo} 与 {@code sourceOrderNo}。</p>
*
* <p>查不到({@code data} 为空)返回 null。</p>
*/
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
throw unsupportedReturn("warehouse.return.get", ctx);
String orderNo = trimToNull(returnRequestNo);
if (orderNo == null) {
throw new IllegalArgumentException("hengjian return detail requires an order number");
}
HengjianReturnDetailDtos.DetailRequest body =
HengjianReturnQueryMapper.toDetailRequest(orderNo);
String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_DETAIL, body, OP_RETURN_GET);
JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
HengjianReturnDetailDtos.PlanDetail detail =
json.fromJson(data.toString(), HengjianReturnDetailDtos.PlanDetail.class);
return HengjianReturnQueryMapper.toReturn(detail);
}
/**
* 分页查退货计划({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。
*
* <p>统一模型这个入口只有游标,恒健的列表支持更多条件;这里把游标当页码,
* 其余条件为空——需要按状态 / 时间窗筛时用 {@link #queryReturnsAdvanced}。</p>
*/
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) {
throw unsupportedReturn("warehouse.return.query", ctx);
return queryReturnsAdvanced(ctx, null, null, null, null, null, null, cursor);
}
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
throw unsupportedReturn("warehouse.return.process", ctx);
/**
* 多条件分页查退货计划。
*
* <p><b>恒健只支持单个状态过滤</b>({@code returnPlanStatus} 是单值不是数组),
* 给多个状态时拒绝——静默只取一个会让调用方以为筛全了。</p>
*/
public Page<WarehouseReturn> queryReturnsAdvanced(WarehouseContext ctx,
List<ReturnStatus> statuses,
String startTime, String endTime,
Integer queryDataType,
String queryType, String queryValue,
String cursor) {
if (statuses != null && statuses.size() > 1) {
throw validation(ctx, OP_RETURN_QUERY,
"hengjian return list supports a single status filter, got " + statuses);
}
ReturnStatus single = statuses == null || statuses.isEmpty() ? null : statuses.get(0);
int page = HengjianReturnQueryMapper.pageOf(cursor);
int size = HengjianReturnQueryMapper.rowsOf(PAGE_SIZE_DEFAULT);
HengjianReturnListDtos.ListRequest body = HengjianReturnQueryMapper.toListRequest(
statuses, single, startTime, endTime, queryDataType, queryType, queryValue,
null, page, size);
String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_PAGE, body, OP_RETURN_QUERY);
HengjianReturnListDtos.ListResponse resp =
json.fromJson(raw, HengjianReturnListDtos.ListResponse.class);
return HengjianReturnQueryMapper.toPage(resp == null ? null : resp.data, cursor, size);
}
private WarehouseException unsupportedReturn(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/saleReturn/getReturnPlanHandlePage})。
*
* <p><b>请求是平铺的</b>(无 {@code params} 包裹),与 thirdParty 那两个不同。</p>
*
* <p>恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。</p>
*/
public Page<HengjianReturnHandleDtos.HandleRow> queryReturnHandles(
WarehouseContext ctx, List<String> returnPlanNos, List<String> trackingNos,
List<String> warehouseCodes, List<Integer> handlingStatuses,
String createdStart, String createdEnd, String cursor) {
int page = HengjianReturnQueryMapper.pageOf(cursor);
int size = HengjianReturnQueryMapper.handleRowsOf(HANDLE_PAGE_SIZE_DEFAULT);
HengjianReturnHandleDtos.HandleListRequest body =
HengjianReturnQueryMapper.toHandleListRequest(returnPlanNos, trackingNos,
warehouseCodes, handlingStatuses, createdStart, createdEnd, page, size);
String raw = execute(ctx, HengjianConstants.PATH_RETURN_HANDLE_PAGE, body,
OP_RETURN_HANDLES);
HengjianReturnHandleDtos.HandleListResponse resp =
json.fromJson(raw, HengjianReturnHandleDtos.HandleListResponse.class);
return HengjianReturnQueryMapper.toHandlePage(resp == null ? null : resp.data, cursor, size);
}
/**
* 填写退货处理方式({@code POST /v1/saleReturn/handlingMethod})。
*
* <p><b>请求平铺</b>,用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位,
* <b>不用行 id</b>——与运去哪的条目处理接口不同。</p>
*
* <p>两级处理方式:{@code handlingMethod}(1 继续拍照 / 2 处理方式)是开关,
* {@code primaryHandlingMethod}(101~206)是具体动作。core 的
* {@code ReturnProcessDisposition} 只有部分能映射(销毁 / 上架良品 / 换标上架 / 卖家自提),
* 拍照类与重新包装必须显式给原值。</p>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
HengjianReturnHandleDtos.HandlingMethodRequest body =
HengjianReturnQueryMapper.toHandlingMethodRequest(cmd);
execute(ctx, HengjianConstants.PATH_RETURN_HANDLING_METHOD, body, OP_RETURN_PROCESS);
}
// ------------------------------------------------------------------ 调拨

486
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java

@ -0,0 +1,486 @@ @@ -0,0 +1,486 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianReturnDetailDtos;
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos;
import common.ecommerce.hengjian.dto.HengjianReturnListDtos;
import common.ecommerce.hengjian.enums.HengjianReturnPlanStatus;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseAttachment;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.List;
import java.util.Locale;
/**
* 恒健退货查询 / 处理方式映射。
*
* <h2>三套码表,别混</h2>
* <table border="1">
* <tr><th>码表</th><th>取值</th></tr>
* <tr><td>计划状态 {@code returnPlanStatus}</td>
* <td>0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 /
* 25 已完成 / 30 已取消 / 35 处理中</td></tr>
* <tr><td>处理状态 {@code handlingStatus}</td>
* <td>5 待处理 / 10 处理中 / 15 已完成 / 20 已取消</td></tr>
* <tr><td>主要处理方式 {@code primaryHandlingMethod}</td>
* <td>101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / 201 销毁 /
* 202 上架良品 / 203 换标上架 / 204 卖家自提 / 205 重新包装 /
* 206 仓库拆箱判断</td></tr>
* </table>
* <p><b>三套互不通用</b>:同样是 {@code 20},在计划状态里是「待处理」、
* 在处理状态里是「已取消」。</p>
*
* <h2>sourceType 两页顺序相反</h2>
* <p>创建页写「1 无来源退货 2 销售退货」,详情页写「1 销售退货 2 无来源退货」。
* <b>两页矛盾</b>,适配器不解释该字段,原值保留在 {@code WarehouseReturn.type()}。</p>
*
* <h2>请求形态两套</h2>
* <p>{@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage} 是
* <b>双层包裹</b>({@code {"params":{...}}});{@code getReturnPlanHandlePage} /
* {@code handlingMethod} 是<b>平铺</b>。发错形态仓方会当成空请求。</p>
*/
public final class HengjianReturnQueryMapper {
private static final DateTimeFormatter DATE_TIME =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
/** 退货计划列表 rows 上限:文档没写,按同站惯例取 100。 */
static final int MAX_ROWS = 100;
/** 处理单列表单页上限:文档没写,取 100;超限拒绝不截断。 */
static final int HANDLE_MAX_ROWS = 100;
private HengjianReturnQueryMapper() {
}
// ================================================================ 详情
/** 详情请求:双层包裹。 */
public static HengjianReturnDetailDtos.DetailRequest toDetailRequest(String orderNo) {
HengjianReturnDetailDtos.DetailParams params = new HengjianReturnDetailDtos.DetailParams();
params.orderNo = orderNo;
HengjianReturnDetailDtos.DetailRequest req = new HengjianReturnDetailDtos.DetailRequest();
req.params = params;
return req;
}
/** 详情 → 统一模型。 */
public static WarehouseReturn toReturn(HengjianReturnDetailDtos.PlanDetail detail) {
String sourceNo = trimToNull(detail.sourceOrderNo);
String planNo = trimToNull(detail.returnPlanNo);
String requestNo = sourceNo != null ? sourceNo : planNo;
if (requestNo == null) {
throw new IllegalArgumentException(
"hengjian return detail has neither sourceOrderNo nor returnPlanNo");
}
WarehouseReturn.Builder builder = WarehouseReturn.builder()
.returnRequestNo(requestNo)
.providerReturnId(planNo)
.warehouseCode(firstNonBlank(detail.orgWarehouseCode, null))
.orderRef(trimToNull(detail.saleOrderNo))
// sourceType 两页文档顺序相反,原值保留不解释
.type(trimToNull(detail.sourceType))
.status(HengjianReturnPlanStatus.toCore(detail.returnPlanStatus))
.rawStatus(trimToNull(detail.returnPlanStatus))
.sourceProvider(WarehouseProvider.HENGJIAN)
.createdAt(parseTime(detail.createdAt))
.actualReceivedAt(parseTime(detail.checkApproveTime))
.relatedProcessNo(null);
// 详情文档没有 lineName 字段:不映射,保持 null(列表才有 lineName)
if (detail.returnPlanSkuList != null) {
for (HengjianReturnDetailDtos.PlanDetail.PlanSku sku : detail.returnPlanSkuList) {
if (sku == null) {
continue;
}
WarehouseReturn.ReturnLine.Builder line = WarehouseReturn.ReturnLine.builder()
.providerSku(trimToNull(sku.erpSku))
.quantity(intOf(sku.returnQuantity))
.processedQuantity(intOf(sku.receivedQuantity))
// 外观破损处理方式:仓方原值,语义由调用方解释
.suggestedDisposition(trimToNull(sku.treatmentMethodForAppearanceDamage))
.newSku(trimToNull(
sku.relabelShelfSkuItems == null || sku.relabelShelfSkuItems.isEmpty()
? null : sku.relabelShelfSkuItems.get(0).changeSku));
if (sku.relabelShelfSkuItems != null) {
for (HengjianReturnDetailDtos.PlanDetail.PlanSku.RelabelItem item
: sku.relabelShelfSkuItems) {
if (item != null) {
line.newSku(trimToNull(item.changeSku));
}
}
}
builder.line(line.build());
}
}
// 待处理 / 已处理列表:作为附件承载不了,统一模型没有对应字段,
// 这里不塞进 lines(那是 SKU 维度),需要时单独用处理单列表接口查
return builder.build();
}
// ================================================================ 列表
/**
* 列表请求:双层包裹,分页参数按文档转字符串。
*
* @param statuses 统一模型的状态过滤;恒健只支持单个状态,多个时拒绝
*/
public static HengjianReturnListDtos.ListRequest toListRequest(
List<ReturnStatus> statuses, ReturnStatus singleStatus,
String startTime, String endTime, Integer queryDataType,
String queryType, String queryValue,
List<String> warehouseCodes, int page, int size) {
HengjianReturnListDtos.ListParams params = new HengjianReturnListDtos.ListParams();
params.page = String.valueOf(page);
params.size = String.valueOf(size);
if (queryDataType != null) {
params.queryDataType = String.valueOf(queryDataType);
}
params.queryStartValue = startTime;
params.queryEndValue = endTime;
if (warehouseCodes != null && !warehouseCodes.isEmpty()) {
// 恒健收逗号拼接的字符串
params.orgWarehouseCode = join(warehouseCodes);
}
if (singleStatus != null) {
params.returnPlanStatus = statusCodeOf(singleStatus);
}
params.queryType = queryType;
params.queryValue = queryValue;
HengjianReturnListDtos.ListRequest req = new HengjianReturnListDtos.ListRequest();
req.params = params;
return req;
}
/** 核心状态 → 恒健计划状态码;认不出返回 null。 */
static String statusCodeOf(ReturnStatus status) {
if (status == null) {
return null;
}
switch (status) {
case DRAFT:
return "0";
case PENDING_REVIEW:
return "5";
case REJECTED:
return "10";
case PENDING_RECEIPT:
return "15";
case COMPLETED:
return "25";
case CLOSED:
return "30";
case RETURNING:
// RETURNING 在恒健对应「待处理(20)」或「处理中(35)」,
// 无法二选一时返回 null —— 让调用方明确选一个,不猜
return null;
default:
return null;
}
}
/** 列表 → 统一 Page。 */
public static Page<WarehouseReturn> toPage(HengjianReturnListDtos.PageData data,
String cursor, int requestedRows) {
if (data == null) {
return Page.last(new ArrayList<WarehouseReturn>());
}
List<WarehouseReturn> out = new ArrayList<WarehouseReturn>();
if (data.content != null) {
for (HengjianReturnListDtos.PlanRow row : data.content) {
if (row != null) {
out.add(toReturn(row));
}
}
}
boolean last = data.last != null ? data.last
: (data.numberOfElements != null && data.numberOfElements < requestedRows);
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));
}
/** 列表行 → 统一模型。 */
public static WarehouseReturn toReturn(HengjianReturnListDtos.PlanRow row) {
String sourceNo = trimToNull(row.sourceOrderNo);
String planNo = trimToNull(row.returnPlanNo);
String requestNo = sourceNo != null ? sourceNo : planNo;
if (requestNo == null) {
throw new IllegalArgumentException(
"hengjian return list row has neither sourceOrderNo nor returnPlanNo");
}
// 列表的仓库字段两套写法都可能出现
String warehouse = firstNonBlank(row.warehouseCode, row.orgWarehouseCode);
return WarehouseReturn.builder()
.returnRequestNo(requestNo)
.providerReturnId(planNo)
.warehouseCode(warehouse == null ? "" : warehouse)
.orderRef(trimToNull(row.saleOrderNo))
.status(HengjianReturnPlanStatus.toCore(row.returnPlanStatus))
.rawStatus(trimToNull(row.returnPlanStatus))
.sourceProvider(WarehouseProvider.HENGJIAN)
.createdAt(parseTime(row.createdAt))
.lineName(trimToNull(row.lineName))
.inspectedQuantity(null)
.build();
}
// ================================================================ 处理单列表
/** 处理单列表请求:<b>平铺</b>,无 params 包裹。 */
public static HengjianReturnHandleDtos.HandleListRequest toHandleListRequest(
List<String> returnPlanNos, List<String> trackingNos,
List<String> warehouseCodes, List<Integer> handlingStatuses,
String createdStart, String createdEnd, int page, int size) {
HengjianReturnHandleDtos.HandleListRequest req =
new HengjianReturnHandleDtos.HandleListRequest();
req.returnPlanNoList = emptyToNull(returnPlanNos);
req.trackingList = emptyToNull(trackingNos);
req.orgWarehouseCodeList = emptyToNull(warehouseCodes);
req.handlingStatusList = emptyToNull(handlingStatuses);
req.createdStartTime = trimToNull(createdStart);
req.createdEndTime = trimToNull(createdEnd);
req.page = page;
req.size = size;
return req;
}
/** 处理单列表 → 统一 Page(每行是一条处理单,不是退货单)。 */
public static Page<HengjianReturnHandleDtos.HandleRow> toHandlePage(
HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) {
if (data == null) {
return Page.last(new ArrayList<HengjianReturnHandleDtos.HandleRow>());
}
List<HengjianReturnHandleDtos.HandleRow> out = new ArrayList<HengjianReturnHandleDtos.HandleRow>();
if (data.content != null) {
for (HengjianReturnHandleDtos.HandleRow row : data.content) {
if (row != null) {
out.add(row);
}
}
}
boolean last = data.last != null ? data.last
: out.size() < requestedRows;
if (last) {
return Page.last(out);
}
int next = (data.number == null ? 0 : data.number) + 2;
return Page.of(out, String.valueOf(next));
}
// ================================================================ 处理方式
/**
* 处理方式请求:<b>平铺</b>,四项定位 + 两级处理方式。
*
* @throws IllegalArgumentException 缺四项定位字段或处理方式
*/
public static HengjianReturnHandleDtos.HandlingMethodRequest toHandlingMethodRequest(
ReturnProcessCommand cmd) {
HengjianReturnHandleDtos.HandlingMethodRequest req =
new HengjianReturnHandleDtos.HandlingMethodRequest();
req.returnPlanNo = requireText(cmd.providerReturnNo(), "returnPlanNo");
req.returnNo = requireText(cmd.returnNo(), "returnNo");
req.erpSku = requireText(cmd.erpSku(), "erpSku");
req.tracking = requireText(cmd.tracking(), "tracking");
req.handlingMethod = requireHandlingMethod(cmd);
req.primaryHandlingMethod = requirePrimaryHandlingMethod(cmd);
req.photosQuantity = cmd.photosQuantity();
req.changeErpsku = trimToNull(cmd.newSku());
req.remark = trimToNull(cmd.remark());
// “继续拍照”必须给拍照数量,否则仓方不知道拍几张
if (req.handlingMethod == HANDLING_CONTINUE_PHOTO
&& (req.photosQuantity == null || req.photosQuantity <= 0)) {
throw new IllegalArgumentException(
"hengjian handlingMethod=1 (continue photo) requires positive photosQuantity");
}
return req;
}
/** 处理方式:1 继续拍照。 */
static final int HANDLING_CONTINUE_PHOTO = 1;
private static Integer requireHandlingMethod(ReturnProcessCommand cmd) {
Integer v = cmd.handlingMethod();
if (v == null) {
throw new IllegalArgumentException(
"hengjian handling method requires handlingMethod (1 continue photo / 2 dispose)");
}
if (v != 1 && v != 2) {
throw new IllegalArgumentException(
"hengjian handlingMethod must be 1 or 2, got " + v);
}
return v;
}
/**
* 主要处理方式。
*
* <p>优先用调用方给的仓方原值;没给时按 core 的 {@link ReturnProcessDisposition}
* 映射四个能对应上的值(销毁 / 上架良品 / 换标上架 / 卖家自提)。
* 拍照类(101~103)与重新包装(205)/ 仓库拆箱判断(206)core 没有对应值,
* 只能由调用方显式给原值。</p>
*/
private static Integer requirePrimaryHandlingMethod(ReturnProcessCommand cmd) {
String explicit = trimToNull(cmd.primaryHandlingMethod());
if (explicit != null) {
try {
return Integer.valueOf(explicit);
} catch (NumberFormatException e) {
throw new IllegalArgumentException(
"hengjian primaryHandlingMethod must be numeric, got " + explicit);
}
}
ReturnProcessDisposition disposition = cmd.disposition();
Integer mapped = primaryCodeOf(disposition);
if (mapped == null) {
throw new IllegalArgumentException(
"hengjian has no primaryHandlingMethod for disposition " + disposition
+ "; pass it explicitly (101-103 / 205 / 206)");
}
return mapped;
}
/** core 处理方式 → 恒健 primaryHandlingMethod;对应不上的返回 null。 */
static Integer primaryCodeOf(ReturnProcessDisposition disposition) {
if (disposition == null) {
return null;
}
switch (disposition) {
case DESTROY:
return 201;
case RESTOCK:
return 202;
case RESTOCK_RELABEL:
return 203;
case CUSTOMER_PICKUP:
return 204;
default:
// RESTOCK_UNSELLABLE / UNKNOWN:恒健没有独立的「不良品上架」码
return null;
}
}
// ================================================================ 分页
/** 页码:游标是字符串化页码,空游标表示第 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 return cursor must be a page number, got " + v);
}
}
/** 退货计划列表每页条数;超上限拒绝不截断。 */
static int rowsOf(int requested) {
if (requested <= 0) {
return MAX_ROWS;
}
if (requested > MAX_ROWS) {
throw new IllegalArgumentException(
"hengjian return rows must not exceed " + MAX_ROWS + ", got " + requested);
}
return requested;
}
/** 处理单列表每页条数;超上限拒绝不截断。 */
static int handleRowsOf(int requested) {
if (requested <= 0) {
return HANDLE_MAX_ROWS;
}
if (requested > HANDLE_MAX_ROWS) {
throw new IllegalArgumentException(
"hengjian return handle rows must not exceed " + HANDLE_MAX_ROWS
+ ", got " + requested);
}
return requested;
}
// ================================================================ 工具
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) {
// 处理单列表的时间戳是 ISO 带时区(2025-08-14T01:32:32.000+0000)
try {
return Instant.parse(v.replace("+0000", "Z"));
} catch (DateTimeParseException ignored) {
try {
return LocalDate.parse(v, DATE).atStartOfDay().toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException alsoIgnored) {
return null;
}
}
}
}
static int intOf(Integer v) {
return v == null ? 0 : v;
}
private static <T> List<T> emptyToNull(List<T> list) {
return list == null || list.isEmpty() ? null : list;
}
private static String join(List<String> values) {
StringBuilder sb = new StringBuilder();
for (String v : values) {
String t = trimToNull(v);
if (t == null) {
continue;
}
if (sb.length() > 0) {
sb.append(',');
}
sb.append(t);
}
return sb.length() == 0 ? null : sb.toString();
}
private static String requireText(String value, String field) {
String v = trimToNull(value);
if (v == null) {
throw new IllegalArgumentException("hengjian handling method requires " + field);
}
return v;
}
private static String firstNonBlank(String a, String b) {
String x = trimToNull(a);
return x != null ? x : trimToNull(b);
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

252
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnDetailDtos.java

@ -0,0 +1,252 @@ @@ -0,0 +1,252 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。
*
* <p><b>请求是双层包裹</b>:{@code {"params":{"orderNo":"..."}}},与创建一致。
* 无 token 时直接 403、不做参数校验。</p>
*
* <p>详情比列表多出三块:{@code returnPlanSkuList}(计划 SKU 明细)、
* {@code returnPlanHandleList}(待处理)、{@code returnPlanExecuteDetails}(已处理)。</p>
*/
public final class HengjianReturnDetailDtos {
private HengjianReturnDetailDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class DetailRequest {
public DetailParams params;
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class DetailParams {
/** 计划单号;必填。 */
public String orderNo;
}
/** 响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class DetailResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public PlanDetail data;
}
/**
* 退货计划详情。
*
* <p>字段多且类型不一致(数量类有的标 string 有的标 integer),一律用 String 接,
* 解析时再转——避免类型漂移炸掉整单。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PlanDetail {
/** 计划单号。 */
@JsonProperty("returnPlanNo")
public String returnPlanNo;
/** 计划状态码:0/5/10/15/20/25/30/35。 */
@JsonProperty("returnPlanStatus")
public String returnPlanStatus;
/** 来源单号(我们下发的退货单)。 */
@JsonProperty("sourceOrderNo")
public String sourceOrderNo;
/** 关联单号。 */
@JsonProperty("associatedNo")
public String associatedNo;
/** 来源类型:1 销售退货 / 2 无来源退货(<b>与创建接口的顺序相反</b>)。 */
@JsonProperty("sourceType")
public String sourceType;
@JsonProperty("saleOrderNo")
public String saleOrderNo;
@JsonProperty("channelAccount")
public String channelAccount;
@JsonProperty("orgWarehouseId")
public String orgWarehouseId;
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
@JsonProperty("lineId")
public String lineId;
@JsonProperty("returnTracking")
public String returnTracking;
@JsonProperty("consignor")
public String consignor;
@JsonProperty("country")
public String country;
@JsonProperty("province")
public String province;
@JsonProperty("city")
public String city;
@JsonProperty("addressOne")
public String addressOne;
@JsonProperty("addressTwo")
public String addressTwo;
@JsonProperty("zipCode")
public String zipCode;
@JsonProperty("phone")
public String phone;
@JsonProperty("threeRdAccount")
public String threeRdAccount;
@JsonProperty("returnReason")
public String returnReason;
@JsonProperty("remark")
public String remark;
@JsonProperty("createdAt")
public String createdAt;
@JsonProperty("updatedAt")
public String updatedAt;
@JsonProperty("returnDate")
public String returnDate;
@JsonProperty("createdName")
public String createdName;
@JsonProperty("updatedName")
public String updatedName;
/** 状态节点时间(详情页展示用)。 */
@JsonProperty("submitTime")
public String submitTime;
@JsonProperty("checkApproveTime")
public String checkApproveTime;
@JsonProperty("inboundCreateTime")
public String inboundCreateTime;
@JsonProperty("completeTime")
public String completeTime;
@JsonProperty("cancelTime")
public String cancelTime;
/** 计划 SKU 明细。 */
@JsonProperty("returnPlanSkuList")
public List<PlanSku> returnPlanSkuList;
/** 待处理列表(与「退货处理单列表」同结构)。 */
@JsonProperty("returnPlanHandleList")
public List<HandleItem> returnPlanHandleList;
/** 已处理列表。 */
@JsonProperty("returnPlanExecuteDetails")
public List<HandleItem> returnPlanExecuteDetails;
/** 计划 SKU 明细行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PlanSku {
@JsonProperty("erpSku")
public String erpSku;
@JsonProperty("sellerSku")
public String sellerSku;
@JsonProperty("returnQuantity")
public Integer returnQuantity;
@JsonProperty("receivedQuantity")
public Integer receivedQuantity;
@JsonProperty("tracking")
public String tracking;
/** 外观破损处理方式:1 客户自提 / 2 拍照 / 3 销毁 / 4 上架 / 5 换标上架 / 6 重新包装。 */
@JsonProperty("treatmentMethodForAppearanceDamage")
public String treatmentMethodForAppearanceDamage;
@JsonProperty("returnShippingMethod")
public String returnShippingMethod;
/** 检验后的分流数量。 */
@JsonProperty("saleableQty")
public Integer saleableQty;
@JsonProperty("unsaleableQty")
public Integer unsaleableQty;
@JsonProperty("shelfQty")
public Integer shelfQty;
@JsonProperty("relabelShelfQty")
public Integer relabelShelfQty;
@JsonProperty("destroyQty")
public Integer destroyQty;
@JsonProperty("customerPickupQty")
public Integer customerPickupQty;
/** 换标上架明细。 */
@JsonProperty("relabelShelfSkuItems")
public List<RelabelItem> relabelShelfSkuItems;
@JsonProperty("createdAt")
public String createdAt;
/** 换标上架明细行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class RelabelItem {
@JsonProperty("changeSku")
public String changeSku;
@JsonProperty("saleableQty")
public String saleableQty;
@JsonProperty("unsaleableQty")
public String unsaleableQty;
}
}
/**
* 一条退货处理(待处理 / 已处理共用)。
*
* <p>{@code handlingStatus} 码表:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。
* {@code primaryHandlingMethod} 码表:101~103 拍照类、201 销毁、202 上架良品、
* 203 换标上架、204 卖家自提、205 重新包装、206 仓库拆箱判断。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class HandleItem {
/** 退货编码 / 处理单号。 */
@JsonProperty("returnNo")
public String returnNo;
@JsonProperty("sourceNo")
public String sourceNo;
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
/** 处理状态:5/10/15/20。 */
@JsonProperty("handlingStatus")
public String handlingStatus;
/** 处理方式:1 继续拍照 / 2 处理方式。 */
@JsonProperty("handlingMethod")
public String handlingMethod;
/** 主要处理方式:101~206。 */
@JsonProperty("primaryHandlingMethod")
public String primaryHandlingMethod;
@JsonProperty("erpSku")
public String erpSku;
@JsonProperty("quantity")
public Integer quantity;
@JsonProperty("handlingQuantity")
public Integer handlingQuantity;
/** 换标 SKU。 */
@JsonProperty("changeErpsku")
public String changeErpsku;
/** 照片链接列表(字段类型标 string,实际可能是数组;用 Object 接住)。 */
@JsonProperty("fileUrlList")
public Object fileUrlList;
@JsonProperty("photosQuantity")
public Integer photosQuantity;
/** 二次拍照列表。 */
@JsonProperty("handleFileUrlList")
public Object handleFileUrlList;
@JsonProperty("remark")
public String remark;
@JsonProperty("createdAt")
public String createdAt;
@JsonProperty("updatedAt")
public String updatedAt;
}
}
}

214
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnHandleDtos.java

@ -0,0 +1,214 @@ @@ -0,0 +1,214 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:退货处理单列表({@code POST /v1/saleReturn/getReturnPlanHandlePage})
* 与「填写退货处理方式」({@code POST /v1/saleReturn/handlingMethod})。
*
* <p><b>注意与另一套接口的差异</b>:这两个接口的请求是<b>平铺</b>的
* (无 {@code params} 包裹),而 {@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage}
* 是双层包裹。两种形态不能混。</p>
*
* <p>无 token 时的表现也不同:这两个接口回
* {@code 500 + code 999999 + "查询失败/处理失败:Unauthorized"},
* 而 thirdParty 那两个直接回 {@code 403}。</p>
*/
public final class HengjianReturnHandleDtos {
private HengjianReturnHandleDtos() {
}
// ================================================================ 处理单列表
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class HandleListRequest {
/** 退货计划单号列表。 */
public List<String> returnPlanNoList;
/** 退货入库单号列表。 */
public List<String> returnInboundNoList;
/** 退货处理单号列表。 */
public List<String> returnPlanHandleNoList;
/** tracking 号列表。 */
public List<String> trackingList;
/** ERP SKU 列表。 */
public List<String> erpSkuList;
/** 仓库 code 列表。 */
public List<String> orgWarehouseCodeList;
/** 处理状态:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 */
public List<Integer> handlingStatusList;
/** 主要处理方式:101~206。 */
public List<Integer> primaryHandlingMethodList;
/** 创建时间区间 {@code yyyy-MM-dd HH:mm:ss}。 */
public String createdStartTime;
public String createdEndTime;
/** 页码,默认 1。 */
public Integer page;
/** 每页大小,默认 20。 */
public Integer size;
}
/** 处理单列表响应。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class HandleListResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public HandlePageData data;
}
/** 分页数据。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class HandlePageData {
@JsonProperty("content")
public List<HandleRow> content;
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("last")
public Boolean last;
@JsonProperty("size")
public Integer size;
/** 当前页码,<b>0 基</b>。 */
@JsonProperty("number")
public Integer number;
}
/** 一条退货处理单。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class HandleRow {
/** 外部来源单号。 */
@JsonProperty("openSourceNo")
public String openSourceNo;
/** 主要处理方式:101~206。 */
@JsonProperty("primaryHandlingMethod")
public String primaryHandlingMethod;
@JsonProperty("inboundRemark")
public String inboundRemark;
@JsonProperty("remark")
public String remark;
/** 退货处理单号。 */
@JsonProperty("returnPlanHandleItemsNo")
public String returnPlanHandleItemsNo;
/** 退货计划单号。 */
@JsonProperty("returnPlanNo")
public String returnPlanNo;
/** 退货入库单号。 */
@JsonProperty("returnInboundNo")
public String returnInboundNo;
@JsonProperty("tracking")
public String tracking;
@JsonProperty("createdAt")
public String createdAt;
@JsonProperty("updatedAt")
public String updatedAt;
@JsonProperty("completeAt")
public String completeAt;
/** 照片 / 处理照片链接(文档标 string,实际可能是数组)。 */
@JsonProperty("fileUrlList")
public Object fileUrlList;
@JsonProperty("handleFileUrlList")
public Object handleFileUrlList;
/** 换标 SKU。 */
@JsonProperty("changeErpsku")
public String changeErpsku;
/** 异常:0 无异常 / 1 推送异常。 */
@JsonProperty("errorStatus")
public String errorStatus;
/** 库存类型:0 可售 / 1 不可售。 */
@JsonProperty("inventoryType")
public String inventoryType;
@JsonProperty("quantity")
public Integer quantity;
@JsonProperty("handlingQuantity")
public Integer handlingQuantity;
@JsonProperty("photosQuantity")
public Integer photosQuantity;
@JsonProperty("sourceNo")
public String sourceNo;
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
@JsonProperty("erpSku")
public String erpSku;
/** 处理状态:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 */
@JsonProperty("handlingStatus")
public String handlingStatus;
}
// ================================================================ 填写处理方式
/**
* 请求:<b>平铺</b>,没有 {@code params} 包裹。
*
* <p>示例里还混了 {@code organizationId} / {@code openSourceNo}——字段表没列,
* 不发(客户组织由认证身份确定,见《库存变动明细查询》那页的说明)。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class HandlingMethodRequest {
/** 计划单号;必填。 */
public String returnPlanNo;
/** 退货编码(处理单号);必填。 */
public String returnNo;
/** ERP SKU;必填。 */
public String erpSku;
/** tracking;必填。 */
public String tracking;
/** 处理方式:1 继续拍照 / 2 处理方式;必填。 */
public Integer handlingMethod;
/** 主要处理方式:101~206;必填。 */
public Integer primaryHandlingMethod;
/** 拍照数量;选填。 */
public Integer photosQuantity;
/** 换标 SKU;选填。 */
public String changeErpsku;
public String remark;
}
/** 响应。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class HandlingMethodResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public HandleRow data;
}
}

152
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnListDtos.java

@ -0,0 +1,152 @@ @@ -0,0 +1,152 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:退货计划列表({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。
*
* <p><b>请求是双层包裹</b>,且分页参数 {@code page} / {@code size} 在文档里标
* <b>string</b>(不是 integer)——照抄,下发时转字符串。</p>
*
* <p>查询是「时间类型 + 时间区间」与「查询类型 + 查询值」两组二选一的组合:
* {@code queryDataType} 1 创建 / 2 修改 / 4 完成;{@code queryType} 1 计划单号 /
* 2 来源单号 / 3 关联订单号 / 4 tracking。</p>
*/
public final class HengjianReturnListDtos {
private HengjianReturnListDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListRequest {
public ListParams params;
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListParams {
/** 页码;文档标 string。 */
public String page;
/** 每页条数;文档标 string。 */
public String size;
/** 查询时间类型:1 创建 / 2 修改 / 4 完成。 */
public String queryDataType;
/** 开始时间 {@code yyyy-MM-dd HH:mm:ss};与结束时间成对。 */
public String queryStartValue;
/** 结束时间。 */
public String queryEndValue;
/** 仓库 code;多个用逗号拼接。 */
public String orgWarehouseCode;
/** 计划状态码(单个,不是数组)。 */
public String returnPlanStatus;
/** 查询类型:1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking。 */
public String queryType;
/** 查询值;需结合 queryType。 */
public String queryValue;
}
/** 响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ListResponse {
@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<PlanRow> 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 PlanRow {
@JsonProperty("id")
public Long id;
@JsonProperty("returnPlanNo")
public String returnPlanNo;
@JsonProperty("sourceOrderNo")
public String sourceOrderNo;
@JsonProperty("associatedNo")
public String associatedNo;
/** 退货追踪号集合(列表是数组,详情是单值 {@code returnTracking})。 */
@JsonProperty("trackingList")
public List<String> trackingList;
@JsonProperty("lineName")
public String lineName;
@JsonProperty("returnPlanStatus")
public String returnPlanStatus;
/** 仓库 code;文档标 null 类型,示例里有值,用 String 接。 */
@JsonProperty("warehouseCode")
public String warehouseCode;
/** 同站的详情字段叫 orgWarehouseCode;列表的字段表写 warehouseCode。 */
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
@JsonProperty("createdAt")
public String createdAt;
@JsonProperty("updatedAt")
public String updatedAt;
@JsonProperty("saleOrderNo")
public String saleOrderNo;
@JsonProperty("saleOrderType")
public String saleOrderType;
/** 退货 / 接收数量;文档标 string。 */
@JsonProperty("returnQuantity")
public String returnQuantity;
@JsonProperty("receivedQuantity")
public String receivedQuantity;
/** 是否接收全部:1 是 / 0 否;文档标 string。 */
@JsonProperty("isReceiveAll")
public String isReceiveAll;
/** 待处理列表(结构同详情)。 */
@JsonProperty("returnPlanHandleList")
public List<HengjianReturnDetailDtos.PlanDetail.HandleItem> returnPlanHandleList;
}
}

368
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java

@ -0,0 +1,368 @@ @@ -0,0 +1,368 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos;
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.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.ZoneOffset;
import java.util.Collections;
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;
/**
* 退货计划详情 / 列表 / 处理单列表 / 处理方式契约测试。
*/
class HengjianReturnQueryTest {
private static final WarehouseContext CTX = WarehouseContext.of(
"HJ-EFCA", WarehouseProviderForTest.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 final class WarehouseProviderForTest {
static final common.ecommerce.warehouse.enums.WarehouseProvider HENGJIAN =
common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN;
}
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\":\"success\",\"data\":{"
+ "\"returnPlanNo\":\"RC25081500018\",\"returnPlanStatus\":20,"
+ "\"sourceOrderNo\":\"RT-1\",\"saleOrderNo\":\"SO-1\","
+ "\"orgWarehouseCode\":\"EFCA\",\"lineId\":\"943\","
+ "\"returnTracking\":\"1Z999\",\"sourceType\":2,"
+ "\"consignor\":\"张三\",\"country\":\"US\",\"province\":\"IL\","
+ "\"city\":\"Quincy\",\"addressOne\":\"620 North\",\"addressTwo\":\"\","
+ "\"zipCode\":\"62305\",\"phone\":\"555\","
+ "\"createdAt\":\"2025-08-15 09:27:10\","
+ "\"checkApproveTime\":\"2025-08-16 10:00:00\","
+ "\"returnPlanSkuList\":[{"
+ "\"erpSku\":\"SKU-A\",\"returnQuantity\":2,\"receivedQuantity\":2,"
+ "\"tracking\":\"1Z999\",\"treatmentMethodForAppearanceDamage\":\"2\","
+ "\"saleableQty\":1,\"unsaleableQty\":1,"
+ "\"relabelShelfSkuItems\":[{\"changeSku\":\"SKU-NEW\","
+ "\"saleableQty\":\"1\",\"unsaleableQty\":\"0\"}]}],"
+ "\"returnPlanHandleList\":[{\"returnNo\":\"TH25081500018\","
+ "\"handlingStatus\":5,\"primaryHandlingMethod\":102,"
+ "\"erpSku\":\"SKU-A\",\"quantity\":2}],"
+ "\"returnPlanExecuteDetails\":[]}}";
private static RecordingTransport detailing() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_RETURN_PLAN_DETAIL, req -> Responses.ok(DETAIL_BODY));
}
@Test
void detailPostsWrappedParams() {
RecordingTransport transport = detailing();
adapter(transport).getReturn(CTX, "RT-1");
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL
+ "/v1/saleReturn/thirdParty/getReturnPlanOrderInfo",
transport.lastDataRequest().url());
String body = transport.lastDataRequest().body();
assertTrue(body.startsWith("{\"params\":{"), "必须是双层包裹,body=" + body);
assertEquals("{\"params\":{\"orderNo\":\"RT-1\"}}", body);
}
@Test
void detailMapsFields() {
WarehouseReturn ret = adapter(detailing()).getReturn(CTX, "RT-1");
assertEquals("RT-1", ret.returnRequestNo(), "来源单号优先作为业务键");
assertEquals("RC25081500018", ret.providerReturnId());
assertEquals("EFCA", ret.warehouseCode());
assertEquals(ReturnStatus.RETURNING, ret.status(), "20 待处理");
assertEquals("20", ret.rawStatus());
assertEquals("SO-1", ret.orderRef());
assertEquals("2", ret.type(), "sourceType 原值保留(两页文档顺序相反,不解释)");
assertEquals(Instant.parse("2025-08-15T09:27:10Z"), ret.createdAt());
assertEquals(Instant.parse("2025-08-16T10:00:00Z"), ret.actualReceivedAt());
}
@Test
void detailMapsSkuLines() {
WarehouseReturn ret = adapter(detailing()).getReturn(CTX, "RT-1");
assertEquals(1, ret.lines().size());
WarehouseReturn.ReturnLine line = ret.lines().get(0);
assertEquals("SKU-A", line.providerSku());
assertEquals(2, line.quantity());
assertEquals(Integer.valueOf(2), line.processedQuantity());
assertEquals("2", line.suggestedDisposition(), "外观破损处理方式原值");
assertEquals("SKU-NEW", line.newSku(), "换标上架明细里的 changeSku");
}
@Test
void detailReturnsNullWhenDataMissing() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_RETURN_PLAN_DETAIL, req -> Responses.ok(
"{\"code\":200,\"message\":\"not found\"}"));
assertNull(adapter(transport).getReturn(CTX, "RT-NONE"));
}
// ================================================================ 列表
private static final String LIST_BODY =
"{\"code\":200,\"message\":\"ok\",\"data\":{"
+ "\"totalElements\":1,\"totalPages\":1,\"numberOfElements\":1,"
+ "\"number\":0,\"size\":100,\"last\":true,\"content\":[{"
+ "\"id\":27859,\"returnPlanNo\":\"RC25032800006\","
+ "\"sourceOrderNo\":\"BI250328000202\",\"returnPlanStatus\":35,"
+ "\"warehouseCode\":\"EFCA\",\"lineName\":\"Default\","
+ "\"saleOrderNo\":\"SO-1\",\"createdAt\":\"2025-03-28 10:31:06\"}]}}";
private static RecordingTransport listing() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_RETURN_PLAN_PAGE, req -> Responses.ok(LIST_BODY));
}
@Test
void listPostsWrappedStringPaging() {
RecordingTransport transport = listing();
adapter(transport).queryReturns(CTX, null);
String body = transport.lastDataRequest().body();
assertTrue(body.startsWith("{\"params\":{"), body);
// 分页参数文档标 string
assertTrue(body.contains("\"page\":\"1\""), body);
assertTrue(body.contains("\"size\":\"100\""), body);
}
/** 状态过滤是单值;给多个时拒绝。 */
@Test
void listRejectsMultipleStatuses() {
RecordingTransport transport = listing();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).queryReturnsAdvanced(CTX,
java.util.Arrays.asList(ReturnStatus.PENDING_RECEIPT, ReturnStatus.COMPLETED),
null, null, null, null, null, null));
assertTrue(ex.getMessage().contains("single status"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
}
@Test
void listSendsSingleStatusAsString() {
RecordingTransport transport = listing();
adapter(transport).queryReturnsAdvanced(CTX,
Collections.singletonList(ReturnStatus.PENDING_RECEIPT),
"2026-10-01 00:00:00", "2026-10-31 23:59:59", 1, "1", "RC1", null);
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"returnPlanStatus\":\"15\""), body);
assertTrue(body.contains("\"queryDataType\":\"1\""), body);
assertTrue(body.contains("\"queryStartValue\":\"2026-10-01 00:00:00\""), body);
assertTrue(body.contains("\"queryType\":\"1\""), body);
assertTrue(body.contains("\"queryValue\":\"RC1\""), body);
}
@Test
void listMapsRows() {
Page<WarehouseReturn> page = adapter(listing()).queryReturns(CTX, null);
assertEquals(1, page.size());
assertFalse(page.hasMore());
WarehouseReturn ret = page.items().get(0);
assertEquals("BI250328000202", ret.returnRequestNo());
assertEquals("RC25032800006", ret.providerReturnId());
assertEquals(ReturnStatus.RETURNING, ret.status(), "35 处理中");
assertEquals("EFCA", ret.warehouseCode());
}
/** RETURNING 无法唯一映射回恒健状态:返回 null 让调用方明确选,不猜。 */
@Test
void returningStatusIsNotMappedBack() {
assertEquals("15", HengjianReturnQueryMapper.statusCodeOf(ReturnStatus.PENDING_RECEIPT));
assertNull(HengjianReturnQueryMapper.statusCodeOf(ReturnStatus.RETURNING));
}
// ================================================================ 处理单列表
private static final String HANDLE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{"
+ "\"totalElements\":15,\"last\":false,\"size\":1,\"number\":0,\"content\":[{"
+ "\"primaryHandlingMethod\":203,"
+ "\"returnPlanHandleItemsNo\":\"RP25081400001\","
+ "\"tracking\":\"KUADIHAO0813\","
+ "\"createdAt\":\"2025-08-14T01:32:32.000+0000\","
+ "\"changeErpsku\":\"C-2077-BU\",\"errorStatus\":0,"
+ "\"returnPlanNo\":\"RC25081300010\",\"orgWarehouseCode\":\"EFCA\","
+ "\"inventoryType\":1,\"quantity\":100,\"handlingQuantity\":100,"
+ "\"sourceNo\":\"BI250813000205\","
+ "\"returnInboundNo\":\"SR2025081300007\",\"erpSku\":\"C-2077-BK\","
+ "\"completeAt\":\"2025-08-14 01:35:06\",\"handlingStatus\":15}]}}";
private static RecordingTransport handling() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_RETURN_HANDLE_PAGE, req -> Responses.ok(HANDLE_BODY));
}
/** 处理单列表请求是平铺的,无 params 包裹。 */
@Test
void handleListPostsFlatBody() {
RecordingTransport transport = handling();
adapter(transport).queryReturnHandles(CTX,
Collections.singletonList("RC1"), null, null,
Collections.singletonList(15), null, null, null);
String body = transport.lastDataRequest().body();
assertFalse(body.contains("\"params\""), "这个接口是平铺的,body=" + body);
assertTrue(body.contains("\"returnPlanNoList\":[\"RC1\"]"), body);
assertTrue(body.contains("\"handlingStatusList\":[15]"), body);
assertTrue(body.contains("\"page\":1"), body);
assertTrue(body.contains("\"size\":20"), body);
}
@Test
void handleListMapsRows() {
Page<HengjianReturnHandleDtos.HandleRow> page =
adapter(handling()).queryReturnHandles(CTX,
Collections.singletonList("RC1"), null, null, null, null, null, null);
assertEquals(1, page.size());
assertTrue(page.hasMore(), "last=false 应给出下一页");
assertEquals("2", page.nextCursor());
HengjianReturnHandleDtos.HandleRow row = page.items().get(0);
assertEquals("RC25081300010", row.returnPlanNo);
assertEquals("RP25081400001", row.returnPlanHandleItemsNo);
assertEquals("15", row.handlingStatus);
assertEquals("203", row.primaryHandlingMethod);
assertEquals("C-2077-BU", row.changeErpsku);
}
// ================================================================ 处理方式
private static RecordingTransport processing() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_RETURN_HANDLING_METHOD, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\","
+ "\"data\":{\"returnPlanHandleItemsNo\":\"RP25090200001\","
+ "\"handlingStatus\":5}}"));
}
@Test
void processPostsFlatBody() {
RecordingTransport transport = processing();
adapter(transport).process(CTX, ReturnProcessCommand.builder()
.providerReturnNo("RC25081500018")
.returnNo("TH25081500018")
.erpSku("SKU-A")
.tracking("1Z999")
.handlingMethod(2)
.primaryHandlingMethod("201")
.disposition(ReturnProcessDisposition.DESTROY)
.remark("确认销毁")
.build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleReturn/handlingMethod",
transport.lastDataRequest().url());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("\"params\""), body);
assertTrue(body.contains("\"returnPlanNo\":\"RC25081500018\""), body);
assertTrue(body.contains("\"returnNo\":\"TH25081500018\""), body);
assertTrue(body.contains("\"erpSku\":\"SKU-A\""), body);
assertTrue(body.contains("\"tracking\":\"1Z999\""), body);
assertTrue(body.contains("\"handlingMethod\":2"), body);
assertTrue(body.contains("\"primaryHandlingMethod\":201"), body);
}
/** 四项定位字段缺一不可(不用行 id)。 */
@Test
void processRequiresFourLocators() {
HengjianAdapter adapter = adapter(processing());
assertThrows(IllegalArgumentException.class,
() -> adapter.process(CTX, ReturnProcessCommand.builder()
.providerReturnNo("RC1").returnNo(null).erpSku("S").tracking("T")
.handlingMethod(2).primaryHandlingMethod("201").build()));
assertThrows(IllegalArgumentException.class,
() -> adapter.process(CTX, ReturnProcessCommand.builder()
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking(null)
.handlingMethod(2).primaryHandlingMethod("201").build()));
}
/** core 处理方式能映射四个;拍照类必须显式给原值。 */
@Test
void primaryMethodMapping() {
assertEquals(Integer.valueOf(201),
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.DESTROY));
assertEquals(Integer.valueOf(202),
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK));
assertEquals(Integer.valueOf(203),
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK_RELABEL));
assertEquals(Integer.valueOf(204),
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.CUSTOMER_PICKUP));
assertNull(HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK_UNSELLABLE));
}
/** 「继续拍照」必须给拍照数量。 */
@Test
void continuePhotoRequiresPhotosQuantity() {
HengjianAdapter adapter = adapter(processing());
assertThrows(IllegalArgumentException.class,
() -> adapter.process(CTX, ReturnProcessCommand.builder()
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking("T")
.handlingMethod(1).primaryHandlingMethod("102")
.disposition(ReturnProcessDisposition.DESTROY)
.build()));
}
/** 不给 handlingMethod 时拒绝。 */
@Test
void processRequiresHandlingMethod() {
HengjianAdapter adapter = adapter(processing());
assertThrows(IllegalArgumentException.class,
() -> adapter.process(CTX, ReturnProcessCommand.builder()
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking("T")
.primaryHandlingMethod("201").build()));
}
// ================================================================ 三套码表
/** 同样是 20:计划状态是「待处理」,处理状态是「已取消」。 */
@Test
void threeCodeTablesAreDistinct() {
assertEquals(ReturnStatus.RETURNING,
common.ecommerce.hengjian.enums.HengjianReturnPlanStatus.toCore("20"));
// 处理状态的 20 是已取消;这里只验证计划状态表,避免误用
assertEquals("20", common.ecommerce.hengjian.enums.HengjianReturnPlanStatus.PENDING_PROCESS.rawCode());
}
// ================================================================ 分页边界
@Test
void rejectsRowsAboveLimit() {
assertThrows(IllegalArgumentException.class,
() -> HengjianReturnQueryMapper.rowsOf(500));
assertThrows(IllegalArgumentException.class,
() -> HengjianReturnQueryMapper.handleRowsOf(500));
}
}

6
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java

@ -62,6 +62,12 @@ public final class YqnReturnMapper { @@ -62,6 +62,12 @@ public final class YqnReturnMapper {
public static YqnReturnProcessDtos.SaleReturnProcessRequest toProcessRequest(ReturnProcessCommand cmd) {
YqnReturnProcessDtos.SaleReturnProcessRequest req = new YqnReturnProcessDtos.SaleReturnProcessRequest();
req.saleReturnPlanNo = cmd.providerReturnNo();
// 运去哪要求行 id;统一模型里是 Long(恒健按四项定位不用 id),
// 所以这里按运去哪的协议校验,缺了直接拒绝而不是发 null
if (cmd.lineId() == null) {
throw new IllegalArgumentException(
"yqn return process requires lineId (from the return query items[].id)");
}
req.id = cmd.lineId();
req.goodsReturnType = YqnReturnProcessDisposition.codeOf(cmd.disposition());
req.newSku = cmd.newSku();

Loading…
Cancel
Save