From eac9eafee93a3858db2aebff9ff8e3efd1be58f4 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 23 Mar 2026 19:22:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=9D=E5=8D=95PDF=E4=B8=8B=E8=BD=BD?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E8=AF=B4=E6=98=8E=EF=BC=88=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E7=AB=AF+=E5=B0=8F=E7=A8=8B=E5=BA=8F=E7=AB=AF=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-03/2026-03-23_insurance_pdf_api.md   | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 changelogs/2026-03/2026-03-23_insurance_pdf_api.md

diff --git a/changelogs/2026-03/2026-03-23_insurance_pdf_api.md b/changelogs/2026-03/2026-03-23_insurance_pdf_api.md
new file mode 100644
index 0000000..f2ba880
--- /dev/null
+++ b/changelogs/2026-03/2026-03-23_insurance_pdf_api.md
@@ -0,0 +1,87 @@
+# 保单PDF下载接口说明
+
+**日期**: 2026-03-23 19:30
+**影响**: 管理端 + 小程序端
+
+---
+
+## 管理端：下载单张保单PDF
+
+```
+GET /admin/insurance/policy/{insuranceOrderId}/download
+```
+
+- 返回：Base64 编码的 PDF 字符串
+- `insuranceOrderId` 从保险保障接口 `GET /admin/insurance/coverage/{orderId}` 返回的 `insuranceOrders[].insuranceOrderId` 获取
+- 前端解码 Base64 后用 `Blob` 创建下载链接或直接预览
+
+### 前端示例
+
+```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
+```
+
+- 返回：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` 数组包含其关联的所有保单：
+
+```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"
+}
+```