diff --git a/README.md b/README.md index 424ee75..eadb675 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ sequenceDiagram | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | -| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货计划创建) | +| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货计划创建查询处理) | 依赖方向: ``` @@ -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 │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos / │ HengjianInventoryDtos / HengjianInventoryMovementDtos / │ HengjianInboundCreateDtos / HengjianInboundQueryDtos / - │ HengjianTransferDtos / HengjianReturnPlanCreateDtos + │ HengjianTransferDtos / HengjianReturnPlanCreateDtos / + │ HengjianReturnDetailDtos / HengjianReturnListDtos / + │ HengjianReturnHandleDtos ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); │ 其余状态枚举约定见 package-info,待建 ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 4c64f17..1ce6e27 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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(入库产品明细必须填写) **未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。 +### 退货查询与处理方式 —— 已接入 + +#### 请求形态有两套,不能混 + +| 接口 | 形态 | +|---|---| +| `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/ │ │ ├── HengjianInboundMapper.java 入库计划创建 │ │ ├── HengjianInboundQueryMapper.java 入库详情 / 列表 │ │ ├── HengjianTransferMapper.java 调拨创建 / 查询 / 取消 - │ │ └── HengjianReturnMapper.java 退货计划创建 + │ │ ├── HengjianReturnMapper.java 退货计划创建 + │ │ └── HengjianReturnQueryMapper.java 退货详情 / 列表 / 处理单 / 处理方式 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -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. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java index d5b3e87..04da488 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java @@ -12,36 +12,84 @@ public final class ReturnProcessCommand { private final String providerReturnNo; /** - * 仓侧明细行 id。 + * 仓侧明细行 id;可为 null。 * *

只来自「退货查询接口」的 items[].id。运去哪没有这个接口, * 其回调(API 142)也不带 id,因此该仓实际无法构造本命令。

+ * + *

恒健的「填写退货处理方式」不用行 id,而是用 + * {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位,所以这里允许为空; + * 需要行 id 的仓(运去哪)由适配器显式校验,不在构造期一刀切。

*/ - private final long lineId; + private final Long lineId; private final ReturnProcessDisposition disposition; /** 换标上架时的新 SKU;其它处理方式必须为 null。 */ private final String newSku; private final String remark; + // ---- 恒健「填写退货处理方式」协议字段(其它仓不用)---- + + /** + * 退货处理单号 / 退货编码。 + * + *

恒健 {@code returnNo}(来自「退货计划待处理列表」的 {@code returnNo})。 + * 与 {@link #providerReturnNo()}(计划单号)是两个号。

+ */ + private final String returnNo; + /** ERP SKU;恒健 {@code erpSku},定位待处理行的四项之一。 */ + private final String erpSku; + /** 跟踪号;恒健 {@code tracking},定位待处理行的四项之一。 */ + private final String tracking; + /** + * 处理方式:1 继续拍照 / 2 处理方式。 + * + *

恒健 {@code handlingMethod}。与 {@link #disposition()} 不是一回事: + * 这个是「先拍照还是直接处理」的开关,那个是具体怎么处理。

+ */ + private final Integer handlingMethod; + /** + * 主要处理方式(仓方原值):101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / + * 201 销毁 / 202 上架(良品)/ 203 换标上架(良品)/ 204 卖家自提 / + * 205 重新包装 / 206 仓库拆箱判断。 + * + *

保留仓方原值:101~103 是「拍照」类动作,core 的 + * {@link ReturnProcessDisposition} 没有对应值,强行归一会丢信息。

+ */ + 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 { 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 { 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 { 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); } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index 999369d..87a5beb 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -253,6 +253,37 @@ public final class HengjianConstants { "/v1/saleReturn/thirdParty/saveReturnPlan"; /** + * 退货计划详情({@code POST},请求双层包裹 {@code {"params":{"orderNo"}}})。 + * + *

无 token 时直接 403、不做参数校验。

+ */ + public static final String PATH_RETURN_PLAN_DETAIL = + "/v1/saleReturn/thirdParty/getReturnPlanOrderInfo"; + + /** + * 退货计划列表({@code POST},请求双层包裹)。 + * + *

{@code page} / {@code size} 文档标 string;状态是单值不是数组。

+ */ + public static final String PATH_RETURN_PLAN_PAGE = + "/v1/saleReturn/thirdParty/getReturnPlanOrderPage"; + + /** + * 退货处理单列表({@code POST},请求平铺、无 params 包裹)。 + * + *

过滤条件全是数组;无 token 时回 500 + 999999 而非 403。

+ */ + public static final String PATH_RETURN_HANDLE_PAGE = "/v1/saleReturn/getReturnPlanHandlePage"; + + /** + * 填写退货处理方式({@code POST},请求平铺)。 + * + *

用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位处理行, + * 不用行 id——与运去哪的条目处理接口不同。

+ */ + public static final String PATH_RETURN_HANDLING_METHOD = "/v1/saleReturn/handlingMethod"; + + /** * {@code btChargeAt} 的日期区间分隔符。 * *

文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。

diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 773ec33..340f24e 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -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; 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 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 return HengjianReturnMapper.toCreated(cmd, resp.data); } - /** 退货查询未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + /** + * 查退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。 + * + *

请求是双层包裹({@code {"params":{"orderNo"}}})。单号既可是计划单号, + * 也可是来源单号——详情响应同时回 {@code returnPlanNo} 与 {@code sourceOrderNo}。

+ * + *

查不到({@code data} 为空)返回 null。

+ */ @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})。 + * + *

统一模型这个入口只有游标,恒健的列表支持更多条件;这里把游标当页码, + * 其余条件为空——需要按状态 / 时间窗筛时用 {@link #queryReturnsAdvanced}。

+ */ @Override public Page 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); + /** + * 多条件分页查退货计划。 + * + *

恒健只支持单个状态过滤({@code returnPlanStatus} 是单值不是数组), + * 给多个状态时拒绝——静默只取一个会让调用方以为筛全了。

+ */ + public Page queryReturnsAdvanced(WarehouseContext ctx, + List 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})。 + * + *

请求是平铺的(无 {@code params} 包裹),与 thirdParty 那两个不同。

+ * + *

恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。

+ */ + public Page queryReturnHandles( + WarehouseContext ctx, List returnPlanNos, List trackingNos, + List warehouseCodes, List 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})。 + * + *

请求平铺,用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位, + * 不用行 id——与运去哪的条目处理接口不同。

+ * + *

两级处理方式:{@code handlingMethod}(1 继续拍照 / 2 处理方式)是开关, + * {@code primaryHandlingMethod}(101~206)是具体动作。core 的 + * {@code ReturnProcessDisposition} 只有部分能映射(销毁 / 上架良品 / 换标上架 / 卖家自提), + * 拍照类与重新包装必须显式给原值。

+ */ + @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); } // ------------------------------------------------------------------ 调拨 diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java new file mode 100644 index 0000000..6d85e09 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java @@ -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; + +/** + * 恒健退货查询 / 处理方式映射。 + * + *

三套码表,别混

+ * + * + * + * + * + * + * + * + *
码表取值
计划状态 {@code returnPlanStatus}0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 / + * 25 已完成 / 30 已取消 / 35 处理中
处理状态 {@code handlingStatus}5 待处理 / 10 处理中 / 15 已完成 / 20 已取消
主要处理方式 {@code primaryHandlingMethod}101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / 201 销毁 / + * 202 上架良品 / 203 换标上架 / 204 卖家自提 / 205 重新包装 / + * 206 仓库拆箱判断
+ *

三套互不通用:同样是 {@code 20},在计划状态里是「待处理」、 + * 在处理状态里是「已取消」。

+ * + *

sourceType 两页顺序相反

+ *

创建页写「1 无来源退货 2 销售退货」,详情页写「1 销售退货 2 无来源退货」。 + * 两页矛盾,适配器不解释该字段,原值保留在 {@code WarehouseReturn.type()}。

+ * + *

请求形态两套

+ *

{@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage} 是 + * 双层包裹({@code {"params":{...}}});{@code getReturnPlanHandlePage} / + * {@code handlingMethod} 是平铺。发错形态仓方会当成空请求。

+ */ +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 statuses, ReturnStatus singleStatus, + String startTime, String endTime, Integer queryDataType, + String queryType, String queryValue, + List 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 toPage(HengjianReturnListDtos.PageData data, + String cursor, int requestedRows) { + if (data == null) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(); + 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(); + } + + // ================================================================ 处理单列表 + + /** 处理单列表请求:平铺,无 params 包裹。 */ + public static HengjianReturnHandleDtos.HandleListRequest toHandleListRequest( + List returnPlanNos, List trackingNos, + List warehouseCodes, List 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 toHandlePage( + HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) { + if (data == null) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(); + 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)); + } + + // ================================================================ 处理方式 + + /** + * 处理方式请求:平铺,四项定位 + 两级处理方式。 + * + * @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; + } + + /** + * 主要处理方式。 + * + *

优先用调用方给的仓方原值;没给时按 core 的 {@link ReturnProcessDisposition} + * 映射四个能对应上的值(销毁 / 上架良品 / 换标上架 / 卖家自提)。 + * 拍照类(101~103)与重新包装(205)/ 仓库拆箱判断(206)core 没有对应值, + * 只能由调用方显式给原值。

+ */ + 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 List emptyToNull(List list) { + return list == null || list.isEmpty() ? null : list; + } + + private static String join(List 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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnDetailDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnDetailDtos.java new file mode 100644 index 0000000..5c0b05d --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnDetailDtos.java @@ -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})。 + * + *

请求是双层包裹:{@code {"params":{"orderNo":"..."}}},与创建一致。 + * 无 token 时直接 403、不做参数校验。

+ * + *

详情比列表多出三块:{@code returnPlanSkuList}(计划 SKU 明细)、 + * {@code returnPlanHandleList}(待处理)、{@code returnPlanExecuteDetails}(已处理)。

+ */ +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; + } + + /** + * 退货计划详情。 + * + *

字段多且类型不一致(数量类有的标 string 有的标 integer),一律用 String 接, + * 解析时再转——避免类型漂移炸掉整单。

+ */ + @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 无来源退货(与创建接口的顺序相反)。 */ + @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 returnPlanSkuList; + + /** 待处理列表(与「退货处理单列表」同结构)。 */ + @JsonProperty("returnPlanHandleList") + public List returnPlanHandleList; + + /** 已处理列表。 */ + @JsonProperty("returnPlanExecuteDetails") + public List 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 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; + } + } + + /** + * 一条退货处理(待处理 / 已处理共用)。 + * + *

{@code handlingStatus} 码表:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 + * {@code primaryHandlingMethod} 码表:101~103 拍照类、201 销毁、202 上架良品、 + * 203 换标上架、204 卖家自提、205 重新包装、206 仓库拆箱判断。

+ */ + @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; + } + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnHandleDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnHandleDtos.java new file mode 100644 index 0000000..07ff670 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnHandleDtos.java @@ -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})。 + * + *

注意与另一套接口的差异:这两个接口的请求是平铺的 + * (无 {@code params} 包裹),而 {@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage} + * 是双层包裹。两种形态不能混。

+ * + *

无 token 时的表现也不同:这两个接口回 + * {@code 500 + code 999999 + "查询失败/处理失败:Unauthorized"}, + * 而 thirdParty 那两个直接回 {@code 403}。

+ */ +public final class HengjianReturnHandleDtos { + + private HengjianReturnHandleDtos() { + } + + // ================================================================ 处理单列表 + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class HandleListRequest { + + /** 退货计划单号列表。 */ + public List returnPlanNoList; + /** 退货入库单号列表。 */ + public List returnInboundNoList; + /** 退货处理单号列表。 */ + public List returnPlanHandleNoList; + /** tracking 号列表。 */ + public List trackingList; + /** ERP SKU 列表。 */ + public List erpSkuList; + /** 仓库 code 列表。 */ + public List orgWarehouseCodeList; + /** 处理状态:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 */ + public List handlingStatusList; + /** 主要处理方式:101~206。 */ + public List 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 content; + + @JsonProperty("totalElements") + public Integer totalElements; + + @JsonProperty("last") + public Boolean last; + + @JsonProperty("size") + public Integer size; + + /** 当前页码,0 基。 */ + @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; + } + + // ================================================================ 填写处理方式 + + /** + * 请求:平铺,没有 {@code params} 包裹。 + * + *

示例里还混了 {@code organizationId} / {@code openSourceNo}——字段表没列, + * 不发(客户组织由认证身份确定,见《库存变动明细查询》那页的说明)。

+ */ + @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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnListDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnListDtos.java new file mode 100644 index 0000000..f803b80 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianReturnListDtos.java @@ -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})。 + * + *

请求是双层包裹,且分页参数 {@code page} / {@code size} 在文档里标 + * string(不是 integer)——照抄,下发时转字符串。

+ * + *

查询是「时间类型 + 时间区间」与「查询类型 + 查询值」两组二选一的组合: + * {@code queryDataType} 1 创建 / 2 修改 / 4 完成;{@code queryType} 1 计划单号 / + * 2 来源单号 / 3 关联订单号 / 4 tracking。

+ */ +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 content; + + @JsonProperty("totalElements") + public Integer totalElements; + + @JsonProperty("totalPages") + public Integer totalPages; + + @JsonProperty("numberOfElements") + public Integer numberOfElements; + + /** 当前页码,0 基。 */ + @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 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 returnPlanHandleList; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java new file mode 100644 index 0000000..dec5448 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java @@ -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 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 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)); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java index 5cc81c4..85bdfed 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java @@ -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();