changelog 示例 JSON 改多行格式（#5452 #5455）

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

@@ -0,0 +1,208 @@
+---
+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

changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md

@@ -0,0 +1,137 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5455"
+title: "看板列表非法枚举参数显式报错（vehicleTypeKeys/statuses 同为拒绝）"
+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 #5466 已合并 dev-v3 并部署 TEST，网关验证非法枚举返 100001、合法枚举筛选回归不变；前端需对 100001 错误码做提示处理。"
+updated_at: "2026-08-04"
+base: "dev-v3"
+---
+
+# 车务: 看板列表非法枚举参数显式报错（vehicleTypeKeys/statuses 同为拒绝）
+
+> **服务**: hl-fleet-service
+> **PR**: #5466
+> **Issue**: #5455
+> **日期**: 2026-08-04
+> **影响范围**: 管理后台车务端看板列表/汇总的车型与状态筛选参数
+
+---
+
+## ⚠️ 关键变化
+
+`GET /admin/fleet/board/orders` 的枚举筛选参数传入非法值时，不再静默失效，统一返回 `100001 参数非法`（与 `variant` 非法值口径一致）。
+
+| 参数 | 以前的行为 | 现在的行为 |
+|------|-----------|-----------|
+| `vehicleTypeKeys` / `typeKeys` | 非法值静默忽略 → 返回全量数据（筛选静默失效，如 `BAD_TYPE` → total=66） | 返回 `100001`，message 指明非法值与合法枚举 |
+| `statuses` / `status` | 非法值静默忽略 → 返回 0 条（如 `BAD_STATUS` → total=0） | 返回 `100001`，message 指明非法值与合法枚举 |
+
+**合法值不变**：
+
+- 车型：`suv`（越野）/ `mpv`（商务车）/ `bus`（大巴）/ `sedan`（轿车），支持多选、逗号分隔，兼容历史大写与中文别名（如 `越野`、`商务`）。
+- 状态：`unassigned`（待派）/ `unassigned_urgent`（待派·临近出团）/ `holding`（排车锁定）/ `holding_urgent`（排车超时）/ `assigned`（已派）/ `change_requested`（请求换车，M1 恒空）/ `canceled`（已取消）/ `completed`（已完成），支持中英文别名、大小写与逗号分隔。
+
+## 变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 看板列表 | GET | `/admin/fleet/board/orders` | 校验新增 | 非法枚举返 100001 |
+
+> 说明：`/admin/fleet/board/summary` 按设计忽略 `statuses`/`status`（不参与汇总过滤），非法状态值不报错，行为不变；`vehicleTypeKeys` 在汇总中参与过滤，非法值同样返 100001。
+
+## 接口详情
+
+### 1. 看板列表 `GET /admin/fleet/board/orders`
+
+**枚举入参**（全部可选）：
+
+| 参数 | 类型 | 合法值 | 说明 |
+|------|------|--------|------|
+| `vehicleTypeKeys` | String[] | `suv`/`mpv`/`bus`/`sedan` | 车型大类多选，任一命中即返；未派按需求车型、已派按实际车辆大类过滤 |
+| `typeKeys` | String[] | 同上 | 车型多选别名（未传 vehicleTypeKeys 时生效） |
+| `statuses` | String[] | `unassigned`/`unassigned_urgent`/`holding`/`holding_urgent`/`assigned`/`change_requested`/`canceled`/`completed` | 多状态筛选，任一命中即返；空=不过滤 |
+| `status` | String | 同上 | 状态筛选别名（单值或逗号分隔；与 statuses 合并） |
+
+**异常示例**（非法车型枚举）：
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&vehicleTypeKeys=BAD_TYPE
+Authorization: Bearer <token>
+（无请求体）
+```
+
+```json
+  {
+    "code": 100001,
+    "message": "参数非法: vehicleTypeKeys 仅支持 suv/mpv/bus/sedan，传入非法值：BAD_TYPE",
+    "data": null,
+    "traceId": null,
+    "success": false
+  }
+```
+
+**异常示例**（非法状态枚举，与车型同为拒绝口径）：
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&statuses=BAD_STATUS
+```
+
+```json
+  {
+    "code": 100001,
+    "message": "参数非法: statuses 含非法状态值：BAD_STATUS（合法值：unassigned/unassigned_urgent/holding/holding_urgent/assigned/change_requested/canceled/completed）",
+    "data": null,
+    "traceId": null,
+    "success": false
+  }
+```
+
+**典型成功示例**（合法多选）：
+
+```text
+GET /admin/fleet/board/orders?page=1&pageSize=20&vehicleTypeKeys=suv,mpv&statuses=unassigned_urgent
+Authorization: Bearer <token>
+```
+
+```json
+{"code": 200, "message": "成功", "data":   {
+    "records": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 20
+  }, "success": true}
+```
+
+## 错误码
+
+| code | 含义 | 说明 |
+|------|------|------|
+| 100001 | 参数非法 | 枚举筛选参数含非法值；message 列出非法值与合法枚举 |
+
+## 前端需要做什么
+
+- 请求参数生成逻辑不变（合法值、多选、逗号分隔均兼容）。
+- 新增处理：收到 `code=100001` 时展示 `message`（如「参数非法: vehicleTypeKeys 仅支持 suv/mpv/bus/sedan，传入非法值：xxx」），不再静默展示全量/空结果。典型场景：下拉数据版本与后端枚举不一致、拼写错误。
+- 建议核对：筛选组件本地若有非法值兜底逻辑（如清空筛选重查全量），可保留但应以 100001 提示为准。
+
+## 验证证据
+
+- 单元测试：非法 `vehicleTypeKeys`/`typeKeys`（含合法值混传非法值）/`statuses`/`status` 均抛 100001 且不查库；合法多选（suv + 中文别名）筛选行为回归不变；汇总接口非法 statuses 按设计忽略不报错。
+- `mvn -pl hl-fleet-service -am verify` 通过（本次改动相关用例全绿）。
+- 测试环境网关验证：`vehicleTypeKeys=BAD_TYPE` → 100001；`statuses=BAD_STATUS` → 100001；合法枚举（`suv`、`suv,mpv`）筛选正常。
+
+## 关联 / 联系人
+
+### 联系人
+
+- **后端负责人**: @wx