---
schema: "hl-changelog/v2"
ticket: "5515"
title: "车务保险任务列表枚举校验补全 + source 来源筛选生效"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "pi-main-session"
frontend_ref: "hl-admin@1553c988ac6065e693769a95f3f412c4e43df5e7"
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(退保) 之一
```

## 关联/联系人

### 链接

- [后端工单 #5515](https://git.1814.love:8443/wx/HL/issues/5515)
- [后端 PR #5522](https://git.1814.love:8443/wx/HL/pulls/5522)
- Merge commit: `f061e02d44`

### 联系人

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