diff --git a/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md b/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md new file mode 100644 index 0000000..58a4e9a --- /dev/null +++ b/changelogs/2026-04/28_fix_contract_hardcode-complaint-phones.md @@ -0,0 +1,53 @@ +# fix(contract): 12301 申报合同硬编码两个投诉电话字段 + +**日期**: 2026-04-28 +**PR**: #1537 (commit 4e63f5d53a) +**工单**: #1536 +**影响端**: 后端内部(12301 平台必填字段补全) + +--- + +## 背景 + +12301 申报合同 API 的 `travelAgency` 块两个必填投诉电话字段当前**完全没拼装到 JSON**,触发青岛文旅局案例文1-2 ¥10万 + 停业3月 P0 红线。 + +## 后端改动 + +`TourageRequestBuilder.buildTravelAgency` 末尾追加 2 行: + +```java +agency.put("localComplaintPhone", "12301"); // 全国旅游服务热线 (固定) +agency.put("complaintPhone", "470-8222122"); // 呼伦贝尔本地投诉电话 (固定) +``` + +## 设计决策 + +| 字段 | 值 | 为什么硬编码不读 Nacos | +|---|---|---| +| `localComplaintPhone` | `"12301"` | 国家文旅部全国统一旅游投诉热线,全国所有旅行社都填这个,不会变 | +| `complaintPhone` | `"470-8222122"` | 呼伦贝尔本地投诉电话,跟 Nacos `agencies[].complaint-phone=4000881814` 是不同语义(4000881814 是呼籁客服热线,470-8222122 是文旅监管投诉热线) | + +## 影响 + +- 12301 申报合同 API 调用即生效,避免被 12301 平台拒签 +- 前端无感知 + +## 部署状态 + +⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。 + +## 部署后验证 + +1. 测试服跑一单 12301 标准模式合同(产品场景:境内游 7 日) +2. 查 hl-order-service-v2 日志找到 12301 标准接口请求 body +3. 必须包含: + ```json + "travelAgency": { + ... + "localComplaintPhone": "12301", + "complaintPhone": "470-8222122", + ... + } + ``` +4. 12301 平台返回 success 不再因投诉电话字段缺失拒签 + diff --git a/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md b/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md new file mode 100644 index 0000000..cfaaaad --- /dev/null +++ b/changelogs/2026-04/28_fix_contract_pdf-upload-to-oss-after-sign.md @@ -0,0 +1,66 @@ +# 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 生命周期/归档策略(运维任务) + diff --git a/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md b/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md new file mode 100644 index 0000000..7ed811c --- /dev/null +++ b/changelogs/2026-04/28_fix_contract_status-log-and-vo-fields-i18n.md @@ -0,0 +1,77 @@ +# fix(contract): 合同详情页状态变更记录与字段值中文化 + +**日期**: 2026-04-28 +**PR**: #1534 (commit 9d420cb61d) +**工单**: #1532 +**影响端**: 管理后台 (admin) - 合同详情页 + +--- + +## 背景 + +合同详情页「状态变更记录」显示英文 `PENDING → GENERATED 来源: MANUAL`、「签约模式 ONLINE」、「证件类型 ID_CARD`,应显示中文。 + +## 后端改动 + +**新增 4 个 `*Label` 字段**(接口返回 JSON 同时含原始 value + 中文 label,前端用哪个都可以): + +### `ContractDetailVO.statusLogs[]` 每项新增 + +```json +{ + "logId": 1, + "oldStatus": "PENDING", + "oldStatusLabel": "待创建", // 新增 + "newStatus": "GENERATED", + "newStatusLabel": "已生成", // 新增 + "source": "MANUAL", + "sourceLabel": "手动", // 新增 + "createTime": "2026-04-28T14:21:14" +} +``` + +### `ContractDetailVO.travelers[]` 每项新增 + +```json +{ + "name": "王骁", + "idCardType": "ID_CARD", + "idCardTypeLabel": "身份证", // 新增 + "idCardNo": "152****5216" +} +``` + +### 主体已存在 ✅ + +`ContractVO.modeLabel` (`ONLINE → 线上签署`) 之前就有,前端记得用。 + +## 字典/枚举来源 + +| label 来源 | 枚举类 | +|---|---| +| `oldStatusLabel/newStatusLabel` | `ContractStatus.labelOf(value)` | +| `sourceLabel` | **新增枚举** `ContractStatusSource.labelOf(value)` (CALLBACK=回调/POLLING=轮询/MANUAL=手动/SYSTEM=系统) | +| `idCardTypeLabel` | `IdCardType.labelOf(value)` | +| `modeLabel` | `ContractMode.labelOf(value)` | + +`labelOf()` 静态方法对未知值/null 都返回 null(不抛异常),前端可放心展示无需 try/catch。 + +## 前端 TODO(yst/mmg) + +合同详情页:把英文渲染替换成 label 字段。建议优先级: + +1. 状态变更记录 list:`oldStatusLabel`、`newStatusLabel`、`sourceLabel` 取代原来的 oldStatus/newStatus/source +2. 出行人 list:「证件类型」列用 `idCardTypeLabel` 取代 `idCardType` +3. 「签约模式」字段用 `modeLabel`(如果之前已经用 `mode`,改成 `modeLabel`) + +label 字段如果是 null(脏数据/未知值场景)做空字符串兜底即可,不要 throw。 + +## 部署状态 + +⏸ 待手动触发 Deploy Panel 部署 hl-order-service-v2 到测试服。本地无法访问 Panel(timeout)。 + +## 影响范围 + +- 后端零破坏(只加字段,不删不改) +- 前端不消费新字段时仍兼容(原 `oldStatus/newStatus/source/idCardType/mode` 都保留) +