wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/12_3760_保险订单页司机投保与年险自动绑定-新增接口与保险块变更-管理后台.md

5.0 KiB
原始文件 永久链接 Blame 文件历史

【新增·管理后台】保险订单页投保下单支持「人员类型=司机」+ 出单自动绑定司机全年保险

变更类型：新增入参 + 新增出参 + 前端交互改造（含 2 个搜索下拉） 影响端：管理后台（保险订单页 + 司机档案页） 关联：工单 #3760 / PR #3770（已合并 dev-v3，测试服已部署实测通过） 服务：hl-fleet-service + hl-order-service-v3 文档：API-SPEC-FLEET v1.5.68（§3.8 / §13.7.9）/ SRS §9.17.5

⚠️ 关键说明

  1. 保险订单页「投保下单」弹窗需加「人员类型」单选：客人（默认）/ 司机。客人路径现行为零变化（关联订单 orderId 仍必填）；司机路径是新交互（见下）。
  2. 司机路径不调 v3 投保接口，改调 fleet 的司机投保端点（POST /admin/fleet/drivers/{driverId}/insurance/purchase）并传 bindAnnual: true——出单成功后该保单自动绑定为司机档案的「全年保险」（一个保单只对应一个司机）。
  3. 被保人不可编辑：司机路径下被保人=该司机本人一条，后端按司机档案自动组装，前端隐藏被保人编辑区（不要传 insuredPersons）。
  4. 两个搜索下拉（顺便解决项，wx 指示）：
    • 弹窗「选择司机」：搜索下拉，数据源 GET /admin/fleet/drivers/page?keyword=（姓名模糊 + 11 位手机全号精确）
    • 客人路径「关联订单」：输入框改搜索下拉，数据源 GET /v3/admin/order/list（keyword 模糊）
  5. 保险计划下拉（司机路径）：用 GET /admin/fleet/drivers/insurance/plan-options（只列运营已打标 DRIVER/BOTH 的计划）。当前测试服该列表为空——需运营先在保险产品侧打标（PUT /v3/admin/insurance/plans/{planId}/usage-category，出参 PlanItem 已有 usageCategory 字段可做打标 UI，见 11_3700 changelog 第 5 点，打标 UI 目前尚未建，前端可一并补）。

1. fleet 司机投保接口加 bindAnnual 入参

POST /admin/fleet/drivers/{driverId}/insurance/purchase

字段 类型 必填 说明
planId string(雪花) 是 保险计划id（从 plan-options 下拉取）
coverageStartDate / coverageEndDate string(date) 是 保障起止（司机路径建议按年预填）
bindAnnual boolean 否 🆕 true=出单成功后自动绑定为司机全年保险；缺省 false（司机档案页投保入口现行为零变化）
remark string 否 备注

请求示例（保险订单页司机路径）：

curl -X POST "https://api.test.1814.love:9443/admin/fleet/drivers/{driverId}/insurance/purchase" \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"planId":"2054773833342451714","coverageStartDate":"2026-07-01","coverageEndDate":"2027-06-30","bindAnnual":true}'

绑定效果（bindAnnual=true 出单受理成功后，后端自动完成，前端无需额外调用）：司机档案 insurance.type 变 annual、保费/起止回填、insuranceOrderId 指向新保单、annualSource 变 baoyou；保单号（extPolicyNo）异步出单时为空，承保回调后自动补填。

2. 司机档案 insurance 块新增出参 annualSource

GET /admin/fleet/drivers/{driverId} 等 insurance 块：

字段 类型 说明
annualSource string 🆕 年保来源：manual=车管手填自有年保单（默认）/ baoyou=保游网出单自动绑定；仅 type=annual 有意义；只读·入参忽略

前端按 annualSource=baoyou 把档案编辑弹窗的年保四件套（保单号/年保费/起止）置为只读——绑定态下这 4 个字段入参会被后端忽略（保持绑定值）；保单号出单中可能为空串属合法态。若要把 baoyou 年险改成手填：先把类型切走（自动解绑）再切回 annual 手填。

3. 行为与错误码

场景 结果
选了未标司机可用的计划（CUSTOMER） 540031 该保险计划未标注为司机可用（测试服已实测）
该司机保障期与已有年险/在途保单重叠 540032 拒绝，提示先在司机档案处理
出单成功但本地绑定失败 🆕 600206 「保险出单成功但年险绑定失败，请勿重复投保…」——前端务必原样展示该消息（保单已生效，重复投保会被拦）
出单失败（FAILED）/ 保单被退保（CANCELLED） 后端自动解绑：档案保险回退 none（原 perTrip 计划不会恢复，需人工重选），前端无需处理
重复点击投保 v3 幂等拦截（短窗内重复请求被拒），按错误提示处理即可
编辑档案时类型从 annual(baoyou) 切走 仅解绑（档案与保单脱钩），不自动退保——退保仍走保单列表/档案保单页手动操作

4. 保险订单列表呈现

司机年险出单后会以 bizType=DRIVER、source=BAOYOU 出现在保险订单列表（列表 source/bizType/bizId 出参见 11_3748 / 12_3765 changelog），与游客订单险共存。