docs(changelog): #5928 保单分页POST契约 + #5923 已取消tab只收订单真取消

2026-08-15 21:33:15 +08:00
@@ -0,0 +1,49 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5928"
+title: "车务司机险保单分页新主链改 POST JSON body + 新路径 GET 显式 405"
+consumer: "admin"
+author: "wx"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端完成：PR #5977 已合并 dev-v3（a006b2b46）并部署 TEST（hl-fleet-service 双实例 UP）。网关实测：POST 新主链 code=200 返回分页；GET 新路径 405；旧 GET /policies 兼容 code=200；新旧 coverage 字段混传 code=100001。"
+updated_at: "2026-08-15"
+base: "dev-v3"
+generated: "2026-08-15T21:30:00+08:00"
+---
+
+# 车务司机险保单分页新主链改 POST JSON body + 新路径 GET 显式 405（#5928）
+
+## 背景
+
+司机险保单分页主链含预筛集合（最多 1000 个雪花 ID），GET query 会撑爆 URL，故主链强制 POST JSON body。本次对齐契约：新主链路径改 POST，GET 显式拒绝；旧路径保留 deprecated 兼容。
+
+## 变更接口
+
+| 接口 | 变更 |
+| --- | --- |
+| `POST /admin/fleet/insurance/driver-policies/page` | 新主链，`@RequestBody` JSON；只收新字段 `coverageStartDate`/`coverageEndDate`；预筛 ID 集合走 body |
+| `GET /admin/fleet/insurance/driver-policies/page` | 显式 **405 Method Not Allowed**（防 `/driver-policies/{insuranceOrderId}` 模板把 `page` 当保单 ID 吞掉）；Swagger 隐藏 |
+| `GET /admin/fleet/insurance/policies` | 保留 deprecated 兼容别名，仅收旧标量参数 `coverageStartDateFrom`/`coverageStartDateTo` |
+
+## 行为变化
+
+- **新旧 coverage 字段不可混传**：新路径传 `coverageStartDateFrom`/`coverageStartDateTo` 或与 `coverageStartDate`/`coverageEndDate` 混传，返回 **100001**（参数非法），message 明确提示「仅旧路径 /policies 使用」。
+- 新路径不再支持 GET；前端保单 Tab 请改用 POST + JSON body。
+
+## 前端动作
+
+- 保单分页改调 `POST /admin/fleet/insurance/driver-policies/page`，参数放 JSON body。
+- 使用新字段名 `coverageStartDate`/`coverageEndDate`；不要再对新路径传 `coverageStartDateFrom/To`。
+- 旧 `GET /policies` 仅为兼容保留，新代码请迁移到新主链。
+
+## 验证证据
+
+- FleetInsuranceTaskControllerTest 17 + FleetRedLineArchTest 13 = 30 全绿，spotless 通过。
+- 网关（TEST, 真 SUPER_ADMIN token）实测：POST 新主链 code=200 返回 46 条分页；GET 新路径 405；旧 GET /policies code=200；新旧 coverage 混传 code=100001。