changelog #5640：司机详情页直接投保全年保险（含前端交接+生产年险计划配置遗留）

changelogs-v2/2026-08/07_5640_司机详情页直接投保全年保险-新增接口-管理后台.md

@@ -0,0 +1,64 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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 拦截。