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恒健只支持单个状态过滤({@code returnPlanStatus} 是单值不是数组), + * 给多个状态时拒绝——静默只取一个会让调用方以为筛全了。
+ */ + public Page请求是平铺的(无 {@code params} 包裹),与 thirdParty 那两个不同。
+ * + *恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。
+ */ + public Page请求平铺,用 {@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},在计划状态里是「待处理」、 + * 在处理状态里是「已取消」。
+ * + *创建页写「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优先用调用方给的仓方原值;没给时按 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请求是双层包裹:{@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{@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示例里还混了 {@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