docs(前端通知): 保险下载保单改同步按需生成,去掉保单生成中轮询(PR #3834)

点下载后端同步拉保游PDF直接返URL,前端加loading+把自动轮询简化为按需重试,契约不变。
已合并dev-v3+部署+线上验证同步路径生效。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

changelogs-v2/2026-06/15_保险下载保单改同步按需生成-去掉保单生成中轮询-管理后台.md

@@ -0,0 +1,29 @@
+# 【行为优化·管理后台】保险「下载保单」改同步按需生成，去掉「保单生成中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 链接并下载成功（不再出现「稍后重试」让人反复点）。
+
+> 注：测试环境保游异步出单产品的单一直停在「出单中」（保游测试不自动出单），**暂无保游真出单的已承保单可端到端验证下载成功路径**；后端代码路径（同步拉取 + 失败优雅兜底）已在线上验证。待保游真出单或换同步出单产品即可完整验证。