车务列表接口非法日期参数统一友好错误文案与看板非法枚举显式报错（#5452 #5455）

2026-08-04 12:54:32 +08:00
@@ -0,0 +1,173 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5452"
+title: "车务 4 个列表接口非法日期参数统一友好错误文案"
+consumer: "admin"
+change_type: "修改接口"
+author: "wx(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端完成：PR #5465 已合并 dev-v3 并部署 TEST，网关验证 4 接口 × 2 种非法日期格式均返回统一友好文案（无 Spring 内部异常文本）；前端需确认错误提示展示无需再适配旧文案。"
+updated_at: "2026-08-04"
+base: "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 时生效） |
+
+**异常示例**（非法日期格式）：
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026/05/01
+Authorization: Bearer <token>
+（无请求体）
+```
+
+```json
+{"code": 400, "message": "参数【startDayFrom】格式不正确", "data": null, "traceId": null, "success": false}
+```
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026-02-30
+```
+
+```json
+{"code": 400, "message": "参数【startDayFrom】格式不正确（日期请用 yyyy-MM-dd，日期时间请用 yyyy-MM-dd'T'HH:mm:ss）", "data": null, "traceId": null, "success": false}
+```
+
+**典型成功示例**：
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&startDayFrom=2026-05-01
+Authorization: Bearer <token>
+```
+
+```json
+{"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 行命中） |
+
+**异常示例**：
+
+```text
+GET /admin/fleet/drivers/page?page=1&pageSize=20&licenseExpireBefore=2026/07/01
+Authorization: Bearer <token>
+```
+
+```json
+{"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) | 年检到期 ≤ 该日（含当日） |
+
+**异常示例**：
+
+```text
+GET /admin/fleet/vehicles/page?page=1&pageSize=20&insureDueBefore=2026/07/01
+Authorization: Bearer <token>
+```
+
+```json
+{"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) | 服务日止（含） |
+
+**异常示例**：
+
+```text
+GET /admin/fleet/insurance/tasks?page=1&pageSize=20&serviceDateFrom=2026/07/01
+Authorization: Bearer <token>
+```
+
+```json
+{"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