From ea1b16a68df1d4971efdc8ed49ad0b3376698ca6 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 15 Jun 2026 17:26:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E5=89=8D=E7=AB=AF=E9=80=9A=E7=9F=A5):=20?= =?UTF-8?q?=E4=BF=9D=E9=99=A9=E4=B8=8B=E8=BD=BD=E4=BF=9D=E5=8D=95=E6=94=B9?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=E6=8C=89=E9=9C=80=E7=94=9F=E6=88=90,?= =?UTF-8?q?=E5=8E=BB=E6=8E=89=E4=BF=9D=E5=8D=95=E7=94=9F=E6=88=90=E4=B8=AD?= =?UTF-8?q?=E8=BD=AE=E8=AF=A2(PR=20#3834)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 点下载后端同步拉保游PDF直接返URL,前端加loading+把自动轮询简化为按需重试,契约不变。 已合并dev-v3+部署+线上验证同步路径生效。 Co-Authored-By: Claude Opus 4.8 --- ...单改同步按需生成-去掉保单生成中轮询-管理后台.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 changelogs-v2/2026-06/15_保险下载保单改同步按需生成-去掉保单生成中轮询-管理后台.md diff --git a/changelogs-v2/2026-06/15_保险下载保单改同步按需生成-去掉保单生成中轮询-管理后台.md b/changelogs-v2/2026-06/15_保险下载保单改同步按需生成-去掉保单生成中轮询-管理后台.md new file mode 100644 index 0000000..8595c0a --- /dev/null +++ b/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`）**完全不变**，前端无需改调用方式，只需：① 加 loading；② 把原来的「自动轮询重试」简化成「按需重试」。 + +## 验收 + +已承保订单点「下载保单」：等几秒应直接得到 PDF 链接并下载成功（不再出现「稍后重试」让人反复点）。 + +> 注：测试环境保游异步出单产品的单一直停在「出单中」（保游测试不自动出单），**暂无保游真出单的已承保单可端到端验证下载成功路径**；后端代码路径（同步拉取 + 失败优雅兜底）已在线上验证。待保游真出单或换同步出单产品即可完整验证。