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 生命周期/归档策略（运维任务）
|
||
|