---
schema: "hl-changelog/v2"
ticket: "5472"
title: "看板列表枚举筛选纯分隔符值校验补全（status 参数）"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5473 已合并 dev-v3 并部署 TEST，网关验证 17/17；#5455 的 100001 错误处理提示已覆盖本单场景，前端无需新改动。"
updated_at: "2026-08-04"
base: "dev-v3"
---

# 车务: 看板列表枚举筛选纯分隔符值校验补全（status 参数）

> **服务**: hl-fleet-service
> **PR**: #5473
> **Issue**: #5472
> **日期**: 2026-08-04
> **影响范围**: 管理后台车务端看板列表的状态筛选参数（#5455 校验契约的补全）

---

## ⚠️ 关键变化

#5455 后，`GET /admin/fleet/board/orders` 仍有一个校验绕过向量：**单值参数 `status`** 传入非空白但纯分隔符组成的值（如 `status=,`、`status=,,`）时，无任何合法状态 token，此前被静默放行返回全量数据；现在与非法状态值同为拒绝口径，返回 `100001 参数非法`。

- 以前：`status=,` → `code=200` + 全量数据（筛选静默失效）。
- 现在：`status=,` → `code=100001`，message 指明非法值与合法枚举。

**数组参数无需变化**（行为如实说明）：`statuses`/`vehicleTypeKeys`/`typeKeys` 为数组参数，Spring 绑定层会先按逗号拆分，纯分隔符值绑定为空数组，与空串等价，按「空=不过滤」返回 200 全量——这是设计口径，与 `statuses=`（空串）行为一致，不属于校验绕过。空值/纯空白（如 `vehicleTypeKeys= `）同样按「空=不过滤」。

## 变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 看板列表 | GET | `/admin/fleet/board/orders` | 校验补全 | 单值参数 `status` 纯分隔符值返 100001 |

## 接口详情

### 1. 看板列表 `GET /admin/fleet/board/orders`

**`status` 参数**（单值，与 statuses 合并）：

| 参数 | 类型 | 合法值 | 说明 |
|------|------|--------|------|
| `status` | String | `unassigned`/`unassigned_urgent`/`holding`/`holding_urgent`/`assigned`/`change_requested`/`canceled`/`completed`（支持中英文别名、大小写、逗号分隔多值） | 状态筛选别名；非空白纯分隔符值返 100001 |

**异常示例**（纯分隔符值）：

```text
GET /admin/fleet/board/orders?page=1&pageSize=20&status=,
Authorization: Bearer <token>
（无请求体）
```

```json
{
  "code": 100001,
  "message": "参数非法: statuses 含非法状态值：,（合法值：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&status=unassigned
Authorization: Bearer <token>
```

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}
```

## 错误码

| code | 含义 | 说明 |
|------|------|------|
| 100001 | 参数非法 | `status` 为非法值/非空白纯分隔符值（与 #5455 同为拒绝口径） |

## 前端需要做什么

- 无需改动：正常请求不产生纯分隔符值；`100001` 的错误提示处理已在 #5455 changelog 中说明（展示 message 即可）。

## 验证证据

- 单元测试：BoardOrderServiceTest 79/79（新增 4 例：status/statuses/vehicleTypeKeys/typeKeys 纯分隔符拒绝且不查库；空值/纯空白/尾逗号合法回归）。
- 全量基线：494f78e7b 上 hl-fleet-service 3064 例（仅 Docker 环境型 1 error，与改动无关）。
- 测试环境网关验证 17/17：`status=,`/`status=,,` → 100001；数组参数纯分隔符 → 200（空=不过滤，设计口径）；空值/纯空白 → 200；合法值（suv、suv,mpv、尾逗号、unassigned,holding）→ 200；BAD_TYPE/BAD_STATUS → 100001。

## 关联 / 联系人

### 联系人

- **后端负责人**: @wx