64 行
5.0 KiB
Markdown
64 行
5.0 KiB
Markdown
# 【新增·管理后台】保险订单页投保下单支持「人员类型=司机」+ 出单自动绑定司机全年保险
|
||
|
||
> **变更类型**：新增入参 + 新增出参 + 前端交互改造（含 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），与游客订单险共存。
|