hl-api-changelog/changelogs-v2/2026-06/12_3765_司机保单列表补source出参与MANUAL年保单PDF按钮收敛-修改接口-管理后台.md

【修改接口·管理后台】司机保单列表补 source 出参——MANUAL 年保单「下载/重传保单」按钮收敛

服务:hl-order-service-v3(8086/8186) + hl-fleet-service(8087) | 分支:dev-v3 | PR:#3765 | 已部署测试服并 4 项实测通过(2026-06-12) 背景:前端反馈——详情抽屉「下载保单/重传保单」按钮对 MANUAL 年保单仍显示,点击提示「保单生成中」不报错但语义偏。本次按约定把 source 带到按天保单列表 VO。

⚠️ 关键说明(前端动作)

1. 司机保单列表(GET /admin/fleet/drivers/{driverId}/insurance/policies)每行新增出参 source:BAOYOU=保游网出单 / MANUAL=手工录入(司机年保档案联动)。
2. 前端请按 source === 'MANUAL' 隐藏「下载保单」「重传保单」按钮——MANUAL 单无保游网电子保单,真相载体是司机档案附件里的纸质保单影印件。
3. MANUAL 单保留在保单列表中(确认结论:不该从列表消失——它是司机的真实保险记录,隐藏整行反而像没保险),仅 PDF 相关操作不可用。
4. 后端已加双保险:即使按钮没藏住/直调接口,下载与重传对 MANUAL 单现在返回明确错误码 540226「手工录入的年保单无电子保单,请查看司机档案附件中的纸质保单影印件」(替代原「保单生成中请稍后」误导提示),前端可直接 toast message。
5. 「分享保单」按订单维度查,MANUAL 单天然不出现,无需处理。

1. 保单列表出参变更(实测示例)

GET /admin/fleet/drivers/{driverId}/insurance/policies

{
  "code": 200,
  "data": [
    {
      "insuranceOrderId": "2068345678901234567",
      "policyNo": "PICC2026X04",
      "extPolicyNo": "PICC2026X04",
      "extOrderNo": null,
      "totalPremium": "3400.00",
      "status": "INSURED",
      "statusLabel": "已承保",
      "source": "MANUAL",               // 🆕 BAOYOU=保游网出单 MANUAL=手工录入年保;MANUAL 须隐藏下载/重传按钮
      "coverageStartDate": "2026-01-01",
      "coverageEndDate": "2026-12-31",
      "insuredPersons": [ { "name": "巴特尔", "idCardNo": "152***********0002" } ]
    }
  ]
}

2. PDF 入口错误码(后端兜底,实测)

调用	结果
GET /v3/admin/insurance/policy/{id}/download(MANUAL 单)	code=540226 手工录入的年保单无电子保单…
POST /v3/admin/insurance/policy/{id}/retry-upload(MANUAL 单)	code=540226 同上
BAOYOU 单两接口	行为不变

另:管理端「批量上传缺失保单PDF」已自动排除 MANUAL 单(后端内部优化,前端无感)。