changelog(v2): 司机保单列表补source出参+MANUAL年保单PDF按钮收敛(540226) (PR #3765)

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

@@ -0,0 +1,47 @@
+# 【修改接口·管理后台】司机保单列表补 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`
+
+```json
+{
+  "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 单(后端内部优化,前端无感)。