From f93d9a9906dcba11b1c821ad76d44ce90c6659fa Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 4 Aug 2026 12:54:32 +0800 Subject: [PATCH] =?UTF-8?q?=E8=BD=A6=E5=8A=A1=E5=88=97=E8=A1=A8=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E9=9D=9E=E6=B3=95=E6=97=A5=E6=9C=9F=E5=8F=82=E6=95=B0?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E5=8F=8B=E5=A5=BD=E9=94=99=E8=AF=AF=E6=96=87?= =?UTF-8?q?=E6=A1=88=E4=B8=8E=E7=9C=8B=E6=9D=BF=E9=9D=9E=E6=B3=95=E6=9E=9A?= =?UTF-8?q?=E4=B8=BE=E6=98=BE=E5=BC=8F=E6=8A=A5=E9=94=99=EF=BC=88#5452=20#?= =?UTF-8?q?5455=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...法日期参数统一友好错误文案-修改接口-管理后台.md | 173 ++++++++++++++++++ ...表非法枚举参数显式报错-修改接口-管理后台.md | 120 ++++++++++++ 2 files changed, 293 insertions(+) create mode 100644 changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md b/changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md new file mode 100644 index 0000000..f74ef24 --- /dev/null +++ b/changelogs-v2/2026-08/04_5452_车务列表接口非法日期参数统一友好错误文案-修改接口-管理后台.md @@ -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 +（无请求体） +``` + +```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 +``` + +```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 +``` + +```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 +``` + +```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 +``` + +```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 diff --git a/changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md b/changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md new file mode 100644 index 0000000..436df75 --- /dev/null +++ b/changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md @@ -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 +（无请求体） +``` + +```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 +``` + +```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