---
schema: "hl-changelog/v2"
ticket: "5640"
title: "司机详情页直接投保全年保险 POST /admin/fleet/drivers/{id}/insure"
consumer: "admin"
author: "wx"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "845d8827"
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5645/#5651/#5652 合并 dev-v3（6f7a9c19b70444395558f137e4cde6fb9524ecff）并部署 TEST；网关实证 600211 守卫+直接投保出单（INSURED）+保单可查+档案年险回填+重复投保 540032 拦截。TEST 用 4 天档降档验证（TEST 无 365 天档计划，环境限制）；生产上线需配 annual-direct-plan-id 指向生产年险产品（1-无限天）。"
updated_at: "2026-08-07"
base: "dev-v3"
generated: "2026-08-07T16:20:00+08:00"
---

# 司机详情页直接投保全年保险（#5640）

## 背景

司机详情页此前只能查看保单、不能直接投保；现有投保只有按行程（PER_TRIP 派单自动投）与手动选计划/起止的 purchase 接口。本单新增「一键直接投保全年保险」端点（wx 口径：直接投保=给司机投全年保险 annual policy，保额/期限按计划默认不可选，被保人=司机档案证件）。

## 新增接口

### `POST /admin/fleet/drivers/{driverId}/insure` —— 司机直接投保全年保险

**入参**：无（仅路径 driverId）。

**行为**：
- 默认计划解析：nacos `fleet.insurance.annual-direct-plan-id`（缺省回落 `annual-gap-plan-id`）→ DRIVER/BOTH 可用计划唯一候选自动选；**多候选/无候选抛 600211**（禁止按列表顺序猜测保额）。
- 保障期：**T+1 起保**（保游硬性约束：即时生效保险起保日必须大于当前时间，540030）× `fleet.insurance.annual-direct-coverage-days` 天（**默认 365=全年**；TEST 环境无 365 天档计划，配 4 天降档验证）。
- 被保人：司机档案证件（姓名/身份证/手机/性别自动组装）。
- 受理即绑档案年险：insurance_type=annual + 保单号/保费/起止回填 + annualSource=baoyou；保游回调 INSURED 补真实保单号，FAILED/CANCELLED 自动解绑回退（沿用 #3760/#5558 Saga）。
- 幂等：同日同人幂等键 + 上游 540032（保障期重叠）双重拦截重复投保。

**响应**：`DriverInsurancePolicyDTO`（与 purchase/policies 同结构，证件号脱敏）。

**错误码**：600205 司机不存在 / **600211 未配置默认全年保险计划且候选不唯一（新增）** / 100001 司机身份证非18位 / 540031 计划未标注司机可用 / 540032 保障期已有生效保单 / 540005 计划不存在 / 540007 无匹配费率 / 540034 产品已下架不可售 / 600206 出单成功但年险绑定失败 / 605601 保险服务不可用。

## 前端交接（司机详情页【投保】按钮）

- 按钮调 `POST /admin/fleet/drivers/{driverId}/insure`（无 body）。
- 成功：返回保单 DTO，提示投保成功并刷新保单列表（`GET /{driverId}/insurance/policies`）与司机详情（insurance_type 变 annual、年险四件套已回填）。
- 600211：提示「未配置默认全年保险计划，请联系运营」；540032：提示「该保障期已有生效保单」；600206：提示「出单成功但年险绑定失败，勿重复投保，联系管理员」。
- 建议按钮在司机已有生效年险时禁用或二次确认（前端可据详情接口 insurance_type/年险起止判断）。

## 配置项（nacos `hl-fleet-service-${env}.yml` → `fleet.insurance`）

| 键 | 含义 | TEST | 生产 |
|---|---|---|---|
| `annual-direct-plan-id` | 直接投保默认计划 | 2067501078319951874（畅心游20万） | **待配：指向生产年险产品计划（1-无限天）** |
| `annual-direct-coverage-days` | 保障天数，默认 365 | 4（TEST 无 365 天档，降档验证） | 不配（默认 365） |

**遗留（不阻塞本单）**：生产 `annual-direct-plan-id` 需运营在保游维护/确认年险产品计划后配置（wx 确认生产有 1-无限天司机年险产品）。

## 验证

- DriverInsuranceServiceTest **30/30**：配置计划一年期+受理即绑 / 单候选自动选 / 多候选 600211 / 无候选 600211 / 降档天数投保。
- 6f7a9c19 全量 verify **3253 项 0F/0E**/4 skipped。
- 网关实证：未配置→600211；配置后投保出单 INSURED（8.8~8.11 4 天档）；保单列表可查；档案年险回填；insurance_order 落账 DRIVER+司机；重复投保 540032 拦截。