# feat(agency): 资质附件分类字段 + 合同平台字典

**日期**: 2026-05-06 16:18
**通知对象**: @mmg (前端)
**关联 PR**: wx/HL #1717 (已 merge dev + 测试服部署 + round-trip 验证通过)

---

## 一、用户需求

1. **资质附件上传需要分类字典** (营业执照 / 旅行社业务经营许可证 / 增值电信业务经营许可证)
2. **「支持平台」label 改为「支持合同平台」** + **字段值改为字典** (12301 / 腾讯电子签)

---

## 二、字典数据 (测试服已生效)

### 1. agency_qualification_type (资质分类) — 资质上传必传

| dictValue | dictLabel | sortOrder |
|-----------|-----------|-----------|
| `BUSINESS_LICENSE` | 营业执照 | 10 |
| `TRAVEL_AGENCY_LICENSE` | 旅行社业务经营许可证 | 20 |
| `VALUE_ADDED_TELECOM_LICENSE` | 增值电信业务经营许可证 | 30 |

### 2. agency_contract_platform (支持的合同平台) — 多选

| dictValue | dictLabel | sortOrder |
|-----------|-----------|-----------|
| `12301` | 12301 团队报送 | 10 |
| `TENCENT_ESIGN` | 腾讯电子签 | 20 |

字典查询接口:

```bash
curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_qualification_type" \
  -H "Authorization: Bearer $TOK"
# data: [{dictValue, dictLabel, sortOrder}, ...]

curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_contract_platform" \
  -H "Authorization: Bearer $TOK"
```

---

## 三、API 改动

### 1. 资质上传请求 / 响应

**`POST /admin/travel-agency/{agencyId}/qualification`** + **`PUT /admin/travel-agency/{agencyId}/qualification/{id}`**

`AgencyQualificationSaveReqVO` **新增必填字段**:

```json
{
  "name": "营业执照",
  "qualificationType": "BUSINESS_LICENSE",   // 必填, 字典 agency_qualification_type
  "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/agency/...",
  "fileType": "PDF",
  "issueDate": "2024-01-01",
  "expireDate": "2029-12-31",
  "sortOrder": 100,
  "remark": ""
}
```

**`GET /admin/travel-agency/{agencyId}/qualification`** 响应新增字段:

```json
{
  "qualificationId": 2051940000000000,
  "agencyId": 2051922156798779394,
  "name": "营业执照",
  "qualificationType": "BUSINESS_LICENSE",
  "qualificationTypeLabel": "营业执照",          // ← 新增, 中文 (供列表展示)
  "fileUrl": "...",
  "fileType": "PDF",
  "fileTypeLabel": "PDF",
  "issueDate": "2024-01-01",
  "expireDate": "2029-12-31",
  "sortOrder": 100,
  "remark": ""
}
```

### 2. 公司主表「支持的合同平台」字段

**字段名**: `supportedPlatforms` (后端字段名不变, 前端 label 必改)

| 现状 | 改为 |
|---|---|
| 前端 label = 「支持平台」 | 「**支持合同平台**」 |
| 字段值是裸字符串 | 拉字典 `agency_contract_platform` 做多选下拉 |

后端字段已是 JSON 数组字符串 (例 `["12301","TENCENT_ESIGN"]`), 前端 form 多选组件直接绑定即可.

---

## 四、前端改动建议

```bash
# hl-ui 前端项目根:
# 1. 资质上传 form 加分类下拉 (拉 /admin/dict/data/agency_qualification_type)
# 2. 资质列表展示用 qualificationTypeLabel (后端已返回中文)
# 3. 公司编辑页:
#    - 「支持平台」label 改为「支持合同平台」
#    - 多选下拉拉 /admin/dict/data/agency_contract_platform
```

---

## 五、测试服 round-trip 验证 (2026-05-06 16:18)

```bash
TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin@123456"}' \
  | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])")

# 资质分类字典
curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_qualification_type" \
  -H "Authorization: Bearer $TOK"
# {"code":200,"data":[
#   {"dictValue":"BUSINESS_LICENSE","dictLabel":"营业执照","sortOrder":10},
#   {"dictValue":"TRAVEL_AGENCY_LICENSE","dictLabel":"旅行社业务经营许可证","sortOrder":20},
#   {"dictValue":"VALUE_ADDED_TELECOM_LICENSE","dictLabel":"增值电信业务经营许可证","sortOrder":30}
# ]}

# 合同平台字典
curl -sk "https://api.test.1814.love:9443/admin/dict/data/agency_contract_platform" \
  -H "Authorization: Bearer $TOK"
# {"code":200,"data":[
#   {"dictValue":"12301","dictLabel":"12301 团队报送","sortOrder":10},
#   {"dictValue":"TENCENT_ESIGN","dictLabel":"腾讯电子签","sortOrder":20}
# ]}
```

---

## 六、后续 PR (本 changelog 不含, 等下一个独立 changelog)

下一个 PR 会同步 nacos 完整数据到 DB:
- `team-report-app-id` / `team-report-sign-key` (UI 「团队报送 AppId/SignKey」当前显示 `-`)
- `supportedPlatforms` 默认值 (UI 当前显示 `[]`)
- `payment.api-v3-key` / `mch-serial-no` / `public-key-id` (UI 「未命名 mchId 1106110439 AppId: -」 当前缺加密字段)

实施后 UI 字段全部填满, 不再显示 `-`.

---

cc @mmg
