hl-api-changelog/changelogs-v2/2026-06/15_司机投保保险计划下拉空-接口已全有需前端接线和加打标UI-管理后台.md

【前端接线 + 缺打标UI·管理后台】司机投保「保险计划」下拉空——后端端点全已存在，缺①计划没打「司机可用」标②前端没接对端点③缺打标入口UI

服务：hl-fleet-service（DriverInsuranceController，§13.7）+ hl-order-service-v3（计划打标）| 无 PR（端点全已存在，后端零改动）| 测试服实测（2026-06-15） 背景：wx 在「保险管理→保险订单→投保下单→人员类型=司机」选了司机后，「保险计划」下拉「无数据」，且找不到哪里能给计划设「司机可用」。wx 拍板：保险订单页 + 司机档案页两个入口都要能给司机投保。

⚠️ 关键判定：不是后端缺接口，是①没数据②前端没接对③缺一个打标UI

司机投保的 admin 端点早已全部存在（fleet DriverInsuranceController，base /admin/fleet/drivers）。保险订单页和司机档案页用同一套 fleet 端点即可（端点注释里已写明「保险订单页人员类型=司机路径传 bindAnnual=true」）：

用途	现成端点（直接接，无需后端补）	关键参数
司机可选计划下拉	GET /admin/fleet/drivers/insurance/plan-options	无参；只返 usageCategory=DRIVER/BOTH 的计划；返回 planId/planName/productName
司机险投保	POST /admin/fleet/drivers/{driverId}/insurance/purchase	body：planId(必填,下拉取)/coverageStartDate/coverageEndDate(必填)/remark(可选)/bindAnnual(保险订单页传 true=出单后自动绑为司机全年保险；档案页缺省 false)。被保人后端按司机档案自动组装，前端不传
司机保单列表	GET /admin/fleet/drivers/{driverId}/insurance/policies	按司机列全部保单
司机险退保	POST /admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel	仅人工误投手动退

为什么下拉空：一个计划都没被标「司机可用」

• 保险计划默认 usageCategory=CUSTOMER（客人用），司机下拉只列 DRIVER/BOTH 的（安全侧，防误投客人计划）。
• 实测：测试库 17 个计划全是 CUSTOMER，0 个司机可用 → 下拉必然空。
• 本次已临时标 2 个意外险计划为 DRIVER 作可测样本（「平安…专属意外险·计划一」+「山河令·10万计划」），现 plan-options 实测返 2 条。正式哪些计划算司机可用应由运营自己定/标（不是这 2 个写死）。

前端要做 3 件事

1. 保险订单页「人员类型=司机」：「保险计划」下拉改调 GET /admin/fleet/drivers/insurance/plan-options（不要调 order 的 /v3/admin/insurance/...，那边没有司机专用下拉）；「确认投保」改调 POST /admin/fleet/drivers/{driverId}/insurance/purchase 并传 bindAnnual=true；被保人列表那块不用填（后端按司机档案自动组装）。
2. 司机档案页投保：同样调上面两个端点，bindAnnual 缺省 false（行为不变）。
3. 🆕 加「设为司机可用」打标入口（这是当前唯一缺的 UI）：在「保险管理→保险产品/计划」页，每个计划加一个「使用分类」开关/下拉（客人 CUSTOMER / 司机 DRIVER / 通用 BOTH），调现成端点：
   • PUT /v3/admin/insurance/plans/{planId}/usage-category，body {"usageCategory":"DRIVER"}（白名单 CUSTOMER/DRIVER/BOTH，非法返 540223）。
   • 计划当前分类在产品详情 GET /v3/admin/insurance/products/all 的 plans[].usageCategory 里可读，用于回显。
   • 标好后司机下拉就有数据，运营无需找后端。

实测（测试服网关 9443）

PUT /v3/admin/insurance/plans/2054773833342451714/usage-category  {"usageCategory":"DRIVER"}  → 200 成功
GET /admin/fleet/drivers/insurance/plan-options  → code=200, 2 条
    [{planId:2054773828716134401, planName:"计划一", productName:"平安…专属意外险(海拉尔)", usageCategory:"DRIVER"},
     {planId:2054773833342451714, planName:"10万计划", productName:"山河令(太保山东新)", usageCategory:"DRIVER"}]

结论

后端零改动：司机投保 4 端点 + 计划打标端点全已存在并实测可用。缺口是前端接线（下拉/投保改调 fleet 端点）+ 新增一个计划打标 UI。投保正向流程会真扣保游账户余额，联调请只打到防御层（如未标计划计划 540031、重叠保障期 540032），勿真出单。