changelog: #5515 保险任务列表枚举校验+source筛选生效（PR #5522）

changelogs-v2/2026-08/05_5515_保险任务列表枚举校验补全与source筛选生效-修改接口-管理后台.md

@@ -0,0 +1,71 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5515"
+title: "车务保险任务列表枚举校验补全 + source 来源筛选生效"
+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 #5522 已合并 dev-v3 并部署 TEST；非法枚举/分页返 400 明确错误码，source 筛选生效（BAOYOU=206）。前端若传 source 参数无需改动；旧传非法枚举值需适配 400 响应。"
+updated_at: "2026-08-05"
+base: "dev-v3"
+---
+
+# 车务: 保险任务列表枚举校验补全 + source 来源筛选生效
+
+> **服务**: hl-fleet-service
+> **PR**: #5522
+> **Issue**: #5515（#5516 分页校验同 PR）
+> **日期**: 2026-08-05
+> **影响范围**: 管理后台车务保险菜单的任务列表筛选参数
+
+---
+
+## ⚠️ 关键变化
+
+`GET /admin/fleet/insurance/tasks` 三个筛选参数行为变更：
+
+1. **`taskType` 非法值不再静默空结果**：`taskType=NOT_A_TYPE` 此前 `code=200` + `total=0`；现在返 `400`，message=`任务类型必须是 PURCHASE(投保)/REFUND(退保) 之一`。
+2. **`taskStatus` 非法值不再静默空结果**：`taskStatus=BAD_STATUS` 此前 `code=200` + `total=0`；现在返 `400`，message=`任务状态必须是 PENDING/PROCESSING/SUCCESS/RESOLVED/IGNORED 之一`。
+3. **`source` 参数新增并生效**：此前 `source=BAOYOU` 被 Spring 静默忽略（返全量 207）；现在按来源过滤（BAOYOU=206 / OFFLINE=1），非法值返 `400`（`来源必须是 BAOYOU(保游)/OFFLINE(线下) 之一`）。
+
+同源收紧（同 PR）：`GET /admin/fleet/matrix/grid` 与 `GET /admin/fleet/matrix/month-counts` 的 `season` 非法值返 `400`（`司机赛季必须是 active/pending/archived/blacklist 之一`）；`GET /admin/fleet/board/expiry` 与 `GET /admin/fleet/board/orders` 分页参数 page/pageSize 非法（非数字/负数/0/超 100）返 `400`（页码最小为1 等），与 drivers/vehicles 列表口径一致。
+
+## 变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保险任务列表 | GET | `/admin/fleet/insurance/tasks` | 校验补全+新增参数 | taskType/taskStatus 非法值 400；新增 source 筛选 |
+| 2 | 矩阵主数据 | GET | `/admin/fleet/matrix/grid` | 校验补全 | season 非法值 400 |
+| 3 | 矩阵月度统计 | GET | `/admin/fleet/matrix/month-counts` | 校验补全 | season 非法值 400 |
+| 4 | 证件到期看板 | GET | `/admin/fleet/board/expiry` | 校验补全 | page/pageSize 非法值 400 |
+| 5 | 看板列表 | GET | `/admin/fleet/board/orders` | 校验补全 | page/pageSize 非法值 400 |
+
+## 接口详情
+
+### 1. 保险任务列表 `GET /admin/fleet/insurance/tasks`
+
+**`source` 参数（新增）**：
+
+- 类型：string；枚举：`BAOYOU`（保游·线上）/ `OFFLINE`（线下）；空/缺省=全部
+- 生效：与 taskType/taskStatus 等 AND 过滤下推 DB（`source = ?` 等值条件）
+
+**校验规则**（taskType/taskStatus/source 均 `@Pattern`）：
+
+- 非法值 → `code=400`，message 包含合法枚举（不再静默空结果）
+- 合法值行为不变（taskType=PURCHASE→28、taskStatus=PENDING→25 等回归不变）
+
+**示例**：
+
+```
+GET /admin/fleet/insurance/tasks?source=BAOYOU&taskType=PURCHASE
+→ 200，仅返回 source=BAOYOU 的投保任务
+GET /admin/fleet/insurance/tasks?taskType=NOT_A_TYPE
+→ 400 任务类型必须是 PURCHASE(投保)/REFUND(退保) 之一
+```