From 11f0cee3aee3b9c00bb2b97aa896211a52fb0916 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 23 Mar 2026 19:37:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=9D=E5=8D=95PDF=E6=94=B9=E4=B8=BA?= =?UTF-8?q?OSS=E7=9B=B4=E9=93=BE=EF=BC=88policyPdfUrl=EF=BC=89=EF=BC=8C?= =?UTF-8?q?=E5=90=AB=E7=AE=A1=E7=90=86=E7=AB=AF+=E5=B0=8F=E7=A8=8B?= =?UTF-8?q?=E5=BA=8F=E7=AB=AF=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-03/2026-03-23_insurance_pdf_api.md | 149 ++++++++++-------- 1 file changed, 82 insertions(+), 67 deletions(-) diff --git a/changelogs/2026-03/2026-03-23_insurance_pdf_api.md b/changelogs/2026-03/2026-03-23_insurance_pdf_api.md index f2ba880..bb585c0 100644 --- a/changelogs/2026-03/2026-03-23_insurance_pdf_api.md +++ b/changelogs/2026-03/2026-03-23_insurance_pdf_api.md @@ -1,87 +1,102 @@ -# 保单PDF下载接口说明 +# 保单PDF完整URL（OSS直链） -**日期**: 2026-03-23 19:30 +**日期**: 2026-03-23 19:40 **影响**: 管理端 + 小程序端 +**已部署**: 测试服务器 ✅ --- -## 管理端：下载单张保单PDF +## 核心变更：保单现在有完整的 `.pdf` OSS链接 -``` -GET /admin/insurance/policy/{insuranceOrderId}/download -``` +每份保险保单投保成功后，系统自动下载PDF并上传到OSS，保存为 `policyPdfUrl` 字段。 -- 返回：Base64 编码的 PDF 字符串 -- `insuranceOrderId` 从保险保障接口 `GET /admin/insurance/coverage/{orderId}` 返回的 `insuranceOrders[].insuranceOrderId` 获取 -- 前端解码 Base64 后用 `Blob` 创建下载链接或直接预览 +**URL示例**: `https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/insurance/policy/2026/03/23/policy_2036026235003478018.pdf` -### 前端示例 - -```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) // 或创建 标签下载 -``` - -### 建议 - -在保险保障卡片上加 **"查看保单"** 按钮，点击调用此接口下载PDF。 +前端直接用这个URL打开/下载PDF即可，**不需要调Base64接口**。 --- -## 小程序端：下载单张保单PDF +## 管理端 +### 保险保障接口（已有） ``` -GET /mp/insurance/policy/{insuranceOrderId}/download +GET /admin/insurance/coverage/{orderId} ``` -- 返回：Base64 编码的 PDF 字符串 -- `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` 数组包含其关联的所有保单： +返回的 `insuranceOrders[]` 每条新增 `policyPdfUrl` 字段： ```json { - "insuranceOrderId": "2036026235003478018", - "productName": "保游未来星研学旅行保险", - "planName": "20万计划", - "extPolicyNo": "11209006600506820270", - "startDate": "2026-03-31", - "endDate": "2026-04-02", - "status": "INSURED", - "statusLabel": "已承保", - "totalPremium": "1.50", - "policyPdfApi": "/mp/insurance/policy/2036026235003478018/download" + "insuranceOrders": [ + { + "insuranceOrderId": "2036026309016166401", + "productName": "保游未来星研学旅行保险", + "planName": "30万计划", + "extPolicyNo": "11209006600506820271", + "startDate": "2026-04-03", + "endDate": "2026-04-05", + "status": "INSURED", + "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` 已全部填充。