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