From 8d04306169a8e69462fec6537e53094cd24f983e Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 17 Nov 2026 16:26:34 +0800 Subject: [PATCH] =?UTF-8?q?refactor(hengjian):=20=E9=80=80=E8=B4=A7?= =?UTF-8?q?=E6=9F=A5=E8=AF=A2=E6=94=B6=E8=BF=9B=20ReturnQuery=EF=BC=8C?= =?UTF-8?q?=E6=B6=88=E9=99=A4=E7=BB=95=E5=BC=80=E6=93=8D=E4=BD=9C=E6=97=A5?= =?UTF-8?q?=E5=BF=97=E7=9A=84=E9=80=82=E9=85=8D=E5=99=A8=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HengjianAdapter.queryReturnsAdvanced 是门面上没有对应入口的 public 方法, 宿主强转适配器直接调用时会绕过 CallSupport.observe,操作日志漏记。 做法不是给它补日志,而是把它表达的能力收进统一模型: - ReturnQuery 增加 rawStatuses / queryDataType / queryTypeValue+queryValue * rawStatuses:统一枚举有损。恒健 RETURNING 对应仓方 20(待处理) 和 35(处理中),归一层表达不了,要给原值时只能传码 * 与 statuses 互斥,两套码表同时给会互相覆盖,构造期就拒绝 - 恒健 queryReturns 支持全部维度,并显式拒绝它没有的(SKU 过滤、 多状态、单号与 tracking 同时给、时间窗只给一半) - 删除 queryReturnsAdvanced;适配器不再有绕开门面的 public 方法 验证:mvn test 全量通过。审计脚本确认门面除 outbound()(返回视图对象) 外零漏点,恒健不再有绕过日志的入口。 --- docs-warehouse/hengjian/README.md | 14 +++ .../ecommerce/warehouse/model/ReturnQuery.java | 91 ++++++++++++++++++ .../hengjian/adapter/HengjianAdapter.java | 107 ++++++++++++++------- .../hengjian/adapter/HengjianReturnQueryTest.java | 17 ++-- 4 files changed, 190 insertions(+), 39 deletions(-) diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index bf954e7..3f6b80a 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -480,6 +480,14 @@ isOriginCountry(是否展示原产地不能为空) - `BoxLabelCommand` 补 `showIndexNo` / `showOriginCountry` / `paperTypeCode` / `fileNamingType` - `LabelPrintTask.taskNo` 改为**可空**(恒健不回任务号),Javadoc 说明了 null 的含义 +### 退货查询入口说明 + +退货列表 / 处理单列表**全部走门面**(`returns().query(...)` / `returns().queryHandles(...)`), +不再有「适配器私有多条件方法」——那种方法绕过 `CallSupport.observe`,操作日志会漏记。 + +适配器上剩下的 public 方法只有协议扩展点(如 `HengjianProductQueryMapper` 之类的静态工具), +不直接对外暴露。 + ### 商品查询(`/v2/product/queryPage`)—— 已接入 真机确认(2026-11-17):无 token 时 `403 Unauthorized`,**鉴权先于参数校验**,必填项按文档实现。 @@ -605,6 +613,12 @@ isOriginCountry(是否展示原产地不能为空) - `page` / `size` 文档标 **string**,下发转字符串。 - **状态过滤是单值**(`returnPlanStatus` 不是数组);给多个时**拒绝**, 静默只取一个会让调用方以为筛全了。 +- **原值状态**:统一枚举有损——`RETURNING` 对应仓方的 20(待处理)和 35(处理中), + 归一层表达不了。要精确筛「处理中」时给 `ReturnQuery.rawStatus(raw)`, + 与 `status(...)` **互斥**。 +- **单号与 tracking 不能同时给**:恒健只有一组 `queryType/queryValue`。 +- **时间窗**由 `queryDataType` 指定作用于哪个字段(1 创建 / 2 修改 / 4 完成), + 起止必须成对。 - `queryDataType`(1 创建 / 2 修改 / 4 完成)+ 时间区间,与 `queryType`(1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking)+ `queryValue` 是两组独立的过滤口径。 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java index 1c3d3cb..a9aa281 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java @@ -22,6 +22,31 @@ public final class ReturnQuery { private final String trackingNo; private final String warehouseCode; private final List statuses; + /** + * 仓方状态原值过滤;空表示不过滤。 + * + *

为什么除了 {@link #statuses()} 还要这个:统一枚举有损。 + * 恒健的 {@code RETURNING} 对应两个仓方码(20 待处理 / 35 处理中), + * 归一层表达不了;调用方需要精确筛「处理中」时只能给原值。 + * 与 {@link #statuses()} 互斥——两套码表同时给会互相覆盖。

+ */ + private final List rawStatuses; + /** + * 时间窗作用于哪个时间字段;null 表示由适配器按默认口径解释。 + * + *

恒健 {@code queryDataType}:1 创建时间 / 2 修改时间 / 4 完成时间。 + * 取值由仓方定义,SDK 不归一——各仓的「修改时间」语义并不一致。

+ */ + private final Integer queryDataType; + /** + * 自由查询条件:类型 + 值。null 表示不用。 + * + *

恒健 {@code queryType}(1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking) + * 配 {@code queryValue}。这类「类型 + 值」的组合各仓词表不同, + * 用两段原值承载比堆一堆枚举更稳。

+ */ + private final String queryTypeValue; + private final String queryValue; private final String providerSku; private final int pageSize; private final String cursor; @@ -38,6 +63,17 @@ public final class ReturnQuery { this.trackingNo = b.trackingNo; this.warehouseCode = b.warehouseCode; this.statuses = Collections.unmodifiableList(new java.util.ArrayList(b.statuses)); + this.rawStatuses = Collections.unmodifiableList(new java.util.ArrayList(b.rawStatuses)); + if (!this.statuses.isEmpty() && !this.rawStatuses.isEmpty()) { + throw new IllegalArgumentException( + "statuses and rawStatuses are mutually exclusive; give one or the other"); + } + this.queryDataType = b.queryDataType; + if (b.queryTypeValue != null && b.queryValue == null) { + throw new IllegalArgumentException("queryValue is required when queryTypeValue is given"); + } + this.queryTypeValue = b.queryTypeValue; + this.queryValue = b.queryValue; this.providerSku = b.providerSku; this.pageSize = b.pageSize; this.cursor = b.cursor; @@ -86,6 +122,26 @@ public final class ReturnQuery { return statuses; } + /** 仓方状态原值过滤;空表示不过滤。与 {@link #statuses()} 互斥。 */ + public List rawStatuses() { + return rawStatuses; + } + + /** 时间窗作用于哪个时间字段(仓方码);null 由适配器解释。 */ + public Integer queryDataType() { + return queryDataType; + } + + /** 自由查询条件类型(仓方码);null 表示不用。 */ + public String queryTypeValue() { + return queryTypeValue; + } + + /** 自由查询条件的值;与 {@link #queryTypeValue()} 成对。 */ + public String queryValue() { + return queryValue; + } + /** 仓侧 SKU。 */ public String providerSku() { return providerSku; @@ -109,6 +165,10 @@ public final class ReturnQuery { private String trackingNo; private String warehouseCode; private final List statuses = new java.util.ArrayList(); + private final List rawStatuses = new java.util.ArrayList(); + private Integer queryDataType; + private String queryTypeValue; + private String queryValue; private String providerSku; private int pageSize = 100; private String cursor; @@ -151,6 +211,37 @@ public final class ReturnQuery { return this; } + /** 仓方状态原值;与 {@link #status} 互斥。 */ + public Builder rawStatus(String v) { + if (v != null && !v.trim().isEmpty()) { + this.rawStatuses.add(v.trim()); + } + return this; + } + + /** 仓方状态原值列表;与 {@link #status} 互斥。 */ + public Builder rawStatuses(List v) { + if (v != null) { + for (String s : v) { + rawStatus(s); + } + } + return this; + } + + /** 时间窗作用于哪个时间字段(仓方码)。 */ + public Builder queryDataType(Integer v) { + this.queryDataType = v; + return this; + } + + /** 自由查询条件类型 + 值(仓方码)。 */ + public Builder queryTypeValue(String type, String value) { + this.queryTypeValue = type; + this.queryValue = value; + return this; + } + public Builder providerSku(String v) { this.providerSku = v; return this; 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 5fc1a69..bd338f1 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 @@ -161,6 +161,13 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_DESTRUCTION_GET = "warehouse.destruction.get"; private static final String OP_RETURN_GET = "warehouse.return.get"; private static final String OP_RETURN_QUERY = "warehouse.return.query"; + /** 退货列表的时间窗格式(恒健文档:{@code yyyy-MM-dd HH:mm:ss},UTC)。 */ + private static final java.time.format.DateTimeFormatter HENGJIAN_TIME = + java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + /** 恒健 {@code queryType}:来源单号。 */ + private static final String QUERY_TYPE_SOURCE_NO = "2"; + /** 恒健 {@code queryType}:退货 tracking。 */ + private static final String QUERY_TYPE_TRACKING = "4"; private static final String OP_RETURN_HANDLES = "warehouse.return.handles"; private static final String OP_RETURN_PROCESS = "warehouse.return.process"; /** 退货列表默认页大小(文档没写,按同站惯例 100)。 */ @@ -315,51 +322,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti /** * 分页查退货计划({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。 * - *

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

+ *

支持的维度见 {@link ReturnQuery};不支持的维度直接拒绝, + * 静默忽略会让调用方以为筛过。

+ * + *

恒健的三处限制:

+ *
    + *
  • 状态是单值({@code returnPlanStatus} 不是数组),给多个即拒绝;
  • + *
  • 没有 SKU 过滤;
  • + *
  • 「单号」与「自由查询条件」共用一组 {@code queryType/queryValue}, + * 所以不能同时给 {@code orderNo} 和 {@code trackingNo}。
  • + *
*/ @Override public Page queryReturns(WarehouseContext ctx, ReturnQuery query) { - // 统一入口只带游标 / 每页条数与仓库;其余条件为空——需要按状态 / 时间窗筛时 - // 用 queryReturnsAdvanced。ReturnQuery 里给了这里不支持的维度时显式拒绝, - // 静默忽略会让调用方以为筛过。 - if (query != null && (query.hasCreatedRange() || query.orderNo() != null - || query.trackingNo() != null || query.providerSku() != null - || !query.statuses().isEmpty())) { + ReturnQuery q = query == null ? ReturnQuery.builder().build() : query; + + if (q.providerSku() != null) { throw validation(ctx, OP_RETURN_QUERY, - "hengjian return list does not take these filters through the unified entry;" - + " use queryReturnsAdvanced (statuses / time window / order no / sku)"); + "hengjian return list has no sku filter"); + } + if (q.statuses().size() > 1 || q.rawStatuses().size() > 1) { + throw validation(ctx, OP_RETURN_QUERY, + "hengjian return list supports a single status; got statuses=" + q.statuses() + + " rawStatuses=" + q.rawStatuses()); + } + if (q.orderNo() != null && q.trackingNo() != null) { + throw validation(ctx, OP_RETURN_QUERY, + "hengjian return list shares one queryType/queryValue pair;" + + " give orderNo or trackingNo, not both"); } - return queryReturnsAdvanced(ctx, null, null, null, null, null, null, - query == null ? null : query.cursor()); - } - /** - * 多条件分页查退货计划。 - * - *

恒健只支持单个状态过滤({@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) { + ReturnStatus single = q.statuses().isEmpty() ? null : q.statuses().get(0); + // 原值优先:调用方明确给了仓方码就用它,别让统一枚举再折一次 + String rawStatus = q.rawStatuses().isEmpty() ? null : q.rawStatuses().get(0); + if (rawStatus != null && single != null) { throw validation(ctx, OP_RETURN_QUERY, - "hengjian return list supports a single status filter, got " + statuses); + "statuses and rawStatuses are mutually exclusive"); } - ReturnStatus single = statuses == null || statuses.isEmpty() ? null : statuses.get(0); - int page = HengjianReturnQueryMapper.pageOf(cursor); - int size = HengjianReturnQueryMapper.rowsOf(PAGE_SIZE_DEFAULT); + + String startTime = null; + String endTime = null; + if (q.hasCreatedRange()) { + startTime = HENGJIAN_TIME.format(q.createdAfter().atOffset(java.time.ZoneOffset.UTC)); + endTime = HENGJIAN_TIME.format(q.createdBefore().atOffset(java.time.ZoneOffset.UTC)); + } else if (q.createdAfter() != null || q.createdBefore() != null) { + throw validation(ctx, OP_RETURN_QUERY, + "hengjian return time window needs both createdAfter and createdBefore"); + } + + // 单号 / tracking 与自由查询条件共用一组 queryType/queryValue + String queryType = q.queryTypeValue(); + String queryValue = q.queryValue(); + if (q.orderNo() != null) { + queryType = QUERY_TYPE_SOURCE_NO; + queryValue = q.orderNo(); + } else if (q.trackingNo() != null) { + queryType = QUERY_TYPE_TRACKING; + queryValue = q.trackingNo(); + } else if ((queryType == null) != (queryValue == null)) { + throw validation(ctx, OP_RETURN_QUERY, + "hengjian return queryTypeValue and queryValue must be given together"); + } + + int page = HengjianReturnQueryMapper.pageOf(q.cursor()); + int size = q.pageSize() > 0 + ? HengjianReturnQueryMapper.rowsOf(q.pageSize()) + : HengjianReturnQueryMapper.rowsOf(PAGE_SIZE_DEFAULT); + List warehouseCodes = q.warehouseCode() == null + ? null : java.util.Collections.singletonList(q.warehouseCode()); HengjianReturnListDtos.ListRequest body = HengjianReturnQueryMapper.toListRequest( - statuses, single, startTime, endTime, queryDataType, queryType, queryValue, - null, page, size); + q.statuses(), single, startTime, endTime, q.queryDataType(), + queryType, queryValue, warehouseCodes, page, size); + if (rawStatus != null) { + // 原值直接落进报文:statusCodeOf 只认统一枚举,表达不了 20 / 35 的区分 + body.params.returnPlanStatus = rawStatus; + } 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); + return HengjianReturnQueryMapper.toPage(resp == null ? null : resp.data, q.cursor(), size); } /** 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 index 82ffeeb..c273390 100644 --- 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 @@ -162,9 +162,10 @@ class HengjianReturnQueryTest { 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)); + () -> adapter(transport).queryReturns(CTX, ReturnQuery.builder() + .status(ReturnStatus.PENDING_RECEIPT) + .status(ReturnStatus.COMPLETED) + .build())); assertTrue(ex.getMessage().contains("single status"), ex.getMessage()); assertTrue(transport.dataRequests().isEmpty()); @@ -173,9 +174,13 @@ class HengjianReturnQueryTest { @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); + adapter(transport).queryReturns(CTX, ReturnQuery.builder() + .status(ReturnStatus.PENDING_RECEIPT) + .createdAfter(Instant.parse("2026-10-01T00:00:00Z")) + .createdBefore(Instant.parse("2026-10-31T23:59:59Z")) + .queryDataType(1) + .queryTypeValue("1", "RC1") + .build()); String body = transport.lastDataRequest().body(); assertTrue(body.contains("\"returnPlanStatus\":\"15\""), body);