hl-api-changelog/changelogs/2026-03/2026-03-20_contract_scheme_updates.md

接口变更记录 — 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 字段。

// 以下两种写法等价：
{ "contractTemplateCode": "A00001", ... }
{ "templateCode": "A00001", ... }

前端使用方式

1. 模板下拉绑定：用 templateCode 作为下拉的 v-model 绑定值
2. 编辑回显：方案详情返回的 templateCode 可直接匹配模板列表的 templateCode
3. 模板名称显示：列表页可直接用 contractTemplateName 显示模板名称，无需额外查询
4. 旅行社名称显示：列表页可用 agencyName 显示旅行社名称

完整响应示例

{
  "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 直接显示名称