67 行
2.2 KiB
Markdown
67 行
2.2 KiB
Markdown
# fix(contract): 合同 PDF 签署完成后转存到自家 OSS
|
|
|
|
**日期**: 2026-04-28
|
|
**PR**: #1535 (commit be7bd3e5b2)
|
|
**工单**: #1533
|
|
**影响端**: 后端内部（前端不感知，`contract.fileUrl` 仍是 PDF 下载链）
|
|
|
|
---
|
|
|
|
## 背景
|
|
|
|
12301 / 腾讯电子签平台返回的 PDF URL 是**临时下载链**，过期后 404，**合规留底丢失**。签署完成后异步下载平台 PDF 上传到自家 `hlgl-test` bucket，替换 `contract.file_url`。
|
|
|
|
## 后端改动
|
|
|
|
新增 `ContractPdfUploadService`（参照保险 `PolicyPdfUploadService`）：
|
|
- `@Async("insuranceTaskExecutor")` 复用保险线程池
|
|
- OSS key: `contract/pdf/{yyyy-MM}/{contractId}.pdf`
|
|
- 50 MB 大小上限
|
|
- 全异常吞 + log.error，不阻塞回调主链路
|
|
|
|
接入两个回调点（都用 `afterCommit` 钩子异步触发）：
|
|
- `ContractCallbackService` - 12301 SIGNED 回调
|
|
- `TencentEsignCallbackService` - 腾讯电子签 FLOW_COMPLETE 回调
|
|
|
|
## 数据流变化
|
|
|
|
### 修改前
|
|
```
|
|
平台签署完成 → 回调 → contract.file_url = 平台临时URL → 几小时后失效 → 404
|
|
```
|
|
|
|
### 修改后
|
|
```
|
|
平台签署完成 → 回调 → contract.file_url = 平台URL（先兜底）
|
|
→ afterCommit 异步：下载 → 上传 OSS → contract.file_url = 自家 OSS URL（永久）
|
|
→ OSS失败：保留平台 URL（不影响业务）
|
|
```
|
|
|
|
## URL 格式
|
|
|
|
成功后 `contract.file_url` 形如：
|
|
```
|
|
https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/pdf/2026-04/123456.pdf
|
|
```
|
|
|
|
## 前端兼容
|
|
|
|
**前端不需要任何改动** — `contract.fileUrl` 字段语义不变，只是后端把外链替换成自家链接。已下发链接（用户手机里的旧链）也仍然兼容到 OSS 失败兜底。
|
|
|
|
## 部署状态
|
|
|
|
⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。
|
|
|
|
## 部署后验证
|
|
|
|
1. 测试服 12301 测试平台真实跑一单合同签署
|
|
2. SQL: `SELECT contract_id, file_url FROM contract WHERE status='SIGNED' ORDER BY signed_at DESC LIMIT 1;`
|
|
3. `file_url` 必须以 `hlgl-test.oss-cn-beijing.aliyuncs.com` 开头
|
|
4. curl 该 URL 返回 200 PDF
|
|
|
|
## 不在范围
|
|
|
|
- 历史数据迁移（如需要单独工单）
|
|
- OSS 生命周期/归档策略（运维任务）
|
|
|