ea1b16a68d
点下载后端同步拉保游PDF直接返URL,前端加loading+把自动轮询简化为按需重试,契约不变。 已合并dev-v3+部署+线上验证同步路径生效。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
30 行
2.2 KiB
Markdown
30 行
2.2 KiB
Markdown
# 【行为优化·管理后台】保险「下载保单」改同步按需生成，去掉「保单生成中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 链接并下载成功（不再出现「稍后重试」让人反复点）。
|
||
|
||
> 注：测试环境保游异步出单产品的单一直停在「出单中」（保游测试不自动出单），**暂无保游真出单的已承保单可端到端验证下载成功路径**；后端代码路径（同步拉取 + 失败优雅兜底）已在线上验证。待保游真出单或换同步出单产品即可完整验证。
|