diff --git a/changelogs-v2/2026-08/05_5515_保险任务列表枚举校验补全与source筛选生效-修改接口-管理后台.md b/changelogs-v2/2026-08/05_5515_保险任务列表枚举校验补全与source筛选生效-修改接口-管理后台.md new file mode 100644 index 0000000..d1ab0c0 --- /dev/null +++ b/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(退保) 之一 +```