changelog(v2): 司机年险绑定保险订单台账(自动落单+双向关联+540224) (PR #3748/#3762)

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

@@ -0,0 +1,59 @@
+# 【修改接口·管理后台】司机档案——全年保险绑定保险订单台账(自动落单+双向关联)
+
+> 服务: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 司机 | 同上自动作废+解绑 |