diff --git a/changelogs/2026-03/2026-03-20_contract_scheme_updates.md b/changelogs/2026-03/2026-03-20_contract_scheme_updates.md new file mode 100644 index 0000000..c9cb56d --- /dev/null +++ b/changelogs/2026-03/2026-03-20_contract_scheme_updates.md @@ -0,0 +1,115 @@ +# 接口变更记录 — 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>` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `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} — 删除方案 + +--- + +## 前端重点调整总结 + +| 页面 | 调整项 | +|------|--------| +| 合同方案新增/编辑表单 | "旅行社"去掉必填星号,允许不选 | +| 合同方案新增/编辑表单 | "合同模板"下拉根据选择的"合同平台"联动筛选,调用 `/admin/contract/templates?platform=xxx` | +| 合同方案新增/编辑表单 | 切换合同平台时清空已选的合同模板 |