hl-api-changelog/changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md

---
schema: "hl-changelog/v2"
ticket: "5452"
title: "车务 4 个列表接口非法日期参数统一友好错误文案"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "Pi"
frontend_ref: "hl-admin@09808c07c18719e30ee7a8e2c8005852ea673e26"
target_release: "v2.1"
verified_at: "2026-08-04"
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 种非法格式均返回统一友好文案；合法日期调用不受影响。

## 关联 / 联系人

### 链接

- **Issue**: [#5452](https://git.1814.love:8443/wx/HL/issues/5452)
- **PR**: [#5465](https://git.1814.love:8443/wx/HL/pulls/5465)
- **Merge commit**: [70483cfb63](https://git.1814.love:8443/wx/HL/commit/70483cfb63)
### 联系人

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