diff --git a/changelogs-v2/2026-06/12_3748_司机年险绑定保险订单台账-修改接口-管理后台.md b/changelogs-v2/2026-06/12_3748_司机年险绑定保险订单台账-修改接口-管理后台.md new file mode 100644 index 0000000..85a57e5 --- /dev/null +++ b/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 司机 | 同上自动作废+解绑 |