# 【新增接口+入参变更·管理后台】司机险走保游网——档案页投保/保单/退保 + 保险块字段变更

> 服务:hl-fleet-service(8087) + hl-order-service-v3(8086) | 分支:dev-v3 | PR:#3700 | 已部署测试服并实测通过(2026-06-11)
> 契约出处:FLEET API §3.3/§3.4 保险块 + §13.7 | 业务拍板:司机险由车管在**司机档案页手动点「投保」**出单(非派车自动、非定时);保险提供方走 **order-v3**

## ⚠️ 关键说明(含 2 处破坏性变更)

1. **🔴 破坏性①——司机保存入参 `insurance.perDayRate` 字段删除**(§3.3 新增/§3.4 编辑):perTrip 日费率改走保游网计划费率,不再手填。前端表单请移除该输入项;继续传该字段会被忽略。
2. **🔴 破坏性②——`insurance.type=perTrip` 时 `insurancePlanId` 必填**(返 100001):从「司机可选保险计划下拉」(下方接口 1)选计划。`annual`/`none` 传 null;类型从 perTrip 切走时后端自动清空该字段。
3. 司机详情 §3.2 `insurance` 块新增回显 `insurancePlanId`(perTrip 有值,字符串雪花)。
4. **投保动作会真实调保游网出单、从保游账户真实扣费**——前端联调请只调下拉/保单列表/校验反例,出单正向请约定后用测试计划操作。
5. 计划下拉数据源 = 运营在「保险计划打标」端点把计划标为 `DRIVER`/`BOTH`(接口 5,order-v3 管理端);**新同步计划默认 CUSTOMER,司机端不可见**,须显式打标。

## 1. 司机可选保险计划下拉

`GET /admin/fleet/drivers/insurance/plan-options`

```json
{ "code": 200, "data": [
  { "planId": "2054773833342451714", "planName": "10万计划", "productName": "山河令（太保山东新）", "usageCategory": "DRIVER" }
], "message": "成功" }
```

## 2. 司机险投保(档案页「投保」按钮)

`POST /admin/fleet/drivers/{driverId}/insurance/purchase`

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| planId | string(雪花) | 是 | 司机专用计划(接口 1 选取) |
| coverageStartDate / coverageEndDate | string(yyyy-MM-dd) | 是 | 保障起止;**「按赛季」「按年」快捷预填由前端实现**(仍可手改);起>止返 100001 |
| remark | string | 否 | 缺省后端填「司机险投保: {司机姓名}」 |

成功返回保单(被保人证件号已脱敏;金额/雪花均字符串):

```json
{ "code": 200, "data": {
  "insuranceOrderId": "1934567890123456789", "policyNo": "...", "extPolicyNo": "BY-2026-...",
  "extOrderNo": "...", "totalPremium": "88.00", "status": "INSURED", "statusLabel": "已投保",
  "coverageStartDate": "2026-07-01", "coverageEndDate": "2027-06-30",
  "insuredPersons": [ { "name": "周师傅", "idCardNo": "1502**********0017" } ] } }
```

> 异步出单型产品返回 `status=INSURING`(投保中,`extPolicyNo` 暂空),保游回调落定后翻 `INSURED`/`FAILED`,刷新保单列表即可。

## 3. 司机保单列表

`GET /admin/fleet/drivers/{driverId}/insurance/policies` → `data` 为接口 2 同构对象数组(createTime 倒序;无保单返 `[]`)。

## 4. 司机险退保(仅人工误投时用)

`POST /admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel`

- 保单不属于该司机 → 100001(越权守卫);仅 `INSURED/INSURING` 可退,否则 540202。
- 业务拍板:**取消派车不退保、换司机投新单旧单到期自然失效、离职拉黑不自动退**——本端点只服务误投撤销。

## 5. 保险计划打标(order-v3 管理端·运营用)

`PUT /v3/admin/insurance/plans/{planId}/usage-category`  body:`{"usageCategory":"DRIVER"}`(白名单 CUSTOMER/DRIVER/BOTH,非法返 540223)。
配套:计划查询出参(`GET /v3/admin/insurance/products/{productId}/plans` 等)已新增 `usageCategory` 字段,可做打标 UI。客人端选计划**不收紧**(维持全量,拍板)。

## 6. 错误码汇总

| code | 触发场景 |
|---|---|
| 100001 | perTrip 缺 insurancePlanId / 保障起>止 / 退保保单不属于该司机 |
| 600205 | 司机不存在 |
| 540031 | 该保险计划未标注为司机可用(选了 CUSTOMER 计划) |
| 540032 | 该司机该保障期已有生效保单(一天只一份生效,含投保中) |
| 540202 | 保单当前状态不可退保 |
| 540223 | 计划使用分类非法(打标端点) |
| 605601 | 保险服务不可用(order-v3 不通,稍后重试) |

### 实测反例示例

```bash
# 选 CUSTOMER 计划投保 → 540031
curl -k -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"}'
# => {"code":540031,"message":"该保险计划未标注为司机可用"}

# perTrip 不带 insurancePlanId 建司机 → 100001
# => {"code":100001,"message":"参数非法: 保险类型为 perTrip 时缺少必填子字段: insurancePlanId(保险方案id,选保游网司机专用计划)"}
```