wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md
API Changelog Bot e040b18f5d
所有检测均成功
changelog-filename-gate / validate (push) Successful in 2s
详情
changelog 示例 JSON 改多行格式（#5452 #5455）
2026-08-04 12:55:10 +08:00

6.6 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer change_type author backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 5452 车务 4 个列表接口非法日期参数统一友好错误文案 admin 修改接口 wx(GIT) deployed verified pending 后端完成：PR #5465 已合并 dev-v3 并部署 TEST，网关验证 4 接口 × 2 种非法日期格式均返回统一友好文案（无 Spring 内部异常文本）；前端需确认错误提示展示无需再适配旧文案。 2026-08-04 dev-v3

车务: 4 个列表接口非法日期参数统一友好错误文案

服务: hl-fleet-service PR: #5465 Issue: #5452 日期: 2026-08-04 影响范围: 管理后台车务端看板/司机/车辆/保险任务列表的日期筛选参数

⚠️ 关键变化

非法日期格式（如 2026/05/01、2026-02-30）的报错文案由「Spring 内部异常堆栈长串」改为统一友好文案「参数【x】格式不正确」，与 order-v3 订单列表口径一致。

  • 以前：code=400，message 为 Failed to convert property value of type 'java.lang.String' to required type 'java.time.LocalDate' ... ConversionFailedException ... Parse attempt failed（前端不可读，且泄漏内部异常类名与嵌套链）。
  • 现在：code=400，message 为 参数【startDayFrom】格式不正确（日期格式形如 2026-02-30 等已符合 yyyy-MM-dd 但日期不存在时，追加提示「（日期请用 yyyy-MM-dd，日期时间请用 yyyy-MM-dd'T'HH:mm:ss）」）。

HTTP 状态、code、data 结构均不变；合法日期（yyyy-MM-dd）行为不变。

变更接口清单

# 接口 方法 路径 变更类型 说明
1 看板列表 GET /admin/fleet/board/orders 错误文案修改 日期参数非法时统一友好文案
2 司机档案分页 GET /admin/fleet/drivers/page 错误文案修改 同上
3 车辆分页 GET /admin/fleet/vehicles/page 错误文案修改 同上
4 保险任务列表 GET /admin/fleet/insurance/tasks 错误文案修改 同上

接口详情

1. 看板列表 GET /admin/fleet/board/orders

日期类入参（全部可选，格式 yyyy-MM-dd）：

参数 类型 说明
startDayFrom String(date) 行程区间起（含）
startDayTo String(date) 行程区间止（含）
startDate String(date) 日期区间起别名（未传 startDayFrom 时生效）
endDate String(date) 日期区间止别名（未传 startDayTo 时生效）

异常示例（非法日期格式）：

GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026/05/01
Authorization: Bearer <token>
（无请求体）

  {
    "code": 400,
    "message": "参数【startDayFrom】格式不正确",
    "data": null,
    "traceId": null,
    "success": false
  }

GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026-02-30

  {
    "code": 400,
    "message": "参数【startDayFrom】格式不正确（日期请用 yyyy-MM-dd，日期时间请用 yyyy-MM-dd'T'HH:mm:ss）",
    "data": null,
    "traceId": null,
    "success": false
  }

典型成功示例：

GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026-05-01
Authorization: Bearer <token>

{"code": 200, "message": "成功", "data":   {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  }, "success": true}

2. 司机档案分页 GET /admin/fleet/drivers/page

日期类入参（全部可选，格式 yyyy-MM-dd）：

参数 类型 说明
licenseExpireBefore String(date) 驾照到期 ≤ 该日
insuranceAnnualEndBefore String(date) 年保到期 ≤ 该日（仅 annual 行命中）

异常示例：

GET /admin/fleet/drivers/page?page=1&pageSize=20&licenseExpireBefore=2026/07/01
Authorization: Bearer <token>

  {
    "code": 400,
    "message": "参数【licenseExpireBefore】格式不正确",
    "data": null,
    "traceId": null,
    "success": false
  }

3. 车辆分页 GET /admin/fleet/vehicles/page

日期类入参（全部可选，格式 yyyy-MM-dd）：

参数 类型 说明
insureDueBefore String(date) 保险到期 ≤ 该日（含当日）
inspectDueBefore String(date) 年检到期 ≤ 该日（含当日）

异常示例：

GET /admin/fleet/vehicles/page?page=1&pageSize=20&insureDueBefore=2026/07/01
Authorization: Bearer <token>

  {
    "code": 400,
    "message": "参数【insureDueBefore】格式不正确",
    "data": null,
    "traceId": null,
    "success": false
  }

4. 保险任务列表 GET /admin/fleet/insurance/tasks

日期类入参（全部可选，格式 yyyy-MM-dd）：

参数 类型 说明
serviceDateFrom String(date) 服务日起（含）
serviceDateTo String(date) 服务日止（含）

异常示例：

GET /admin/fleet/insurance/tasks?page=1&pageSize=20&serviceDateFrom=2026/07/01
Authorization: Bearer <token>

  {
    "code": 400,
    "message": "参数【serviceDateFrom】格式不正确",
    "data": null,
    "traceId": null,
    "success": false
  }

错误码

code 含义 说明
400 参数格式错误 日期参数非法格式；message 统一为「参数【字段名】格式不正确」

前端需要做什么

  • 无需修改请求/响应字段结构；日期筛选组件仍按 yyyy-MM-dd 提交。
  • 建议核对：错误提示直接展示 message 即可，不需要再解析/兜底 Spring 异常长串；如前端此前针对旧文案写过 workaround（如截取、正则清洗），可清理。

验证证据

  • 集成测试：4 接口 × 2 种非法格式（斜杠分隔、不存在的日期）断言 code=400 + 统一文案 + 不含 ConversionFailedException/IllegalArgumentException/Failed to convert。
  • mvn -pl hl-fleet-service -am verify 通过（本次改动相关 3072 用例全绿；仅 2 个环境性失败与本次无关：Docker 缺失的保险集成测试 + 偶发时序的 releasee 进程测试，复跑通过）。
  • 测试环境网关验证：4 接口 × 2 种非法格式均返回统一友好文案；合法日期调用不受影响。

关联 / 联系人

联系人

  • 后端负责人: @wx