From b538ff365c98e28b8655a419589b83e467be30b2 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 18 Jun 2026 10:41:40 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E4=BF=9D=E9=99=A9=E4=BF=9D?= =?UTF-8?q?=E5=8D=95=E4=B8=8B=E8=BD=BD=E5=8F=AA=E8=AF=BBOSS=E4=B8=8D?= =?UTF-8?q?=E5=86=8D=E7=8E=B0=E6=8B=89=E7=AC=AC=E4=B8=89=E6=96=B9+540310?= =?UTF-8?q?=E8=87=AA=E6=84=88(PR=20#3959,=20=E7=AE=A1=E7=90=86=E5=90=8E?= =?UTF-8?q?=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...载只读OSS不再现拉第三方-540310自愈-管理后台.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 changelogs-v2/2026-06/18_保险保单下载只读OSS不再现拉第三方-540310自愈-管理后台.md diff --git a/changelogs-v2/2026-06/18_保险保单下载只读OSS不再现拉第三方-540310自愈-管理后台.md b/changelogs-v2/2026-06/18_保险保单下载只读OSS不再现拉第三方-540310自愈-管理后台.md new file mode 100644 index 0000000..d1ec41b --- /dev/null +++ b/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。 + +--- + +变更点仅后端，前端按上表契约调用即可（与原契约一致）。如下载页有「点击触发生成」类交互可去掉，统一依赖后台异步出单 + 补传。