109 行
5.4 KiB
Markdown
109 行
5.4 KiB
Markdown
---
|
||
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. 保单号点击打开详情抽屉（被保人证件号已脱敏，无需前端二次处理）。
|
||
|
||
## 关联/联系人
|
||
|
||
### 链接
|
||
|
||
- [后端工单 #5537](https://git.1814.love:8443/wx/HL/issues/5537)
|
||
- [后端 PR #5543](https://git.1814.love:8443/wx/HL/pulls/5543)
|
||
- Merge commit: `e0cf4a47ef`
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|