docs(changelog): 保险保单下载只读OSS不再现拉第三方+540310自愈(PR #3959, 管理后台)

changelogs-v2/2026-06/18_保险保单下载只读OSS不再现拉第三方-540310自愈-管理后台.md

@@ -0,0 +1,45 @@
+【后端行为变更·管理后台】保险保单下载改为只读 OSS、不再同步现拉第三方；540310「保单生成中」现可自愈
+
+> 服务：hl-order-service-v3（订单服务v3）
+> 关联 PR：#3959（Closes #3958），已合并 dev-v3 + 部署测试服双实例 + API 实测通过
+> 类型：**后端行为变更**（接口契约不变，下载行为与可靠性优化）
+> 端点：`GET /v3/admin/insurance/policy/{id}/download`
+
+## ⚠️ 关键说明
+
+后台「保险管理 → 保险订单」点下载保单时偶发「保单生成中，约 30 秒后可重试」，且下载会卡顿数十秒。根因：保单 PDF 本应在承保时异步下载存 OSS，但首次异步上传失败即永久卡住、无重试，于是下载端走「空 URL 时当场同步调第三方拉取」的兜底，慢且常失败。
+
+本次后端改造（**接口入参/出参契约完全不变**，前端无需改调用）：
+1. 下载端**只读 OSS**：有 `policyPdfUrl` 返之；没有则直接返 `540310`，**不再同步阻塞调第三方**，响应从数十秒降到约 0.5~1.2 秒。
+2. 承保 / 出单回调改 afterCommit 异步上传 OSS（消除竞态）。
+3. 新增定时补传 job（每 5 分钟）扫「已承保但缺 PDF」的单自动补传 OSS。
+
+**对前端的影响**：拿到 `540310`「保单生成中」时，**短轮询 / 稍后重试即可自愈**——后台异步链路会在数分钟内把 PDF 填进 OSS，之后下载即返真实 OSS URL。无需前端触发生成，也不要把下载当作"触发出单/生成"的动作。
+
+## 1. 接口契约（不变，仅重申）
+
+| 项 | 内容 |
+|----|------|
+| 方法/路径 | `GET /v3/admin/insurance/policy/{id}/download` |
+| 入参 | path `id`=保险订单 ID |
+| 成功 | `code=200`，`data`=保单 PDF 的 OSS URL（字符串） |
+| 未就绪 | `code=540310`，`message`=「保单生成中，约 30 秒后可重试」，`data=null` |
+| 手工年保单 | `code=540226`（无电子保单，真相在司机档案纸质影印件） |
+
+## 2. 前端处理建议
+
+1. `200` → 用 `data`（OSS URL）直接下载 / 预览。
+2. `540310` → 提示「保单生成中，稍后重试」，**可加自动短轮询**（如每 10~15s 重试、最多几次）；现在后台会自动补传，重试能拿到结果，不再永久卡。
+3. `540226` → 提示「手工录入年保单无电子保单」。
+
+## 3. 实测（测试服网关 9443 + 真 admin token）
+
+```
+GET /v3/admin/insurance/policy/2067403577227137025/download
+→ code=540310  elapsed=0.53s  （快速返回，未再同步调第三方）
+```
+承保后异步 + 定时补传补齐 OSS 后，同一接口将返 200 + OSS URL。
+
+---
+
+变更点仅后端，前端按上表契约调用即可（与原契约一致）。如下载页有「点击触发生成」类交互可去掉，统一依赖后台异步出单 + 补传。