# 【行为优化·管理后台】保险「下载保单」改同步按需生成，去掉「保单生成中30秒后重试」轮询

> 端：hl-ui（保险订单 → 下载保单）| 服务：hl-order-service-v3 insurance | PR #3834 已合并 dev-v3 + 部署测试服 + 实测 | 2026-06-15

## ⚠️ 关键说明（前端体验变化）

「下载保单」`GET /v3/admin/insurance/policy/{id}/download` 行为优化：

- **旧**：PDF 还没上传 OSS 时，后端 fire-and-forget 异步补传 + 立刻返 `540310 保单生成中,约30秒后可重试`，**前端要等会儿再点一次（轮询）**。
- **新（同步按需生成）**：点下载时后端**同步**拉保游 PDF + 传 OSS，**直接把文件 URL 返回**。已承保订单**点一次、等几秒就拿到文件**，不用再重试轮询。

## 1. 前端需要配合的点

| 点 | 说明 |
|---|---|
| **响应可能慢几秒** | 同步拉 PDF 会让这个请求**阻塞几秒**（实测 1~3s）。前端点「下载」后**请显示 loading**，不要因为没秒回就当失败。 |
| **成功** | `code=200`，`data` = PDF 的 OSS URL，直接打开/下载即可。 |
| **仍可能返 540310** | 仅当保游侧 PDF 确实还没生成（罕见，正常已承保单下单后即可下）才返 `540310 保单生成中,稍后重试`——此时仍可稍后再点。**不再需要做高频自动轮询**，按需重试即可。 |
| **MANUAL 手工年保单** | 仍返 `540226`（无保游电子保单，真相在司机档案纸质附件），不变。 |

## 2. 契约不变

- 接口路径 / 入参 / 出参类型（`Result<String>`）**完全不变**，前端无需改调用方式，只需：① 加 loading；② 把原来的「自动轮询重试」简化成「按需重试」。

## 验收

已承保订单点「下载保单」：等几秒应直接得到 PDF 链接并下载成功（不再出现「稍后重试」让人反复点）。

> 注：测试环境保游异步出单产品的单一直停在「出单中」（保游测试不自动出单），**暂无保游真出单的已承保单可端到端验证下载成功路径**；后端代码路径（同步拉取 + 失败优雅兜底）已在线上验证。待保游真出单或换同步出单产品即可完整验证。