hl-api-changelog/changelogs-v2/2026-06/12_3748_司机年险绑定保险订单台账-修改接口-管理后台.md

【修改接口·管理后台】司机档案——全年保险绑定保险订单台账(自动落单+双向关联)

服务:hl-fleet-service(8087) + hl-order-service-v3(8086/8186) | 分支:dev-v3 | PR:#3748/#3754/#3758(空diff作废)/#3762 | 已部署测试服并 8 项端到端实测全过(2026-06-12) 契约出处:FLEET API v1.5.63 §3.2/§3.3/§3.4 + §13.7.7/§13.7.8 | wx 拍板:「司机的全年保险得和保险订单绑定」 前端编辑弹窗交互零改动——年险五件套照旧手填,绑定由后端自动完成。

⚠️ 关键说明

1. 编辑/新增司机选「全年保险」保存后,后端自动在保险订单台账生成一张 MANUAL 来源的年保单(保险管理→保险订单可见),保单号/保费/起止照搬档案录入值,状态=已投保(INSURED)。
2. 司机详情 insurance 块新增出参 insuranceOrderId(字符串,关联的台账单 ID;非 annual 或联动未完成时为 null)——前端可用它跳转保险订单详情。联动是提交后异步完成(秒级),保存接口响应里不会立即有值,刷新详情即可。
3. 再次编辑年险信息(保费/起止/保单号)→ 同一张台账单原地更新,不会重复开单。
4. 保险类型从「全年保险」切走(或删除司机)→ 台账单自动作废(CANCELLED)+ 解除关联。
5. MANUAL 年保单不能在保险订单页退保:点退保返 code=540224「手工录入的司机年保单请在司机档案中维护」——它没有保游网外部单,生命周期跟司机档案走。
6. 保险订单列表/详情新增出参:source(BAOYOU=保游网出单 / MANUAL=手工录入年保)、bizType(ORDER=订单险 / DRIVER=司机险)、bizId(字符串;DRIVER 行=司机ID)——列表页可按来源/归属区分展示(建议 MANUAL 行隐藏「退保」按钮)。
7. 口径:年险司机在保障期内再走「司机险投保」(保游网按天)会被 540032 保障期重叠拦截——年险已覆盖全年,按天投保=重复投保;确需投保请先把档案保险类型切走(台账单自动作废)再投。

1. 司机编辑/新增(§3.3/§3.4) — 入参零变化

入参与原来完全一致(type=annual + policyNo/annualPremium/annualStart/annualEnd 条件必填),无新增字段。

2. 司机详情(§3.2) — insurance 块新增 1 出参

{
  "insurance": {
    "type": "annual",
    "policyNo": "PICC2026X04",
    "annualPremium": "3400.00",
    "annualStart": "2026-01-01",
    "annualEnd": "2026-12-31",
    "insurancePlanId": null,
    "insuranceOrderId": "2068331660551747586"   // 🆕 关联台账单ID(字符串;非annual/未联动=null)
  }
}

3. 保险订单列表与详情 — 新增 3 出参(测试服实测)

{
  "insuranceOrderId": "2068331660551747586",
  "extPolicyNo": "PICC2026X04",
  "totalPremium": 3400.0,
  "status": "INSURED",
  "source": "MANUAL",                  // 🆕 BAOYOU=保游网出单 MANUAL=手工录入(司机年保档案联动)
  "bizType": "DRIVER",                 // 🆕 ORDER=订单险 DRIVER=司机险
  "bizId": "2065272153565020161"       // 🆕 归属业务ID(DRIVER=司机ID,字符串)
}

4. 端到端实测数据点(可作联调预期)

操作	结果
编辑司机设 annual 保存	200;~2 秒后详情 insuranceOrderId 有值;台账出现 MANUAL/DRIVER/INSURED 单
再编辑改保费 3400→3800	同一张台账单 totalPremium 更新,单号不变
保险订单页对 MANUAL 单点退保	code=540224
类型切回「无保险」	详情 insuranceOrderId=null;台账单变 CANCELLED
删除 annual 司机	同上自动作废+解绑