diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md index eb8f81f..911e228 100644 --- a/docs-warehouse/architecture.md +++ b/docs-warehouse/architecture.md @@ -80,6 +80,11 @@ public enum YqnOutboundStatus { ## 4. 能力矩阵 +**查询排序**:`OutboundQuery.sortField()` / `sortDirection()` 是可选项, +调用方指定优先,未指定由适配器用自己的默认值。`sortField` 是仓方字段名(core 不做白名单), +`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略, +调用方不应假定排序一定生效。 + `WarehouseCapability`(25 个): | 能力 | 说明 | 运去哪 | 信仓 | diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 0e0b89e..563999c 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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 @@ | 账户仓代码 | 自动带上 `orgWarehouseCodes`,避免跨仓混账 | - **一条过滤条件都没有时本地拒绝**:等于拉全量账单。 +- **仓过滤可配**:`FeeQuery.warehouseCodes()` 非空时用它(接口本就是复数仓), + 空才退回账户仓。写死账户仓会让调用方无法表达「查全部仓」或「查其中几个仓」。 +- **`providerSku` / `noType` 不支持**:恒健三个计费接口没有 SKU 维度、也没有 + 单号类型参数,传了就**拒绝**,不静默忽略。 +- **`pageSize` 超上限(200)拒绝**:这个上限文档没写,是保守值。不静默截断—— + 截断会让调用方按自己的 pageSize 误判末页,漏账。 - **分页**:统一方法返回 `List`、不带游标,翻页靠 `query.toBuilder().pageCursor("2").build()`。判末页的约定是 - **返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100,超过 200 截断 - (文档没写上限,取保守值)。 + **返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100;超过 200 会拒绝 + (上限文档没写,是保守值,待真机确认)。 - **状态口径**:三项都是账单明细(带 `billNo`),是已发生账目, 不是预估 → `estimated(false)`。 - **金额**:`cost` 是该行总费用,不是单价。`cost` 缺失的行**跳过**, @@ -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. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/SortDirection.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/SortDirection.java new file mode 100644 index 0000000..839ef1c --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/SortDirection.java @@ -0,0 +1,47 @@ +package common.ecommerce.warehouse.enums; + +/** + * 查询排序方向。 + * + *

只表达业务语义(升序 / 降序),仓方的字面量({@code asc/desc}、{@code 1/0}、 + * {@code ASCENDING} 等)由适配器映射。排序字段本身不进枚举——那是仓方字典, + * core 不认识任何仓的字段名。

+ * + *

与能力位同构:适配器不支持排序时忽略该字段并保持仓方默认,调用方不应假定 + * 排序一定生效;需要强保证时应改用 {@code query} 之外的显式接口。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java index 3be894d..c63f66b 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java @@ -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 { private final String pageCursor; /** 每页条数;0 表示用适配器默认值。 */ private final int pageSize; + /** + * 仓过滤(仓方口径的仓代码);空表示用账户配置的仓。 + * + *

恒健 / 易达云的账单接口本来就收复数仓代码,写死成账户仓会让调用方 + * 无法表达「查这个账户下全部仓」或「只查其中几个仓」。与 + * {@link InventoryQuery#warehouseCodes()} 同口径。

+ */ + private final List warehouseCodes; private FeeQuery(Builder b) { if (b.snapshotStartDate != null && b.snapshotEndDate != null @@ -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(b.warehouseCodes)); } public static Builder builder() { @@ -161,6 +174,11 @@ public final class FeeQuery { return pageSize; } + /** 仓过滤;空表示用账户配置的仓。不可变列表。 */ + public List warehouseCodes() { + return warehouseCodes; + } + /** 翻页时只改游标。 */ public Builder toBuilder() { Builder b = builder() @@ -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 { private common.ecommerce.warehouse.enums.FeeQueryNoType noType; private String pageCursor; private int pageSize; + private final List warehouseCodes = new ArrayList(); /** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */ public Builder saleOrderNo(String v) { @@ -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 v) { + if (v != null) { + for (String code : v) { + warehouseCode(code); + } + } + return this; + } + public FeeQuery build() { return new FeeQuery(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java index c1da05d..fac98d6 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java @@ -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 { private final String orderRef; private final int pageSize; private final String cursor; + /** + * 排序字段(仓方字段名);null 表示用适配器的默认字段。 + * + *

内容是仓方口径:恒健是 {@code id}、其它仓可能是 {@code createTime} 之类。 + * core 不做白名单校验——仓方字段由各自的文档决定,猜不了的就不拦, + * 传错了由仓方报错(比本地静默改成一个值更容易发现)。

+ */ + 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 { 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 { 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 { .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 { 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 { 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); } 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 b406cca..9b8082f 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 @@ -128,7 +128,13 @@ public final class HengjianConstants { /** 计费明细默认每页条数;调用方未指定时使用。 */ public static final int FEE_PAGE_SIZE_DEFAULT = 100; - /** 计费明细单页上限:文档没写,取常见的 200,超过时截断。 */ + /** + * 计费明细单页上限。 + * + *

文档没写这个值。上一版取 200 并静默截断,调用方传 9999 实际只发 + * 200 却毫不知情,按自己的 pageSize 判末页会误判。现在改成:超过即显式报错, + * 由调用方自己决定用多大;真机确认仓方上限后再收紧。

+ */ public static final int FEE_PAGE_SIZE_MAX = 200; /** @@ -139,14 +145,22 @@ public final class HengjianConstants { public static final String FEE_DATE_RANGE_SEPARATOR = " ~ "; /** - * 列表接口的排序字段。 + * 列表接口的默认排序字段。 + * + *

文档:{@code sidx} 必填,可写死 {@code id}。调用方经 + * {@code OutboundQuery.sortField()} 指定时以调用方为准——文档说「可写死」, + * 不是「只能写 id」。

+ */ + public static final String ORDER_LIST_DEFAULT_SIDX = "id"; + + /** + * 列表接口的默认排序方向。 * - *

文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc}; - * 两个都是必填。

+ *

文档把 {@code sort} 列为必填,取值为 {@code asc} / {@code desc}。 + * 这是两个可选值,不是常量:调用方经 + * {@code OutboundQuery.sortDirection()} 选,未指定时才用这个默认。

*/ - 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"; /** * 列表接口的时间跨度上限(天)。 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 0f424eb..d36520b 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 @@ -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 "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 params = new LinkedHashMap(); - 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 private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) { Map params = new LinkedHashMap(); 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 params.put("endDateTime", end.toString()); } - /** 单页行数;恒健上限 100,超出截断而不是让仓方报错。 */ - private static int clampRows(int pageSize) { + /** + * 单页行数。 + * + *

上限 100 是文档明写的(「一页的行数,默认最高 100」)。超过时 + * 显式拒绝而不是静默截断:调用方按自己传的 pageSize 判末页, + * 被悄悄改小会误判「还有下一页」。

+ */ + 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 基入参)。 */ diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java index 237123b..8a2dcf4 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java @@ -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,10 +111,15 @@ public final class HengjianFeeMapper { + "refusing to pull the whole bill"); } - // 仓过滤:没显式给就用账户仓,避免跨仓混账 - String warehouse = trimToNull(defaultWarehouseCode); - if (warehouse != null) { - orgWarehouseCodes.add(warehouse); + // 仓过滤:调用方显式给了就用调用方的(账单接口本就是复数仓), + // 没给才退回账户仓,避免跨仓混账 + 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 { } } - /** 每页条数:0 用默认值,超过上限截断(文档没写上限,按 200 保守处理)。 */ + /** + * 每页条数:0 用默认值;超过上限显式报错。 + * + *

上一版是静默截断到 200——调用方传 9999 实际只发 200 却毫不知情, + * 再按自己的 pageSize 判「本页是否满」就会误判末页,漏账。现在超限直接拒绝。

+ */ 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; } // ================================================================ 仓储费 diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java index fd78c54..8d76d11 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java @@ -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()); } /** 单号与日期区间都要映射到对应字段。 */ diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java index af9a3fb..e5718a9 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java @@ -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()); } /** 翻页:游标是页码,回填下一页。 */