diff --git a/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md b/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md new file mode 100644 index 0000000..8596a89 --- /dev/null +++ b/changelogs/2026-05/09_refactor_admin_contract-scheme-drop-dispute-fields.md @@ -0,0 +1,130 @@ +# 合同方案删除「管辖法院/仲裁委员会/争议解决方式」3 字段 + +> **服务**: hl-order-service-v2 (8094) +> **PR**: #1929 +> **Issue**: #1928 +> **日期**: 2026-05-09 +> **影响范围**: admin「合同管理 → 合同方案」编辑/新增弹窗 + +--- + +## ⚠️ 关键变化 + +合同方案弹窗删除以下 3 个字段, **前端必须同步删 form item 否则保存接口会 400**: +- `disputeResolution` 争议解决方式 (1=诉讼 / 2=仲裁) +- `tribunalName` 仲裁委员会 +- `litigationCourt` 管辖法院 + +travel_agency 表已有 `tribunal_name` `litigation_court` 字段, 合同生成时自动从所选旅行社读取, 用户不再需要在合同方案里重复填。 + +--- + +## 一、背景 + +代码 `ContractCreateService.java:1179` 注释明确写: +> 业务规则(2026-05-04 用户反馈): 合同方案表单移除"管辖法院"输入(走 agency 自动兜底) + +历史改动只补了 fallback 逻辑没真删字段, 导致合同方案弹窗仍要求填这些字段, 用户多次反馈。本次彻底清理。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | +|---|------|------|------|----------| +| 1 | 创建合同方案 | POST | `/admin/contract/scheme` | 请求体删 3 字段 | +| 2 | 更新合同方案 | PUT | `/admin/contract/scheme/{schemeId}` | 请求体删 3 字段 | +| 3 | 查询启用方案列表 | GET | `/admin/contract/scheme/list` | 响应体删 3 字段 | +| 4 | 查询单个方案 | GET | `/admin/contract/scheme/{id}` | 响应体删 3 字段 | + +--- + +## 三、ContractSchemeRequest 入参变化 + +### 删除字段 (必删) + +```java +// 删除前 +private Integer disputeResolution; // @Min(1) @Max(2) +private String tribunalName; // @Size(max=100) +private String litigationCourt; // @Size(max=100) +``` + +前端 form 必须删除对应 input/radio。如果前端继续传这 3 个字段, Spring 反序列化会忽略(因为 DTO 上没有), 但建议同步删除 UI 避免误导用户。 + +### 保留字段(关键) + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `schemeName` | String | ✅ | 方案名称 | +| `contractPlatform` | String | ✅ | 合同平台 (12301 / TENCENT_ESIGN) | +| `contractTemplateCode` | String | ✅ | 合同模板编码 | +| `agencyCode` | String | ❌ | 旅行社编码(不填走支付商户号自动匹配) | +| `transactorName` | String | ❌ | 经办人姓名 | +| `transactorPhone` | String | ❌ | 经办人电话 | +| `signatoryMode` | Integer | ❌ | 签署模式 | +| `contractMode` | String | ❌ | 签约模式 | +| `supplementaryClause` | String | ❌ | 补充条款 | + +--- + +## 四、ContractSchemeVO 响应变化 + +响应体删除: +```json +// 修复前 +{ "disputeResolution": 2, "tribunalName": "呼伦贝尔仲裁委员会", "litigationCourt": "海拉尔区人民法院", ... } + +// 修复后 +{ "schemeName": "...", "contractPlatform": "12301", ... } // 3 字段消失 +``` + +如果前端编辑表单的 echo 逻辑里取了这 3 个值, 改成不取(或对不存在字段做容错)。 + +--- + +## 五、合同生成兜底逻辑(后端自动, 前端无感) + +走 12301 / 腾讯电子签生成合同时, 法律字段从所选 agency 读: + +| 字段 | 兜底链 | +|---|---| +| 仲裁委员会 | `agency.tribunal_name` → 常量「呼伦贝尔仲裁委员会」 | +| 管辖法院 | `agency.litigation_court` → 常量「海拉尔区人民法院」 | +| 争议解决方式 | 默认 `2` (仲裁) | + +travel_agency 表已存 `tribunal_name` `litigation_court`, admin「公司管理」编辑该公司时填写。 + +--- + +## 六、前端 mmg 改造点 + +### 文件: `hl-ui/src/views/contract/scheme/...`(合同方案弹窗) + +1. **删除 3 个 form item**: + - "争议解决方式" radio (1=诉讼 / 2=仲裁) + - "仲裁委员会" input + - "管辖法院" input +2. **submit 时不传** `disputeResolution / tribunalName / litigationCourt` +3. **echo 时不取** 这 3 个字段(响应体没有了, 取了会 undefined) +4. 弹窗变得更简洁(只剩方案名、合同平台、模板、签约/签署模式、旅行社、补充条款) + +### 测试服 API 验证 (2026-05-09 21:25) + +| Case | 实测 | +|---|---| +| `GET /admin/contract/scheme/list` | 200, 响应体已无 3 字段 | +| DB `SHOW COLUMNS FROM contract_scheme` | 3 列已 DROP, V20260510_001 success=1 | +| 合同生成走 12301 | tribunal/court 走 agency 字段, dispute 默认 2(仲裁), 单测 `disputeResolutionNull_fallbackToArbitration2` 验证通过 | + +--- + +## 七、不在本 PR 范围 + +- travel_agency 加 `dispute_resolution` 字段(让公司维度可配)留后续工单 +- 历史 contract_scheme 表 3 列值随 DROP COLUMN 丢失(业务上 agency 兜底, 不影响) +- 已签合同的渲染不受影响(渲染走快照, 此次只改新建合同的字段来源) + +--- + +**联系人**: wx