车务列表接口非法日期参数统一友好错误文案与看板非法枚举显式报错（#5452 #5455）
这个提交包含在：
API Changelog Bot
父节点
6f530766c5
当前提交
f93d9a9906
@ -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
|
||||
@ -0,0 +1,120 @@
|
||||
---
|
||||
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
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户