docs: 保单PDF下载接口说明（管理端+小程序端）

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"
+}
+```