---
schema: "hl-changelog/v2"
ticket: "5455"
title: "看板列表非法枚举参数显式报错（vehicleTypeKeys/statuses 同为拒绝）"
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 #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