合同方案弹窗「旅行社」下拉新增按合同平台过滤接口

服务: hl-order-service-v2 (8094) PR: #1922 主体 + #1923 空字符串兜底修复 Issue: #1921 日期: 2026-05-09 影响范围: admin「合同管理 → 合同方案 → 新增/编辑合同方案」弹窗的「旅行社」下拉

一、背景

弹窗里点旅行社下拉显示「无数据」。根因:之前没有「按合同平台过滤启用旅行社」的下拉接口,前端不知道调哪个。现有 /admin/travel-agency/enabled 和 /enabled-for-product 都不带平台维度,直接调出来不分平台,与"按合同平台配置"的业务语义不匹配。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	按合同平台过滤启用旅行社	GET	`/admin/travel-agency/enabled-by-platform`	新增	给「新增合同方案」弹窗下拉用

三、接口详情

`GET /admin/travel-agency/enabled-by-platform`

Headers: 标准 admin token

Query 参数:

字段	类型	必填	说明
`contractPlatform`	String	✅	合同平台 code,取值: `12301` / `TENCENT_ESIGN` / `LOCAL`(LOCAL 暂未在前端用)

响应 Result<List<AgencySimpleRespVO>>:

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {
      "agencyId": "2051922156798779394",
      "code": "hulai",
      "agencyName": "内蒙古呼籁国际旅行社有限公司",
      "isPrimary": 0,
      "sortOrder": 100
    }
  ]
}

字段说明(与现有 /enabled 接口同 VO,字段不变):

字段	类型	说明
`agencyId`	Long(序列化为 String 防 JS 精度丢失)	旅行社 ID,提交合同方案时作为关联标识
`code`	String	旅行社编码,合同方案 `agencyCode` 字段对应它
`agencyName`	String	旅行社全称(下拉 label)
`isPrimary`	Integer	是否主体公司(1=是, 0=否),前端可视情况打标
`sortOrder`	Integer	排序号

过滤逻辑:

status = 'ENABLED' (只返启用)
supported_platforms IS NOT NULL AND supported_platforms <> '' (跳过脏数据空字符串行,见下方 PR #1923 上下文)
JSON_CONTAINS(supported_platforms, JSON_QUOTE(?)) (数组里包含选定平台)

排序: is_primary DESC (主体公司优先) + agency_id ASC (稳定排序)

错误码:

HTTP code	业务 code	触发
200	200	正常返列表(空 list 表示该平台暂无支持的旅行社)
200	400	`contractPlatform` 缺参 → `enabledByPlatform.contractPlatform: 合同平台不能为空`

四、前端改造点(mmg)

文件: hl-ui/src/views/contract/scheme/...(合同方案配置弹窗)

旅行社下拉接口: 改调 GET /admin/travel-agency/enabled-by-platform
入参: 把当前选中的 contractPlatform(radio: 12301 / 腾讯电子签 → TENCENT_ESIGN)作为 query param 传入
联动: 切换合同平台 radio 时重新拉取旅行社列表(可触发 watch contractPlatform 重新调接口)
空态: 接口返 data: [] 时显示「该合同平台暂无支持的旅行社,请联系管理员配置」之类的友好提示
不再用 /admin/travel-agency/enabled 这个老接口(那是不带平台过滤的全量,本场景不合适)
placeholder「不填则根据支付商户号自动匹配」可保留(业务语义没变,只是下拉本身要先有数据可选)

五、测试服 API 验证(2026-05-09 19:00)

Case	实测
`?contractPlatform=12301`	✅ 200, 4 条旅行社(hulai / qianshou / hulai-wenlu / bohua-test)
`?contractPlatform=TENCENT_ESIGN`	✅ 200, `data: []`(测试库无 agency 支持腾讯电子签)
`?contractPlatform=` (空)	✅ code=400, message="enabledByPlatform.contractPlatform: 合同平台不能为空"

测试库 5 条 ENABLED 旅行社 supported_platforms 现状:

["12301"] × 4 (hulai / qianshou / hulai-wenlu / bohua-test)
"" (空字符串) × 1 (kj) — 已被 isNotNull + ne('') 过滤跳过

六、衍生 PR (空字符串兜底)

PR #1922 主体合并后首测发现 JSON_CONTAINS 解析空字符串报 Data truncation: Invalid JSON text in argument 1 to function json_contains: "The document is empty.",整个查询 500。根因测试库 1 行 supported_platforms = '' 脏数据。PR #1923 在 mapper 加 isNotNull + ne('') 前置过滤,跳过脏行。

后续治理建议(不在本 PR 范围):所有旅行社记录的 supported_platforms 应统一存 [] 或合法 JSON 数组,避免空字符串脏数据(可在 admin 端「旅行社管理」编辑保存时校验,或加迁移 SQL UPDATE travel_agency SET supported_platforms = '[]' WHERE supported_platforms = '' OR supported_platforms IS NULL)。

七、不在本 PR 范围

现有 /admin/travel-agency/enabled 和 /enabled-for-product 不动(其他场景在用)
旅行社管理页面新增/编辑时 supported_platforms 字段 UI(如果还没有,需另起 PR)
合同方案保存时如何用 agencyCode 关联到旅行社(现有逻辑不动)
测试库脏数据治理(可后续加 V*.sql 统一)

八、相关 PR / 工单

PR / Issue	说明
#1921	工单
#1922	主体 PR
#1923	空字符串兜底修复

联系人: wx

5.3 KiB 原始文件 Blame 文件历史 Unescape Escape