120 行
4.4 KiB
Markdown
120 行
4.4 KiB
Markdown
---
|
||
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。
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#5472](https://git.1814.love:8443/wx/HL/issues/5472)
|
||
- **PR**: [#5473](https://git.1814.love:8443/wx/HL/pulls/5473)
|
||
- **Merge commit**: [49565f8a41](https://git.1814.love:8443/wx/HL/commit/49565f8a41)
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|