---
schema: "hl-changelog/v2"
ticket: "5537"
title: "车务保险保单查看（手动保单可见）+ 任务/保单筛选加司机名"
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@d5235e2d89ce009fbad251cf1428ba304333524c"
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. 保单号点击打开详情抽屉（被保人证件号已脱敏，无需前端二次处理）。