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

> 服务: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 出参

```json
{
  "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 出参(测试服实测)

```json
{
  "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 司机 | 同上自动作废+解绑 |