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

【后端行为变更·管理后台】保险保单下载改为只读 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。

---

变更点仅后端，前端按上表契约调用即可（与原契约一致）。如下载页有「点击触发生成」类交互可去掉，统一依赖后台异步出单 + 补传。