Browse Source

fix(warehouse): 排序/分页/仓过滤改为可配,停止静默吞参数与静默截断

审计恒健已接接口时发现的四类问题,一并修正:

1) sort 被写死成 desc。文档里 sidx「可写死 id」、sort 明确是 asc/desc 两值,
   而 OutboundQuery 根本没有排序字段,调用方无处表达。
   → core 新增 SortDirection 与 OutboundQuery.sortField / sortDirection;
     恒健未指定时用文档默认(sidx=id、sort=desc),指定则透传。

2) 静默吞参数:orderRef / providerSku / noType 传了不生效也不报错。
   → 三者均改为显式拒绝(与同方法里 statuses 的处理一致)。

3) 静默截断:rows 超 100、计费 size 超 200 被悄悄改小,
   调用方按自己的 pageSize 判末页会误判「还有下一页」,导致漏账。
   → 改为超限直接报错。rows=100 是文档明写上限;size=200 是我编的保守值,
     已在注释标注待真机确认。

4) 计费仓过滤写死账户仓。恒健接口参数本就是复数 orgWarehouseCodes,
   写死会让调用方无法表达「全部仓」或「其中几个仓」。
   → FeeQuery 新增 warehouseCodes(与 InventoryQuery 同口径),
     非空用调用方的,空才退回账户仓。

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

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 4 days ago
parent
commit
53c296c12f
  1. 5
      docs-warehouse/architecture.md
  2. 24
      docs-warehouse/hengjian/README.md
  3. 47
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/SortDirection.java
  4. 40
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  5. 42
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java
  6. 28
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  7. 51
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  8. 33
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java
  9. 56
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java
  10. 60
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java

5
docs-warehouse/architecture.md

@ -80,6 +80,11 @@ public enum YqnOutboundStatus { @@ -80,6 +80,11 @@ public enum YqnOutboundStatus {
## 4. 能力矩阵
**查询排序**:`OutboundQuery.sortField()` / `sortDirection()` 是<b>可选项</b>,
调用方指定优先,未指定由适配器用自己的默认值。`sortField` 是仓方字段名(core 不做白名单),
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
`WarehouseCapability`(25 个):
| 能力 | 说明 | 运去哪 | 信仓 |

24
docs-warehouse/hengjian/README.md

@ -253,7 +253,13 @@ @@ -253,7 +253,13 @@
- 时间跨度上限 **30 天**,超过也本地拒绝。
- 不支持状态过滤:`OutboundQuery.statuses()` 非空时**拒绝**而不是静默忽略
(静默忽略会让调用方以为过滤生效了)。
- `OutboundQuery.orderRef` 恒健没有对应参数,不参与查询。
- `OutboundQuery.orderRef`(平台单号)恒健**没有**对应参数:传了就**拒绝**,
不静默忽略(静默忽略会让调用方以为过滤生效了)。
- **排序可配**:`sortField` / `sortDirection` 由调用方指定,未指定才用文档默认
(`sidx=id`、`sort=desc`)。文档说 `sidx`「可写死 id」,不是「只能 id」;
`sort` 本来就是 `asc` / `desc` 两个可选值。
- **`rows` 上限 100 是文档明写的**,超过时**拒绝**而不是静默截断——
截断后调用方按自己的 `pageSize` 判末页会误判「还有下一页」。
- **列表是唯一回 `orderId` 的接口**,映射进 `providerOrderId` 与 `providerId`。
- 翻页游标是字符串页码(恒健入参 1 基,响应 `number` 是 0 基);
是否末页以仓方 `last` 为准。
@ -373,10 +379,16 @@ @@ -373,10 +379,16 @@
| 账户仓代码 | 自动带上 `orgWarehouseCodes`,避免跨仓混账 |
- **一条过滤条件都没有时本地拒绝**:等于拉全量账单。
- **仓过滤可配**:`FeeQuery.warehouseCodes()` 非空时用它(接口本就是复数仓),
空才退回账户仓。写死账户仓会让调用方无法表达「查全部仓」或「查其中几个仓」。
- **`providerSku` / `noType` 不支持**:恒健三个计费接口没有 SKU 维度、也没有
单号类型参数,传了就**拒绝**,不静默忽略。
- **`pageSize` 超上限(200)拒绝**:这个上限文档没写,是保守值。不静默截断——
截断会让调用方按自己的 pageSize 误判末页,漏账。
- **分页**:统一方法返回 `List`、不带游标,翻页靠
`query.toBuilder().pageCursor("2").build()`。判末页的约定是
**返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100,超过 200 截断
(文档没写上限,取保守值)。
**返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100;超过 200 会拒绝
(上限文档没写,是保守值,待真机确认)。
- **状态口径**:三项都是账单明细(带 `billNo`),是<b>已发生账目</b>,
不是预估 → `estimated(false)`。
- **金额**:`cost` 是<b>该行总费用</b>,不是单价。`cost` 缺失的行**跳过**,
@ -443,17 +455,17 @@ warehouse-sdk-hengjian/ @@ -443,17 +455,17 @@ warehouse-sdk-hengjian/
├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianOrderQueryTest.java 25 个:详情映射 / 列表分页 / 时间窗 / 包裹去重 / 枚举
├── adapter/HengjianOrderQueryTest.java 29 个:详情映射 / 分页 / 排序可配 / 时间窗 / 包裹去重
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态
├── adapter/HengjianFeeTest.java 18 个:三接口路由 / 分页 / 过滤 / 行映射 / 缺金额跳过
├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过
├── 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` 全部通过(149 个 + 4 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(157 个 + 4 个跳过)。
## 5. 探针用法

47
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/SortDirection.java

@ -0,0 +1,47 @@ @@ -0,0 +1,47 @@
package common.ecommerce.warehouse.enums;
/**
* 查询排序方向。
*
* <p>只表达业务语义(升序 / 降序),仓方的字面量({@code asc/desc}、{@code 1/0}、
* {@code ASCENDING} 等)由适配器映射。<b>排序字段本身不进枚举</b>——那是仓方字典,
* core 不认识任何仓的字段名。</p>
*
* <p>与能力位同构:适配器不支持排序时忽略该字段并保持仓方默认,调用方不应假定
* 排序一定生效;需要强保证时应改用 {@code query} 之外的显式接口。</p>
*/
public enum SortDirection {
/** 升序。 */
ASC(10, "升序"),
/** 降序。 */
DESC(20, "降序");
private final int code;
private final String label;
SortDirection(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查;未知返回 null。 */
public static SortDirection ofCode(int code) {
for (SortDirection d : values()) {
if (d.code == code) {
return d;
}
}
return null;
}
}

40
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java

@ -3,6 +3,9 @@ package common.ecommerce.warehouse.model; @@ -3,6 +3,9 @@ package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseFeeType;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 费用查询条件。
@ -48,6 +51,14 @@ public final class FeeQuery { @@ -48,6 +51,14 @@ public final class FeeQuery {
private final String pageCursor;
/** 每页条数;0 表示用适配器默认值。 */
private final int pageSize;
/**
* 仓过滤(仓方口径的仓代码);空表示用账户配置的仓。
*
* <p>恒健 / 易达云的账单接口本来就收<b>复数</b>仓代码,写死成账户仓会让调用方
* 无法表达「查这个账户下全部仓」或「只查其中几个仓」。与
* {@link InventoryQuery#warehouseCodes()} 同口径。</p>
*/
private final List<String> warehouseCodes;
private FeeQuery(Builder b) {
if (b.snapshotStartDate != null && b.snapshotEndDate != null
@ -80,6 +91,8 @@ public final class FeeQuery { @@ -80,6 +91,8 @@ public final class FeeQuery {
throw new IllegalArgumentException("pageSize must not be negative");
}
this.pageSize = b.pageSize;
this.warehouseCodes = Collections.unmodifiableList(
new ArrayList<String>(b.warehouseCodes));
}
public static Builder builder() {
@ -161,6 +174,11 @@ public final class FeeQuery { @@ -161,6 +174,11 @@ public final class FeeQuery {
return pageSize;
}
/** 仓过滤;空表示用账户配置的仓。不可变列表。 */
public List<String> warehouseCodes() {
return warehouseCodes;
}
/** 翻页时只改游标。 */
public Builder toBuilder() {
Builder b = builder()
@ -172,7 +190,8 @@ public final class FeeQuery { @@ -172,7 +190,8 @@ public final class FeeQuery {
.noType(noType)
.settledAfter(settledAfter)
.settledBefore(settledBefore)
.pageSize(pageSize);
.pageSize(pageSize)
.warehouseCodes(warehouseCodes);
if (hasDateRange()) {
b.snapshotDateRange(snapshotStartDate, snapshotEndDate);
}
@ -200,6 +219,7 @@ public final class FeeQuery { @@ -200,6 +219,7 @@ public final class FeeQuery {
private common.ecommerce.warehouse.enums.FeeQueryNoType noType;
private String pageCursor;
private int pageSize;
private final List<String> warehouseCodes = new ArrayList<String>();
/** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */
public Builder saleOrderNo(String v) {
@ -263,6 +283,24 @@ public final class FeeQuery { @@ -263,6 +283,24 @@ public final class FeeQuery {
return this;
}
/** 仓过滤;不传表示用账户配置的仓。 */
public Builder warehouseCode(String v) {
if (v != null && !v.trim().isEmpty()) {
this.warehouseCodes.add(v.trim());
}
return this;
}
/** 仓过滤(多仓);不传表示用账户配置的仓。 */
public Builder warehouseCodes(List<String> v) {
if (v != null) {
for (String code : v) {
warehouseCode(code);
}
}
return this;
}
public FeeQuery build() {
return new FeeQuery(this);
}

42
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java

@ -1,5 +1,7 @@ @@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.SortDirection;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
@ -17,6 +19,16 @@ public final class OutboundQuery { @@ -17,6 +19,16 @@ public final class OutboundQuery {
private final String orderRef;
private final int pageSize;
private final String cursor;
/**
* 排序字段(仓方字段名);null 表示用适配器的默认字段。
*
* <p><b>内容是仓方口径</b>:恒健是 {@code id}、其它仓可能是 {@code createTime} 之类。
* core 不做白名单校验——仓方字段由各自的文档决定,猜不了的就不拦,
* 传错了由仓方报错(比本地静默改成一个值更容易发现)。</p>
*/
private final String sortField;
/** 排序方向;null 表示用适配器的默认方向。 */
private final SortDirection sortDirection;
private OutboundQuery(Builder b) {
if (b.after != null && b.before != null && !b.after.isBefore(b.before)) {
@ -29,6 +41,8 @@ public final class OutboundQuery { @@ -29,6 +41,8 @@ public final class OutboundQuery {
this.orderRef = b.orderRef;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
this.sortField = b.sortField;
this.sortDirection = b.sortDirection;
}
public static Builder builder() {
@ -80,6 +94,16 @@ public final class OutboundQuery { @@ -80,6 +94,16 @@ public final class OutboundQuery {
return cursor;
}
/** 排序字段(仓方口径);null 表示用适配器默认字段。 */
public String sortField() {
return sortField;
}
/** 排序方向;null 表示用适配器默认方向。 */
public SortDirection sortDirection() {
return sortDirection;
}
/** 翻页时只改游标。 */
public Builder toBuilder() {
return builder()
@ -89,7 +113,9 @@ public final class OutboundQuery { @@ -89,7 +113,9 @@ public final class OutboundQuery {
.outboundRequestNo(outboundRequestNo)
.orderRef(orderRef)
.pageSize(pageSize)
.cursor(cursor);
.cursor(cursor)
.sortField(sortField)
.sortDirection(sortDirection);
}
public static final class Builder {
@ -101,6 +127,8 @@ public final class OutboundQuery { @@ -101,6 +127,8 @@ public final class OutboundQuery {
private String orderRef;
private int pageSize = 100;
private String cursor;
private String sortField;
private SortDirection sortDirection;
public Builder after(Instant after) {
this.after = after;
@ -146,6 +174,18 @@ public final class OutboundQuery { @@ -146,6 +174,18 @@ public final class OutboundQuery {
return this;
}
/** 排序字段(仓方口径);null 表示用适配器默认。 */
public Builder sortField(String sortField) {
this.sortField = sortField;
return this;
}
/** 排序方向;null 表示用适配器默认。 */
public Builder sortDirection(SortDirection sortDirection) {
this.sortDirection = sortDirection;
return this;
}
public OutboundQuery build() {
return new OutboundQuery(this);
}

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

@ -128,7 +128,13 @@ public final class HengjianConstants { @@ -128,7 +128,13 @@ public final class HengjianConstants {
/** 计费明细默认每页条数;调用方未指定时使用。 */
public static final int FEE_PAGE_SIZE_DEFAULT = 100;
/** 计费明细单页上限:文档没写,取常见的 200,超过时截断。 */
/**
* 计费明细单页上限。
*
* <p><b>文档没写</b>这个值。上一版取 200 并<b>静默截断</b>,调用方传 9999 实际只发
* 200 却毫不知情,按自己的 pageSize 判末页会误判。现在改成:超过即<b>显式报错</b>,
* 由调用方自己决定用多大;真机确认仓方上限后再收紧。</p>
*/
public static final int FEE_PAGE_SIZE_MAX = 200;
/**
@ -139,14 +145,22 @@ public final class HengjianConstants { @@ -139,14 +145,22 @@ public final class HengjianConstants {
public static final String FEE_DATE_RANGE_SEPARATOR = " ~ ";
/**
* 列表接口的排序字段。
* 列表接口的<b>默认</b>排序字段。
*
* <p>文档:{@code sidx} 必填,可写死 {@code id}。调用方经
* {@code OutboundQuery.sortField()} 指定时以调用方为准——文档说「可写死」,
* 不是「只能写 id」。</p>
*/
public static final String ORDER_LIST_DEFAULT_SIDX = "id";
/**
* 列表接口的<b>默认</b>排序方向。
*
* <p>文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc};
* 两个都是必填。</p>
* <p>文档把 {@code sort} 列为必填,取值为 {@code asc} / {@code desc}。
* 这是<b>两个可选值</b>,不是常量:调用方经
* {@code OutboundQuery.sortDirection()} 选,未指定时才用这个默认。</p>
*/
public static final String ORDER_LIST_SIDX = "id";
/** 列表接口的排序方向。 */
public static final String ORDER_LIST_SORT = "desc";
public static final String ORDER_LIST_DEFAULT_SORT = "desc";
/**
* 列表接口的时间跨度上限(天)。

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

@ -34,6 +34,7 @@ import common.ecommerce.warehouse.enums.CancelEligibility; @@ -34,6 +34,7 @@ import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.SortDirection;
import common.ecommerce.warehouse.enums.WarehouseFeeType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
@ -465,11 +466,20 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -465,11 +466,20 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
"hengjian order list has no status filter; refusing to silently ignore "
+ query.statuses());
}
// orderRef 是平台单号;恒健列表只有 orderNos(来源单号)与 orderIds,
// 静默忽略会让调用方以为按平台单号过滤生效了
if (trimToNull(query.orderRef()) != null) {
throw validation(ctx, OP_ORDER_QUERY,
"hengjian order list cannot filter by platform order number (orderRef="
+ query.orderRef() + "); use outboundRequestNo instead");
}
Map<String, Object> params = new LinkedHashMap<String, Object>();
int pageSize = clampRows(query.pageSize());
// rows 上限是文档明写的「默认最高 100」,超过即拒绝(不静默截断)
int pageSize = requireRows(ctx, query.pageSize());
params.put("rows", pageSize);
params.put("sidx", HengjianConstants.ORDER_LIST_SIDX);
params.put("sort", HengjianConstants.ORDER_LIST_SORT);
// 排序:调用方指定优先,未指定才用默认值。文档里 sidx 可写死 id、sort 有 asc/desc 两值
params.put("sidx", sortFieldOf(query.sortField()));
params.put("sort", sortDirectionOf(query.sortDirection()));
params.put("page", pageNumberOf(query.cursor()));
String orderNo = trimToNull(query.outboundRequestNo());
@ -620,8 +630,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -620,8 +630,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) {
Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("rows", 1);
params.put("sidx", HengjianConstants.ORDER_LIST_SIDX);
params.put("sort", HengjianConstants.ORDER_LIST_SORT);
params.put("sidx", HengjianConstants.ORDER_LIST_DEFAULT_SIDX);
params.put("sort", HengjianConstants.ORDER_LIST_DEFAULT_SORT);
params.put("page", 1);
if (orderNo != null) {
params.put("orderNos", orderNo);
@ -754,12 +764,37 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -754,12 +764,37 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
params.put("endDateTime", end.toString());
}
/** 单页行数;恒健上限 100,超出截断而不是让仓方报错。 */
private static int clampRows(int pageSize) {
/**
* 单页行数。
*
* <p>上限 100 是<b>文档明写</b>的(「一页的行数,默认最高 100」)。超过时
* <b>显式拒绝</b>而不是静默截断:调用方按自己传的 pageSize 判末页,
* 被悄悄改小会误判「还有下一页」。</p>
*/
private int requireRows(WarehouseContext ctx, int pageSize) {
if (pageSize <= 0) {
return HengjianConstants.ORDER_LIST_MAX_ROWS;
}
return Math.min(pageSize, HengjianConstants.ORDER_LIST_MAX_ROWS);
if (pageSize > HengjianConstants.ORDER_LIST_MAX_ROWS) {
throw validation(ctx, OP_ORDER_QUERY,
"hengjian order list rows must not exceed "
+ HengjianConstants.ORDER_LIST_MAX_ROWS + ", got " + pageSize);
}
return pageSize;
}
/** 排序字段:调用方指定优先,否则用文档的默认 {@code id}。 */
private static String sortFieldOf(String requested) {
String v = trimToNull(requested);
return v == null ? HengjianConstants.ORDER_LIST_DEFAULT_SIDX : v;
}
/** 排序方向:{@code asc} / {@code desc};未指定用默认 {@code desc}。 */
private static String sortDirectionOf(SortDirection direction) {
if (direction == null) {
return HengjianConstants.ORDER_LIST_DEFAULT_SORT;
}
return direction == SortDirection.ASC ? "asc" : "desc";
}
/** 游标是字符串化的页码;空游标表示第 1 页(恒健是 1 基入参)。 */

33
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java

@ -92,6 +92,18 @@ public final class HengjianFeeMapper { @@ -92,6 +92,18 @@ public final class HengjianFeeMapper {
filtered = true;
}
// 恒健三个计费接口都没有 SKU 维度,也没有「单号类型」参数:
// 静默忽略会让调用方以为过滤生效了,对账金额对不上
if (trimToNull(query.providerSku()) != null) {
throw new IllegalArgumentException(
"hengjian billing detail has no SKU filter, got providerSku=" + query.providerSku());
}
if (query.noType() != null) {
throw new IllegalArgumentException(
"hengjian billing detail has no order-number-type parameter, got noType="
+ query.noType());
}
if (!filtered) {
throw new IllegalArgumentException(
"hengjian billing detail query requires at least one filter "
@ -99,11 +111,16 @@ public final class HengjianFeeMapper { @@ -99,11 +111,16 @@ public final class HengjianFeeMapper {
+ "refusing to pull the whole bill");
}
// 仓过滤:没显式给就用账户仓,避免跨仓混账
// 仓过滤:调用方显式给了就用调用方的(账单接口本就是复数仓),
// 没给才退回账户仓,避免跨仓混账
if (!query.warehouseCodes().isEmpty()) {
orgWarehouseCodes.addAll(query.warehouseCodes());
} else {
String warehouse = trimToNull(defaultWarehouseCode);
if (warehouse != null) {
orgWarehouseCodes.add(warehouse);
}
}
return dateRange;
}
@ -133,12 +150,22 @@ public final class HengjianFeeMapper { @@ -133,12 +150,22 @@ public final class HengjianFeeMapper {
}
}
/** 每页条数:0 用默认值,超过上限截断(文档没写上限,按 200 保守处理)。 */
/**
* 每页条数:0 用默认值;超过上限<b>显式报错</b>。
*
* <p>上一版是静默截断到 200——调用方传 9999 实际只发 200 却毫不知情,
* 再按自己的 pageSize 判「本页是否满」就会误判末页,漏账。现在超限直接拒绝。</p>
*/
static int pageSizeOf(int requested) {
if (requested <= 0) {
return HengjianConstants.FEE_PAGE_SIZE_DEFAULT;
}
return Math.min(requested, HengjianConstants.FEE_PAGE_SIZE_MAX);
if (requested > HengjianConstants.FEE_PAGE_SIZE_MAX) {
throw new IllegalArgumentException(
"hengjian billing page size must not exceed "
+ HengjianConstants.FEE_PAGE_SIZE_MAX + " (仓方上限待真机确认), got " + requested);
}
return requested;
}
// ================================================================ 仓储费

56
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java

@ -90,13 +90,61 @@ class HengjianFeeTest { @@ -90,13 +90,61 @@ class HengjianFeeTest {
assertTrue(body.contains("\"size\":50"), body);
}
/** 超过上限显式拒绝,不静默截断(截断会让调用方误判末页)。 */
@Test
void clampsPageSizeToMax() {
void rejectsPageSizeAboveMax() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0"));
adapter(t).settlements(CTX, storageQuery().toBuilder().pageSize(9999).build());
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(t).settlements(CTX, storageQuery().toBuilder().pageSize(9999).build()));
assertTrue(ex.getMessage().contains(String.valueOf(HengjianConstants.FEE_PAGE_SIZE_MAX)),
ex.getMessage());
assertTrue(t.dataRequests().isEmpty(), "本地拒绝不应发请求");
}
/** 调用方指定多仓时用调用方的,不退回账户仓。 */
@Test
void honoursExplicitWarehouseCodes() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0"));
adapter(t).settlements(CTX, storageQuery().toBuilder()
.warehouseCodes(java.util.Arrays.asList("EFCA", "EFNJ")).build());
String body = t.lastDataRequest().body();
assertTrue(body.contains("\"orgWarehouseCodes\":[\"EFCA\",\"EFNJ\"]"), body);
}
/** 不指定仓时用账户仓(现有行为不变)。 */
@Test
void fallsBackToAccountWarehouse() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0"));
adapter(t).settlements(CTX, storageQuery());
assertTrue(t.lastDataRequest().body()
.contains("\"size\":" + HengjianConstants.FEE_PAGE_SIZE_MAX));
assertTrue(t.lastDataRequest().body().contains("\"orgWarehouseCodes\":[\"EFCA\"]"));
}
/** 恒健计费接口没有 SKU 维度:传了就拒绝,不静默忽略。 */
@Test
void rejectsProviderSkuFilter() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(t).settlements(CTX, storageQuery().toBuilder()
.providerSku("SKU-1").build()));
assertTrue(ex.getMessage().contains("providerSku"), ex.getMessage());
assertTrue(t.dataRequests().isEmpty());
}
/** 恒健计费接口没有「单号类型」参数:传了就拒绝。 */
@Test
void rejectsNoTypeFilter() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(t).settlements(CTX, storageQuery().toBuilder()
.noType(common.ecommerce.warehouse.enums.FeeQueryNoType.PLATFORM_ORDER_NO)
.build()));
assertTrue(ex.getMessage().contains("noType"), ex.getMessage());
assertTrue(t.dataRequests().isEmpty());
}
/** 单号与日期区间都要映射到对应字段。 */

60
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java

@ -292,15 +292,65 @@ class HengjianOrderQueryTest { @@ -292,15 +292,65 @@ class HengjianOrderQueryTest {
assertTrue(ex.getMessage().contains("status filter"), ex.getMessage());
}
/** 单页行数超过仓方上限时截断。 */
/** 单页行数超过仓方上限(文档明写 100)时显式拒绝,不静默截断。 */
@Test
void queryClampsPageSize() {
void queryRejectsPageSizeAboveLimit() {
RecordingTransport transport = list();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(500).build()));
assertTrue(ex.getMessage().contains(String.valueOf(HengjianConstants.ORDER_LIST_MAX_ROWS)),
ex.getMessage());
assertTrue(transport.dataRequests().isEmpty(), "本地拒绝不应发请求");
}
/** 排序方向可配:调用方选 asc 就真的发 asc。 */
@Test
void sortDirectionIsConfigurable() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(10)
.sortDirection(common.ecommerce.warehouse.enums.SortDirection.ASC)
.build());
String url = transport.lastDataRequest().url();
assertTrue(url.contains("sort=asc"), url);
assertFalse(url.contains("sort=desc"), url);
}
/** 排序字段可配:文档说 sidx「可写死 id」,不是「只能 id」。 */
@Test
void sortFieldIsConfigurable() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(500).build());
.outboundRequestNo("OB-1").pageSize(10).sortField("createTime").build());
assertTrue(transport.lastDataRequest().url()
.contains("rows=" + HengjianConstants.ORDER_LIST_MAX_ROWS));
assertTrue(transport.lastDataRequest().url().contains("sidx=createTime"));
}
/** 未指定排序时用文档默认值,行为与改造前一致。 */
@Test
void sortDefaultsWhenUnspecified() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(10).build());
String url = transport.lastDataRequest().url();
assertTrue(url.contains("sidx=" + HengjianConstants.ORDER_LIST_DEFAULT_SIDX), url);
assertTrue(url.contains("sort=" + HengjianConstants.ORDER_LIST_DEFAULT_SORT), url);
}
/** orderRef(平台单号)恒健查不了:拒绝而不是静默忽略。 */
@Test
void queryRejectsOrderRef() {
RecordingTransport transport = list();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").orderRef("AMZ-1").build()));
assertTrue(ex.getMessage().contains("orderRef"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
}
/** 翻页:游标是页码,回填下一页。 */

Loading…
Cancel
Save