diff --git a/changelogs-v2/2026-06/12_3765_司机保单列表补source出参与MANUAL年保单PDF按钮收敛-修改接口-管理后台.md b/changelogs-v2/2026-06/12_3765_司机保单列表补source出参与MANUAL年保单PDF按钮收敛-修改接口-管理后台.md new file mode 100644 index 0000000..8b7a0bd --- /dev/null +++ b/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 单(后端内部优化,前端无感)。