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

> **服务**: 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