5.4 KiB
schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | change_type | author | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 5537 | 车务保险保单查看（手动保单可见）+ 任务/保单筛选加司机名 | admin | 新增接口 | wx(GIT) | deployed | verified | implemented | pi-main-session | hl-admin@d5235e2d89ce009fbad251cf1428ba304333524c | 后端完成：PR #5543 已合并 dev-v3（merge e0cf4a47e）并部署 TEST；网关验证通过（保单列表/司机名筛选/详情/非法状态 400）。前端需在车务保险菜单新增保单 Tab（见展示矩阵）。 | 2026-08-05 | dev-v3 |
车务: 保险保单查看（手动保单可见）+ 司机名筛选
服务: hl-fleet-service + hl-order-service-v3（内部接口） PR: #5543 Issue: #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 覆盖可见性。
前端配合
- 车务保险菜单新增保单 Tab（复用 tasks 页面框架），列与筛选见展示矩阵；
- tasks Tab 筛选区增加司机名输入框（模糊搜索）；
- 保单号点击打开详情抽屉（被保人证件号已脱敏，无需前端二次处理）。
关联/联系人
链接
- 后端工单 #5537
- 后端 PR #5543
- Merge commit:
e0cf4a47ef
联系人
- 后端负责人: @wx