---
schema: "hl-changelog/v2"
ticket: "5601"
title: "接口参数校验3缺陷：pageNo兼容别名拦截+看板不存在订单报错+保险任务status兼容校验"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5615 合并 dev-v3（e6ecb3555a2ad1d56a4a6d93aebb90bdcd2ec9c5）并部署 TEST；网关实测 pageNo=0/-1 返 400 页码最小为1、看板不存在订单返 605904 订单不存在、保险任务 status=XXX 返 400 枚举错误。前端契约参数名不变（page/pageSize、taskStatus），pageNo/status 为兼容别名（等价生效并校验）。"
updated_at: "2026-08-07"
base: "dev-v3"
generated: "2026-08-06T17:15:00+08:00"
---

# 接口参数校验3缺陷：pageNo兼容别名拦截+看板不存在订单报错+保险任务status兼容校验

> 服务端已部署 TEST 并网关验证；前端契约参数名不变，无强制改动。

## 关联 / 联系人

### 链接

- **Issue**: [#5601](https://git.1814.love:8443/wx/HL/issues/5601)
- **PR**: [#5615](https://git.1814.love:8443/wx/HL/pulls/5615)
- **Merge commit**: [e6ecb3555](https://git.1814.love:8443/wx/HL/commit/e6ecb3555a2ad1d56a4a6d93aebb90bdcd2ec9c5)

### 联系人

- **后端负责人**: @wx

## 变更接口

| 方法 | 路径 | 来源 | 变更 |
|---|---|---|---|
| `GET` | `/admin/fleet/drivers/page` | `DriverController`（fleet） | 查询参数新增兼容别名 `pageNo`（等价 `page`）：`pageNo=0/-1` 返 400「页码最小为1」（修复前被静默忽略返回默认第一页）；`driverStatus`/`season`/`insuranceType` 非法枚举值返 400（修复前静默空结果） |
| `GET` | `/admin/fleet/board/orders` | `BoardController`（fleet） | 查询参数新增兼容别名 `pageNo`（等价 `page`）：非法页码返 400 |
| `GET` | `/admin/fleet/board/orders/<orderId>` | `BoardController`（fleet） | 语义修复：订单不存在（跨库确认查无）返 **605904 订单不存在**（修复前返回 200 空壳 VO）；order-v3 整体不可达时仍降级回显（relatedDetailReady=false） |
| `GET` | `/admin/fleet/insurance/tasks` | `FleetInsuranceTaskController`（fleet） | 查询参数新增兼容别名 `status`（等价 `taskStatus`）：`status=非法值` 返 400「任务状态必须是 PENDING/PROCESSING/SUCCESS/RESOLVED/IGNORED 之一」（修复前被静默忽略返回全部任务） |
| `GET` | `/admin/fleet/vehicles/page` | `VehicleController`（fleet） | `ownerType`/`vehicleStatus` 非法枚举值返 400（同类扫） |
| `GET` | `/admin/fleet/reconciliation/pending-compensations` | `ReconController`（fleet） | `status`/`opType` 非法枚举值返 400（同类扫） |

> 注：`pageNo`、`status` 为兼容别名，**契约主参数名不变**（`page`/`pageSize`、`taskStatus`）；所有继承 `PageParam` 的分页接口（司机/车辆/车队/车型/保险任务/保单/H5 Token/对账补偿等 10 个）自动获得 `pageNo` 兼容与校验。

## 契约影响文件

- `hl-common/hl-common-core/src/main/java/com/hulalv/common/result/PageParam.java`（新增 `getPageNo/setPageNo` 兼容别名，@Min 校验复用）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/board/vo/BoardOrderPageReqVO.java`（同上；page/pageSize 校验 #5516 已有）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/board/service/BoardOrderService.java`（queryOrderDetail 无本地派单且订单确认不存在 → 605904；不可达不误报；原 605908 孤儿语义保留）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/insurance/vo/FleetInsuranceTaskPageReqVO.java`（新增 `status` 兼容字段 + @Pattern 校验）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/insurance/FleetInsuranceTaskService.java`（pageTasks status→taskStatus 归一合并）
- `hl-fleet-service/src/main/java/com/hulalv/fleet/driver/vo/DriverPageReqVO.java`、`vehicle/vo/VehiclePageReqVO.java`、`reconciliation/vo/ReconPendingCompPageReqVO.java`（枚举 @Pattern 校验）

## 根因与修复说明

- **① pageNo<=0 不拦**：契约参数名是 `page`（`PageParam` 已有 `@Min(1)` 拦截 `page=0`），历史调用方传 `pageNo` 时被 Spring 当作未知参数静默忽略，返回默认第一页且不报错 → 新增 `pageNo` 兼容别名（getter+setter 映射到 `page`），非法值随 `@Min` 统一返 400
- **② 看板不存在订单返回空壳**：`queryOrderDetail` 只在本地有派单快照时校验订单存在（孤儿 605908），无派单且订单不存在时走完组装返回 （id=假id、orderNo=null、...） 空壳 → 无本地派单且跨库确认不存在时直接抛 605904；order-v3 不可达（查询结果未知）仍保留降级回显，不误报
- **③ 保险任务非法 status 返回全部**：契约参数名是 `taskStatus`（#5515 已有 @Pattern 校验），调用方传 `status` 时被忽略返回全部任务 → 新增 `status` 兼容字段（等价 `taskStatus`），非法值 400，合法值等价筛选
- **同类扫**：按 #5515「非法枚举值显式 400 而非静默」口径补齐 drivers/vehicles/recon 枚举字段；board/expiry、matrix、保单 status 等已有校验确认到位

## 前端/调用方动作

1. **无强制改动**：前端契约参数名（`page`/`pageSize`、`taskStatus`）不变，现有调用不受影响
2. **兼容增强**：若历史调用方曾传 `pageNo`/`status`，现在与 `page`/`taskStatus` 等价并校验非法值；同一请求同时传 `page` 与 `pageNo`（或 `taskStatus` 与 `status`）时，后者覆盖前者（Spring 绑定顺序），建议只传契约主参数
3. **看板详情错误处理**：不存在订单现返回 605904「订单不存在」（修复前 200 空壳），前端可据此提示

## 验证证据

- 定向测试 285/285 全绿：BoardOrderServiceTest 87（+2：空壳拦截 605904 / 不可达降级不误报）、BoardControllerTest 11（+3：pageNo 非法 400 / 合法绑定 / 605904 透传）、DriverControllerTest 30（+3：pageNo 非法 400 / 合法绑定 / 枚举 400）、FleetInsuranceTaskControllerTest 15（+2：status 非法 400 / 合法透传）、FleetInsuranceTaskServiceTest 142
- fleet verify：255 个测试类全绿（含 spotless）；唯一失败 ReleaseEMixedBinaryHarnessTest 2 项经基线对比（dev-v3 干净 HEAD 同样失败）确认为基线环境 flaky（进程 runner 管道/超时），与本次改动无关
- 网关验证（TEST，经 api.test.1814.love:9443）：
  - `pageNo=0` / `pageNo=-1` → 400「页码最小为1」（drivers/page 与 board/orders 同口径）；`pageNo=2` → 200 正常分页（total=28）
  - `/admin/fleet/board/orders/999999999999999999` → **605904 订单不存在** data=null（修复前 200 空壳）
  - `status=XXX` → 400 任务状态枚举错误；`status=SUCCESS` → 200 正常筛选（total=49，records[0].taskStatus=SUCCESS）