From c2dcf9efa4ad6975f704ba68b089ce2d1e9c59e9 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 12 Jun 2026 18:22:58 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E4=BF=9D=E9=99=A9?= =?UTF-8?q?=E8=AE=A2=E5=8D=95=E9=A1=B5=E5=8F=B8=E6=9C=BA=E6=8A=95=E4=BF=9D?= =?UTF-8?q?+=E5=B9=B4=E9=99=A9=E8=87=AA=E5=8A=A8=E7=BB=91=E5=AE=9A(#3760/P?= =?UTF-8?q?R#3770)=E2=80=94=E2=80=94=E4=BA=BA=E5=91=98=E7=B1=BB=E5=9E=8B?= =?UTF-8?q?=E5=8D=95=E9=80=89+bindAnnual+annualSource+=E4=B8=A4=E4=B8=AA?= =?UTF-8?q?=E6=90=9C=E7=B4=A2=E4=B8=8B=E6=8B=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...保与年险自动绑定-新增接口与保险块变更-管理后台.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 changelogs-v2/2026-06/12_3760_保险订单页司机投保与年险自动绑定-新增接口与保险块变更-管理后台.md diff --git a/changelogs-v2/2026-06/12_3760_保险订单页司机投保与年险自动绑定-新增接口与保险块变更-管理后台.md b/changelogs-v2/2026-06/12_3760_保险订单页司机投保与年险自动绑定-新增接口与保险块变更-管理后台.md new file mode 100644 index 0000000..6d1afdf --- /dev/null +++ b/changelogs-v2/2026-06/12_3760_保险订单页司机投保与年险自动绑定-新增接口与保险块变更-管理后台.md @@ -0,0 +1,63 @@ +# 【新增·管理后台】保险订单页投保下单支持「人员类型=司机」+ 出单自动绑定司机全年保险 + +> **变更类型**：新增入参 + 新增出参 + 前端交互改造（含 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 | 否 | 备注 | + +请求示例（保险订单页司机路径）： + +```bash +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），与游客订单险共存。