202607014 feat 合伙人协议pdf接口

亲亲创客二期/文档/后端/api-doc-合伙人协议PDF.md

+# 合伙人合作协议 PDF 下载接口
+# 合伙人合作协议 PDF 下载接口
+
+> 实现位置：`hro/hro_spview/services/partner_api.groovy` → `agreement_pdf`
+> 用途：合伙人在小程序/H5 点击"查看/下载合作协议"时，拿到该用户专属的协议 PDF 下载地址。
+> 完成日期：2026-07-14
+
+---
+
+## 调用方式（领域服务）
+
+```ts
+sdk.domainServicePost(
+  "agreement_pdf",       // 接口名
+  { data: {} },          // 无需入参
+  false,                 // isAnonymous=false，需登录
+  "hro_spview",          // subProjectName
+  "partner_api"          // serviceName
+)
+```
+
+- **路由**：`POST /general/project/hro_spview/service/partner_api/agreement_pdf`
+- **认证**：需登录态。后端从 token 取当前登录 `uid`，据此查该用户的实名信息生成/返回其本人的协议，前端**不传任何标识**。
+
+---
+
+## agreement_pdf — 获取协议 PDF 下载地址
+
+- **入参**：无（`data: {}` 即可）。
+- **反参**（直接对象，字段在顶层）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| result | int | 0 成功 |
+| msg | string | 提示信息 |
+| url | string | **协议 PDF 完整下载地址**（前端直接用它下载/预览） |
+| fs | string | 文件相对路径 `fs/xxx`（一般用不到，`url` 已是完整地址） |
+
+- **示例**：
+
+```jsonc
+// 请求 data: {}
+// 响应
+{
+  "result": 0,
+  "msg": "成功",
+  "url": "http://<域名>/fs/1752480000000_xxxxxxxx",
+  "fs": "fs/1752480000000_xxxxxxxx"
+}
+```
+
+---
+
+## 行为说明（前端需知道的点）
+
+1. **幂等**：同一用户**第一次调用**会实时生成 PDF 并存库；**之后调用直接返回同一个 `url`**（不重复生成）。所以前端每次进入都可直接调，拿 `url` 即可，不用担心重复生成。
+2. **前提：用户已实名**。协议里的姓名、身份证号、手机号取自该用户的实名信息；未实名用户这些位置会为空。
+3. **PDF 特性**（后端已处理，前端无需关心，仅告知）：
+   - 已加**权限锁**：禁止修改、禁止复制文本，可查看/打印；打开**不需要密码**。
+   - 含**骑缝章**（每页右侧）。
+   - 内嵌中文字体，A4 版式。
+4. **报错**：`result != 0` 或抛异常时，`msg` 为原因（如"未找到当前用户信息"）。
+
+---
+
+## 备注
+
+- 首次生成有一点耗时（渲染 + 加章 + 加密），前端可加 loading；命中缓存后是秒回。
+- `url` 指向平台文件服务，直接 `window.open(url)` 或作为下载链接即可。