通知: 合同模块3条改动 (#1532中文化 #1533PDF入OSS #1536投诉电话硬编码)
这个提交包含在：
API Changelog Bot
父节点
bf52afa11e
当前提交
b993709c77
@ -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 不再因投诉电话字段缺失拒签
|
||||
|
||||
@ -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 生命周期/归档策略（运维任务）
|
||||
|
||||
@ -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` 都保留）
|
||||
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户