fix(admin): 合同方案弹窗旅行社下拉新增 GET /admin/travel-agency/enabled-by-platform (PR #1922 + #1923, Closes #1921)

changelogs/2026-05/09_fix_admin_contract-scheme-agency-by-platform.md

@@ -0,0 +1,136 @@
+# 合同方案弹窗「旅行社」下拉新增按合同平台过滤接口
+
+> **服务**: 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>>`:
+
+```json
+{
+  "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/...`(合同方案配置弹窗)
+
+1. **旅行社下拉接口**: 改调 `GET /admin/travel-agency/enabled-by-platform`
+2. **入参**: 把当前选中的 `contractPlatform`(radio: 12301 / 腾讯电子签 → `TENCENT_ESIGN`)作为 query param 传入
+3. **联动**: 切换合同平台 radio 时**重新拉取**旅行社列表(可触发 watch contractPlatform 重新调接口)
+4. **空态**: 接口返 `data: []` 时显示「该合同平台暂无支持的旅行社,请联系管理员配置」之类的友好提示
+5. **不再用** `/admin/travel-agency/enabled` 这个老接口(那是不带平台过滤的全量,本场景不合适)
+6. 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