171 行
6.4 KiB
Markdown
171 行
6.4 KiB
Markdown
# 接口变更记录 — 2026-03-20（合同方案 + 模板筛选）
|
||
|
||
> **类型** feature + fix
|
||
|
||
---
|
||
|
||
## 一、合同方案管理菜单已添加
|
||
|
||
"合同管理"下新增"合同方案"子菜单，排在合同列表前面。
|
||
|
||
---
|
||
|
||
## 二、合同模板接口支持按平台筛选
|
||
|
||
### `GET` /admin/contract/templates
|
||
|
||
新增可选参数 `platform`，前端根据合同方案表单中选择的"合同平台"传值，实现模板联动筛选。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `platform` | String | 否 | 合同平台：`12301`=全国旅游监管平台，`FADADA`=法大大。不传则返回全部 |
|
||
|
||
**前端调整**：
|
||
- 合同方案新增/编辑表单中，选择"合同平台"后，调用 `/admin/contract/templates?platform=12301` 或 `?platform=FADADA` 刷新合同模板下拉列表
|
||
- 切换平台时需清空已选的合同模板
|
||
|
||
---
|
||
|
||
## 三、合同方案 — 旅行社改为非必填
|
||
|
||
### 变更说明
|
||
|
||
`ContractSchemeRequest` 中 `agencyCode`（旅行社编码）从**必填**改为**可选**。
|
||
|
||
**业务逻辑**：不填旅行社时，创建合同时会根据订单支付的商户号自动匹配对应公司的旅行社。
|
||
|
||
### `POST` /admin/contract/scheme — 创建合同方案
|
||
### `PUT` /admin/contract/scheme/{schemeId} — 更新合同方案
|
||
|
||
| 字段 | 变更 | 说明 |
|
||
|------|------|------|
|
||
| `agencyCode` | 必填 → **可选** | 不填则根据订单支付商户号自动匹配旅行社 |
|
||
|
||
**前端调整**：
|
||
- "旅行社"字段去掉必填星号 `*`
|
||
- 可以保留下拉选择，但允许不选
|
||
- 表单提交时不再校验旅行社必填
|
||
|
||
---
|
||
|
||
## 四、合同方案管理接口一览
|
||
|
||
以下接口用于"合同管理 → 合同方案"页面：
|
||
|
||
### `GET` /admin/contract/scheme/list-all — 全部方案列表（管理页面）
|
||
|
||
**响应**：`Result<List<ContractSchemeVO>>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `schemeId` | String | 方案ID |
|
||
| `name` | String | 方案名称 |
|
||
| `description` | String | 方案描述 |
|
||
| `contractPlatform` | String | 合同平台：`12301`/`FADADA` |
|
||
| `contractTemplateCode` | String | 合同模板编码 |
|
||
| `contractMode` | String | 签约模式：`STANDARD`=电子签约，`SYNC`=线下报备 |
|
||
| `signatoryMode` | Integer | 签署模式：1=短信签署，2=现场签署，3=线下签署 |
|
||
| `agencyCode` | String | 旅行社编码（可能为空） |
|
||
| `disputeResolution` | Integer | 争议解决方式：1=仲裁，2=诉讼 |
|
||
| `supplementaryClause` | String | 补充条款 |
|
||
| `transactorName` | String | 经办人姓名 |
|
||
| `transactorPhone` | String | 经办人电话 |
|
||
| `sortOrder` | Integer | 排序 |
|
||
| `status` | String | 状态：`ACTIVE`/`INACTIVE` |
|
||
|
||
### `GET` /admin/contract/scheme/list — 启用方案列表（产品配置下拉）
|
||
|
||
只返回 `status=ACTIVE` 的方案，用于产品编辑页"合同方案"下拉选择。
|
||
|
||
### `POST` /admin/contract/scheme — 创建方案
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | String | 是 | 方案名称 |
|
||
| `description` | String | 否 | 方案描述 |
|
||
| `contractPlatform` | String | 是 | 合同平台：`12301`/`FADADA` |
|
||
| `contractTemplateCode` | String | 是 | 合同模板编码（从模板列表接口获取） |
|
||
| `contractMode` | String | 是 | 签约模式：`STANDARD`/`SYNC` |
|
||
| `signatoryMode` | Integer | 是 | 签署模式：1/2/3 |
|
||
| `agencyCode` | String | **否** | 旅行社编码（不填则自动匹配） |
|
||
| `disputeResolution` | Integer | 是 | 争议解决方式：1=仲裁，2=诉讼 |
|
||
| `supplementaryClause` | String | 否 | 补充条款 |
|
||
| `transactorName` | String | 是 | 经办人姓名 |
|
||
| `transactorPhone` | String | 是 | 经办人电话 |
|
||
| `sortOrder` | Integer | 否 | 排序（默认0） |
|
||
|
||
### `PUT` /admin/contract/scheme/{schemeId} — 更新方案
|
||
|
||
请求参数同创建。
|
||
|
||
### `PUT` /admin/contract/scheme/{schemeId}/toggle-status — 切换启用/停用
|
||
|
||
### `DELETE` /admin/contract/scheme/{schemeId} — 删除方案
|
||
|
||
---
|
||
|
||
## 五、合同方案响应新增回显字段 + 字段别名
|
||
|
||
### 变更说明
|
||
|
||
合同方案响应（`ContractSchemeVO`）新增以下字段，解决**编辑回显**和**字段命名统一**问题：
|
||
|
||
| 新增字段 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| `templateCode` | String | 合同模板编码（与 `contractTemplateCode` **相同值**，方便前端统一使用 `templateCode` 绑定下拉） |
|
||
| `contractTemplateName` | String | 合同模板名称（回显用，如"国内旅游合同-标准版"） |
|
||
| `agencyName` | String | 旅行社名称（回显用，如"内蒙古呼籁国际旅行社有限公司"） |
|
||
|
||
### 保存时字段兼容
|
||
|
||
保存（创建/更新）时，**`contractTemplateCode` 和 `templateCode` 都接受**。前端可以统一用 `templateCode` 作为合同模板下拉的 `value` 字段。
|
||
|
||
```json
|
||
// 以下两种写法等价：
|
||
{ "contractTemplateCode": "A00001", ... }
|
||
{ "templateCode": "A00001", ... }
|
||
```
|
||
|
||
### 前端使用方式
|
||
|
||
1. **模板下拉绑定**：用 `templateCode` 作为下拉的 `v-model` 绑定值
|
||
2. **编辑回显**：方案详情返回的 `templateCode` 可直接匹配模板列表的 `templateCode`
|
||
3. **模板名称显示**：列表页可直接用 `contractTemplateName` 显示模板名称，无需额外查询
|
||
4. **旅行社名称显示**：列表页可用 `agencyName` 显示旅行社名称
|
||
|
||
### 完整响应示例
|
||
|
||
```json
|
||
{
|
||
"schemeId": "123456789",
|
||
"name": "标准国内电子签约方案",
|
||
"contractPlatform": "12301",
|
||
"contractTemplateCode": "A00001",
|
||
"templateCode": "A00001",
|
||
"contractTemplateName": "国内旅游合同-标准版",
|
||
"contractMode": "STANDARD",
|
||
"signatoryMode": 1,
|
||
"agencyCode": "agency_hlgj",
|
||
"agencyName": "内蒙古呼籁国际旅行社有限公司",
|
||
"disputeResolution": 1,
|
||
"transactorName": "张三",
|
||
"transactorPhone": "13800138000",
|
||
"sortOrder": 0,
|
||
"status": "ACTIVE"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端重点调整总结
|
||
|
||
| 页面 | 调整项 |
|
||
|------|--------|
|
||
| 合同方案新增/编辑表单 | "旅行社"去掉必填星号，允许不选 |
|
||
| 合同方案新增/编辑表单 | "合同模板"下拉根据选择的"合同平台"联动筛选，调用 `/admin/contract/templates?platform=xxx` |
|
||
| 合同方案新增/编辑表单 | 切换合同平台时清空已选的合同模板 |
|
||
| 合同方案新增/编辑表单 | 模板下拉 `v-model` 绑定 `templateCode`（保存和回显统一使用此字段） |
|
||
| 合同方案列表页 | 可用 `contractTemplateName` 和 `agencyName` 直接显示名称 |
|