diff --git a/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md b/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md new file mode 100644 index 0000000..d0c3ddc --- /dev/null +++ b/changelogs/2026-05/06_feat_agency_qualification_type_and_contract_platform.md @@ -0,0 +1,151 @@ +# 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