137 行
5.3 KiB
Markdown
137 行
5.3 KiB
Markdown
# 合同方案弹窗「旅行社」下拉新增按合同平台过滤接口
|
||
|
||
> **服务**: 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
|