78 行
2.4 KiB
Markdown
78 行
2.4 KiB
Markdown
# 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` 都保留）
|
||
|