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

服务: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 处破坏性变更)

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

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

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

{ "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	否	缺省后端填「司机险投保: {司机姓名}」

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

{ "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 不通,稍后重试)

实测反例示例

# 选 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,选保游网司机专用计划)"}

4.9 KiB 原始文件 Blame 文件历史