wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-08/06_5601_接口参数校验3缺陷：pageNo兼容别名拦截+看板不存在订单报错+保险任务status兼容校验-修改接口-管理后台.md
Mimingguang f32db894e4
所有检测均成功
changelog-filename-gate / validate (push) Successful in 2s
详情
chore(changelog): #5601 确认前端无需改动(pageNo/status 为后端兼容别名)
2026-08-07 10:50:11 +08:00

6.8 KiB
原始文件 永久链接 Blame 文件历史

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

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

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

关联 / 联系人

链接

联系人

  • 后端负责人: @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）