Browse Source

refactor(hengjian): 退货查询收进 ReturnQuery,消除绕开操作日志的适配器入口

HengjianAdapter.queryReturnsAdvanced 是门面上没有对应入口的 public 方法,
宿主强转适配器直接调用时会绕过 CallSupport.observe,操作日志漏记。

做法不是给它补日志,而是把它表达的能力收进统一模型:

- ReturnQuery 增加 rawStatuses / queryDataType / queryTypeValue+queryValue
  * rawStatuses:统一枚举有损。恒健 RETURNING 对应仓方 20(待处理)
    和 35(处理中),归一层表达不了,要给原值时只能传码
  * 与 statuses 互斥,两套码表同时给会互相覆盖,构造期就拒绝
- 恒健 queryReturns 支持全部维度,并显式拒绝它没有的(SKU 过滤、
  多状态、单号与 tracking 同时给、时间窗只给一半)
- 删除 queryReturnsAdvanced;适配器不再有绕开门面的 public 方法

验证:mvn test 全量通过。审计脚本确认门面除 outbound()(返回视图对象)
外零漏点,恒健不再有绕过日志的入口。
feature/Walmart
lml 3 days ago
parent
commit
8d04306169
  1. 14
      docs-warehouse/hengjian/README.md
  2. 91
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java
  3. 107
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  4. 17
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java

14
docs-warehouse/hengjian/README.md

@ -480,6 +480,14 @@ isOriginCountry(是否展示原产地不能为空) @@ -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(是否展示原产地不能为空) @@ -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`
是两组独立的过滤口径。

91
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java

@ -22,6 +22,31 @@ public final class ReturnQuery { @@ -22,6 +22,31 @@ public final class ReturnQuery {
private final String trackingNo;
private final String warehouseCode;
private final List<ReturnStatus> statuses;
/**
* 仓方状态<b>原值</b>过滤;空表示不过滤。
*
* <p>为什么除了 {@link #statuses()} 还要这个:统一枚举有损。
* 恒健的 {@code RETURNING} 对应两个仓方码(20 待处理 / 35 处理中),
* 归一层表达不了;调用方需要精确筛「处理中」时只能给原值。
* <b>与 {@link #statuses()} 互斥</b>——两套码表同时给会互相覆盖。</p>
*/
private final List<String> rawStatuses;
/**
* 时间窗作用于<b>哪个时间字段</b>;null 表示由适配器按默认口径解释。
*
* <p>恒健 {@code queryDataType}:1 创建时间 / 2 修改时间 / 4 完成时间。
* 取值由仓方定义,SDK 不归一——各仓的「修改时间」语义并不一致。</p>
*/
private final Integer queryDataType;
/**
* 自由查询条件:类型 + 值。null 表示不用。
*
* <p>恒健 {@code queryType}(1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking)
* 配 {@code queryValue}。这类「类型 + 值」的组合各仓词表不同,
* 用两段原值承载比堆一堆枚举更稳。</p>
*/
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 { @@ -38,6 +63,17 @@ public final class ReturnQuery {
this.trackingNo = b.trackingNo;
this.warehouseCode = b.warehouseCode;
this.statuses = Collections.unmodifiableList(new java.util.ArrayList<ReturnStatus>(b.statuses));
this.rawStatuses = Collections.unmodifiableList(new java.util.ArrayList<String>(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 { @@ -86,6 +122,26 @@ public final class ReturnQuery {
return statuses;
}
/** 仓方状态原值过滤;空表示不过滤。与 {@link #statuses()} 互斥。 */
public List<String> 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 { @@ -109,6 +165,10 @@ public final class ReturnQuery {
private String trackingNo;
private String warehouseCode;
private final List<ReturnStatus> statuses = new java.util.ArrayList<ReturnStatus>();
private final List<String> rawStatuses = new java.util.ArrayList<String>();
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 { @@ -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<String> 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;

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

@ -161,6 +161,13 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -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 @@ -315,51 +322,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
/**
* 分页查退货计划({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。
*
* <p>统一模型这个入口只有游标,恒健的列表支持更多条件;这里把游标当页码,
* 其余条件为空——需要按状态 / 时间窗筛时用 {@link #queryReturnsAdvanced}。</p>
* <p>支持的维度见 {@link ReturnQuery};<b>不支持的维度直接拒绝</b>,
* 静默忽略会让调用方以为筛过。</p>
*
* <p>恒健的三处限制:</p>
* <ul>
* <li>状态是<b>单值</b>({@code returnPlanStatus} 不是数组),给多个即拒绝;</li>
* <li>没有 SKU 过滤;</li>
* <li>「单号」与「自由查询条件」共用一组 {@code queryType/queryValue},
* 所以不能同时给 {@code orderNo} 和 {@code trackingNo}。</li>
* </ul>
*/
@Override
public Page<WarehouseReturn> 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());
}
/**
* 多条件分页查退货计划。
*
* <p><b>恒健只支持单个状态过滤</b>({@code returnPlanStatus} 是单值不是数组),
* 给多个状态时拒绝——静默只取一个会让调用方以为筛全了。</p>
*/
public Page<WarehouseReturn> queryReturnsAdvanced(WarehouseContext ctx,
List<ReturnStatus> statuses,
String startTime, String endTime,
Integer queryDataType,
String queryType, String queryValue,
String cursor) {
if (statuses != null && statuses.size() > 1) {
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<String> 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);
}
/**

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

@ -162,9 +162,10 @@ class HengjianReturnQueryTest { @@ -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 { @@ -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);

Loading…
Cancel
Save