46 行
2.8 KiB
Markdown
46 行
2.8 KiB
Markdown
【后端行为变更·管理后台】保险保单下载改为只读 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。
|
||
|
||
---
|
||
|
||
变更点仅后端，前端按上表契约调用即可（与原契约一致）。如下载页有「点击触发生成」类交互可去掉，统一依赖后台异步出单 + 补传。
|