143 行
5.8 KiB
Markdown
143 行
5.8 KiB
Markdown
---
|
||
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`）筛选正常。
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#5455](https://git.1814.love:8443/wx/HL/issues/5455)
|
||
- **PR**: [#5466](https://git.1814.love:8443/wx/HL/pulls/5466)
|
||
- **Merge commit**: [fa954d22c7](https://git.1814.love:8443/wx/HL/commit/fa954d22c7)
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|