From 2638269e715fab9e4e6d5181ccd10cbe75023f42 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 4 Aug 2026 13:30:02 +0800
Subject: [PATCH] =?UTF-8?q?=E7=9C=8B=E6=9D=BF=E5=88=97=E8=A1=A8=E6=9E=9A?=
 =?UTF-8?q?=E4=B8=BE=E7=AD=9B=E9=80=89=E7=BA=AF=E5=88=86=E9=9A=94=E7=AC=A6?=
 =?UTF-8?q?=E5=80=BC=E6=A0=A1=E9=AA=8C=E8=A1=A5=E5=85=A8=EF=BC=88#5472?=
 =?UTF-8?q?=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...��举筛选纯分隔符值校验补全-修改接口-管理后台.md | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 changelogs-v2/2026-08/04_5472_看板列表枚举筛选纯分隔符值校验补全-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-08/04_5472_看板列表枚举筛选纯分隔符值校验补全-修改接口-管理后台.md b/changelogs-v2/2026-08/04_5472_看板列表枚举筛选纯分隔符值校验补全-修改接口-管理后台.md
new file mode 100644
index 0000000..f72760b
--- /dev/null
+++ b/changelogs-v2/2026-08/04_5472_看板列表枚举筛选纯分隔符值校验补全-修改接口-管理后台.md
@@ -0,0 +1,114 @@
+---
+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