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 到测试服。

部署后验证

测试服 12301 测试平台真实跑一单合同签署
SQL: SELECT contract_id, file_url FROM contract WHERE status='SIGNED' ORDER BY signed_at DESC LIMIT 1;
file_url 必须以 hlgl-test.oss-cn-beijing.aliyuncs.com 开头
curl 该 URL 返回 200 PDF

不在范围

历史数据迁移（如需要单独工单）
OSS 生命周期/归档策略（运维任务）

2.2 KiB 原始文件 Blame 文件历史 Unescape Escape