docs: 保单PDF改为OSS直链（policyPdfUrl），含管理端+小程序端使用说明
这个提交包含在：
API Changelog Bot
父节点
eac9eafee9
当前提交
11f0cee3ae
@ -1,87 +1,102 @@
|
|||||||
# 保单PDF下载接口说明
|
# 保单PDF完整URL（OSS直链）
|
||||||
|
|
||||||
**日期**: 2026-03-23 19:30
|
**日期**: 2026-03-23 19:40
|
||||||
**影响**: 管理端 + 小程序端
|
**影响**: 管理端 + 小程序端
|
||||||
|
**已部署**: 测试服务器 ✅
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 管理端：下载单张保单PDF
|
## 核心变更：保单现在有完整的 `.pdf` OSS链接
|
||||||
|
|
||||||
```
|
每份保险保单投保成功后，系统自动下载PDF并上传到OSS，保存为 `policyPdfUrl` 字段。
|
||||||
GET /admin/insurance/policy/{insuranceOrderId}/download
|
|
||||||
```
|
|
||||||
|
|
||||||
- 返回：Base64 编码的 PDF 字符串
|
**URL示例**: `https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/insurance/policy/2026/03/23/policy_2036026235003478018.pdf`
|
||||||
- `insuranceOrderId` 从保险保障接口 `GET /admin/insurance/coverage/{orderId}` 返回的 `insuranceOrders[].insuranceOrderId` 获取
|
|
||||||
- 前端解码 Base64 后用 `Blob` 创建下载链接或直接预览
|
|
||||||
|
|
||||||
### 前端示例
|
前端直接用这个URL打开/下载PDF即可，**不需要调Base64接口**。
|
||||||
|
|
||||||
```javascript
|
|
||||||
const res = await request.get(`/admin/insurance/policy/${insuranceOrderId}/download`)
|
|
||||||
const base64 = res.data
|
|
||||||
const blob = new Blob([Uint8Array.from(atob(base64), c => c.charCodeAt(0))], { type: 'application/pdf' })
|
|
||||||
const url = URL.createObjectURL(blob)
|
|
||||||
window.open(url) // 或创建 <a> 标签下载
|
|
||||||
```
|
|
||||||
|
|
||||||
### 建议
|
|
||||||
|
|
||||||
在保险保障卡片上加 **"查看保单"** 按钮，点击调用此接口下载PDF。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 小程序端：下载单张保单PDF
|
## 管理端
|
||||||
|
|
||||||
|
### 保险保障接口（已有）
|
||||||
```
|
```
|
||||||
GET /mp/insurance/policy/{insuranceOrderId}/download
|
GET /admin/insurance/coverage/{orderId}
|
||||||
```
|
```
|
||||||
|
|
||||||
- 返回：Base64 编码的 PDF 字符串
|
返回的 `insuranceOrders[]` 每条新增 `policyPdfUrl` 字段：
|
||||||
- `insuranceOrderId` 从订单详情 `travelers[].insurancePolicies[].insuranceOrderId` 获取
|
|
||||||
- 也可以从 `travelers[].insurancePolicies[].policyPdfApi` 获取完整路径（如 `/mp/insurance/policy/2036026235003478018/download`）
|
|
||||||
|
|
||||||
### 小程序端示例
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const res = await wx.request({ url: `${baseUrl}/mp/insurance/policy/${insuranceOrderId}/download` })
|
|
||||||
const base64 = res.data.data
|
|
||||||
// 写入临时文件
|
|
||||||
const filePath = `${wx.env.USER_DATA_PATH}/policy_${insuranceOrderId}.pdf`
|
|
||||||
const fs = wx.getFileSystemManager()
|
|
||||||
fs.writeFile({ filePath, data: base64, encoding: 'base64' })
|
|
||||||
wx.openDocument({ filePath, fileType: 'pdf' })
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 小程序端：获取订单所有保单PDF（合并）
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /mp/insurance/policy-pdf/{orderId}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 返回：`{ pdfBase64, personName, policyCount, failedCount }`
|
|
||||||
- 将该订单所有出行人的所有有效保单合并为一个PDF
|
|
||||||
- 适用于"一键查看全部保单"场景
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 出行人保单数据结构（订单详情 travelers 内）
|
|
||||||
|
|
||||||
每个出行人的 `insurancePolicies` 数组包含其关联的所有保单：
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"insuranceOrderId": "2036026235003478018",
|
"insuranceOrders": [
|
||||||
"productName": "保游未来星研学旅行保险",
|
{
|
||||||
"planName": "20万计划",
|
"insuranceOrderId": "2036026309016166401",
|
||||||
"extPolicyNo": "11209006600506820270",
|
"productName": "保游未来星研学旅行保险",
|
||||||
"startDate": "2026-03-31",
|
"planName": "30万计划",
|
||||||
"endDate": "2026-04-02",
|
"extPolicyNo": "11209006600506820271",
|
||||||
"status": "INSURED",
|
"startDate": "2026-04-03",
|
||||||
"statusLabel": "已承保",
|
"endDate": "2026-04-05",
|
||||||
"totalPremium": "1.50",
|
"status": "INSURED",
|
||||||
"policyPdfApi": "/mp/insurance/policy/2036026235003478018/download"
|
"policyPdfUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/insurance/policy/2026/03/23/policy_2036026309016166401.pdf"
|
||||||
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 前端展示建议
|
||||||
|
在每个保险卡片上加 **"查看保单"** 按钮：
|
||||||
|
```javascript
|
||||||
|
window.open(item.policyPdfUrl) // 直接打开PDF
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 小程序端
|
||||||
|
|
||||||
|
### 订单详情出行人保险数据
|
||||||
|
|
||||||
|
订单详情 `travelers[].insurancePolicies[]` 每条包含：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| insuranceOrderId | String | 保险订单ID |
|
||||||
|
| productName | String | 保险产品名称 |
|
||||||
|
| planName | String | 保险计划名称 |
|
||||||
|
| extPolicyNo | String | 保单号 |
|
||||||
|
| startDate | String | 保障开始日期 |
|
||||||
|
| endDate | String | 保障结束日期 |
|
||||||
|
| status | String | INSURED=已承保, CANCELLED=已退保 |
|
||||||
|
| statusLabel | String | 中文状态 |
|
||||||
|
| totalPremium | String | 保费 |
|
||||||
|
| **policyPdfUrl** | **String** | **保单PDF的OSS完整链接（.pdf结尾，直接可访问）** |
|
||||||
|
| policyPdfApi | String | 备用：Base64下载接口路径 |
|
||||||
|
|
||||||
|
### 小程序展示建议
|
||||||
|
|
||||||
|
出行人信息下方展示保单卡片，点击"查看保单"用 `wx.downloadFile` + `wx.openDocument`：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
wx.downloadFile({
|
||||||
|
url: item.policyPdfUrl,
|
||||||
|
success(res) {
|
||||||
|
wx.openDocument({ filePath: res.tempFilePath, fileType: 'pdf' })
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### 一个出行人多份保单
|
||||||
|
|
||||||
|
一个出行人可能有多份保单（覆盖不同日期段），`insurancePolicies` 是数组，按保障期间展示即可：
|
||||||
|
|
||||||
|
```
|
||||||
|
米明光
|
||||||
|
├── 保游未来星研学旅行保险 20万计划
|
||||||
|
│ 保障期间：2026-03-31 ~ 2026-04-02 [查看保单]
|
||||||
|
└── 保游未来星研学旅行保险 30万计划
|
||||||
|
保障期间：2026-04-03 ~ 2026-04-05 [查看保单]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 旧数据
|
||||||
|
|
||||||
|
所有历史保单的PDF已补传完成，`policyPdfUrl` 已全部填充。
|
||||||
|
|||||||
正在加载...
x
在新工单中引用
屏蔽一个用户