changelog: #5537 车务保险保单查看与司机名筛选（新增接口）

changelogs-v2/2026-08/06_5537_车务保险保单查看与司机名筛选-新增接口-管理后台.md

@@ -0,0 +1,96 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5537"
+title: "车务保险保单查看（手动保单可见）+ 任务/保单筛选加司机名"
+consumer: "admin"
+change_type: "新增接口"
+author: "wx(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端完成：PR #5543 已合并 dev-v3（merge e0cf4a47e）并部署 TEST；网关验证通过（保单列表/司机名筛选/详情/非法状态 400）。前端需在车务保险菜单新增保单 Tab（见展示矩阵）。"
+updated_at: "2026-08-05"
+base: "dev-v3"
+---
+
+# 车务: 保险保单查看（手动保单可见）+ 司机名筛选
+
+> **服务**: hl-fleet-service + hl-order-service-v3（内部接口）
+> **PR**: #5543
+> **Issue**: [#5537](https://git.1814.love:8443/wx/HL/issues/5537)
+> **日期**: 2026-08-05
+
+## 背景
+
+车务保险页面（`/admin/fleet/insurance`）此前只有任务视图（`tasks` 接口 = `fleet_insurance_task` 投退保流水），**手动投保的保单（`insurance_order` bizType=DRIVER）不可见**（排查实证：任务表 PURCHASE+SUCCESS+BAOYOU=0，手动投保从不落任务）。本次新增**保单维度**展示 + 手动投保成交自动落任务。
+
+## 变更接口
+
+| 方法 | 路径 | 来源 |
+|---|---|---|
+| `GET` | `/admin/fleet/insurance/policies` | `FleetInsuranceTaskController`（fleet） |
+| `GET` | `/admin/fleet/insurance/policies/{insuranceOrderId}` | 同上 |
+| `GET` | `/admin/fleet/insurance/tasks` | 同上（**新增 `driverName` 参数**） |
+| `GET` | `/v3/internal/insurance/policy-page` | `InternalInsuranceController`（order，Feign 内部） |
+| `GET` | `/v3/internal/insurance/policy/{insuranceOrderId}` | 同上（Feign 内部） |
+
+路径前缀 `/admin/fleet/**` 已由网关登录/角色校验与 `FleetAdminRoleGuardInterceptor`（VEHICLE_MANAGER / SUPER_ADMIN）收口，无需新增网关规则。
+
+## 1. 保单列表 `GET /admin/fleet/insurance/policies`
+
+请求参数（query，均选填）：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `page` / `pageSize` | int | 分页（pageSize ≤100） |
+| `driverName` | string | 司机名/被保人姓名模糊搜索（两步查 insured_person） |
+| `policyNo` | string | 保单号精确（ext_policy_no） |
+| `status` | string | PENDING=待出单 / INSURING=出单中 / INSURED=已承保 / CANCELLED=已退保 / FAILED=投保失败；非法枚举返 400 明确业务错误 |
+| `coverageStartDateFrom` / `coverageStartDateTo` | date | 保障起期区间（按 start_date） |
+
+响应 `data`（PageResult）：
+
+| 字段 | JSON 类型 | 说明 |
+|---|---|---|
+| `insuranceOrderId` | string(Long) | 保单 ID（雪花字符串） |
+| `policyNo` | string | 保单号 |
+| `extOrderNo` | string | 保游外部订单号（可空） |
+| `totalPremium` | string(BigDecimal) | 保费（元） |
+| `status` / `statusLabel` | string | 状态码 + 中文标签 |
+| `source` | string | BAOYOU / MANUAL |
+| `coverageStartDate` / `coverageEndDate` | date | 保障期间 |
+| `insuredName` | string | 被保人姓名（首位；司机险一人一单） |
+| `productName` / `planName` | string | 险种（产品·计划，可空） |
+| `driverId` | string(Long) | 司机 ID（bizId） |
+| `createTime` | string | 创建时间 |
+
+**展示矩阵**：
+- 数据源：`insurance_order`（bizType=DRIVER，与司机详情保单区域同源）+ `insured_person` + `insurance_plan/product`
+- 列建议：保单号 / 被保人 / 险种（产品·计划）/ 保费 / 保障期间 / 状态 / 创建时间
+- **保额**：产品/计划/费率表均无权威结构化保额字段，**不展示保额列**（如需展示需保游产品侧补字段，另行排期）
+- 状态色：INSURED 绿、PENDING/INSURING 橙、CANCELLED 灰、FAILED 红
+- 空态：空列表 + 提示"暂无保单"
+
+## 2. 保单详情 `GET /admin/fleet/insurance/policies/{insuranceOrderId}`
+
+响应 `data`：列表项全部字段 + `extPolicyNo` / `insuredPersons`（姓名+脱敏证件号，保前 3 尾 4）/ `planId` / `policyHolderName` / `remark` / `updateTime`。
+
+错误码：**540201** 保单不存在或非司机险 / **605601** 保险服务不可用 / 401 未登录。
+
+## 3. 任务列表新增 `driverName` 筛选
+
+`GET /admin/fleet/insurance/tasks?driverName=斯琴`：按任务快照 `driver_name` 模糊匹配。**原有枚举校验（taskType/taskStatus/source 非法值 400）保持不变**。
+
+## 4. 手动投保落任务（后端行为变更）
+
+手动投保（`POST /admin/fleet/drivers/{driverId}/insurance/purchase`）出单成功（保单状态 INSURED）后，自动在 `fleet_insurance_task` 落一条 PURCHASE+SUCCESS 流水（bizKey=`MANUAL_PURCHASE:{保单ID}`，幂等；落库失败仅告警不反噬投保）。任务列表（含司机名筛选）可查到手动保单任务；**受理期（INSURING）保单不落任务**，由保单 Tab 覆盖可见性。
+
+## 前端配合
+
+1. 车务保险菜单新增**保单 Tab**（复用 tasks 页面框架），列与筛选见展示矩阵；
+2. tasks Tab 筛选区增加**司机名**输入框（模糊搜索）；
+3. 保单号点击打开详情抽屉（被保人证件号已脱敏，无需前端二次处理）。