8e2af4e81c
一些检查失败了
changelog-filename-gate / validate (push) Failing after 1s
修改原因：保险任务来源筛选、来源展示及页面入口和布局已完成，需要同步 source 终态。 修改内容：将 #5515 标记为 implemented，并记录 hl-admin@1553c988ac6065e693769a95f3f412c4e43df5e7。 实际验证：两次 pnpm checkpoint 全量通过，业务提交已推送 origin/v2.1。
72 行
3.6 KiB
Markdown
72 行
3.6 KiB
Markdown
---
|
||
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(退保) 之一
|
||
```
|