feat(mp-agency): /mp/agency/primary 加 qualifications[] 替代 BUG2 误调 (#1738)

2026-05-06 19:17:55 +08:00 · 2026-05-06 19:17:55 +08:00 · 2ae056d5de
--- a/changelogs/2026-05/06_feat_mp_agency_qualifications.md
+++ b/changelogs/2026-05/06_feat_mp_agency_qualifications.md
@ -0,0 +1,106 @@
+# feat(mp-agency): /mp/agency/primary 新增公开资质附件列表 (替代 BUG2 误调)
+
+**日期**: 2026-05-06 19:50
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1738 (已 merge dev + 测试服部署 + round-trip ✓)
+**关联工单**: wx/HL #1732
+**取代**: changelog `06_diag_mp_merchant_qualifications_not_found.md`(那个不需要 mmg 回复了)
+
+---
+
+## 一、用户原本反馈
+
+`/mp/common/merchant-qualifications` 接口不存在 + `/mp/agency/primary` 应返回附件。
+
+## 二、后端实现
+
+后端在 `/mp/agency/primary` 加了 `qualifications: List<MpAgencyQualificationVO>` 字段,前端从这里取资质。**不要再调** `/mp/common/merchant-qualifications`(本来就不存在)。
+
+## 三、API 改动
+
+**接口路径不变**:`GET /mp/agency/primary`(无需 token,公开接口)
+
+**响应新增 `data.qualifications` 字段**(测试服 round-trip 实测):
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "code": "hulai",
+    "agencyName": "内蒙古呼籁国际旅行社有限公司",
+    "licenseNumber": "L-NMG-100953",
+    "businessLicenseNumber": "91150702MACYFE851R",
+    "complaintPhone": "12301",
+    "agencyAddress": "内蒙古自治区呼伦贝尔市海拉尔区奋斗镇学府路煤校3号楼211号",
+    "qualifications": [
+      {
+        "name": "呼籁国际营业执照",
+        "qualificationType": "BUSINESS_LICENSE",
+        "qualificationTypeLabel": "营业执照",
+        "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/rich-text/2026/05/06/ca98ae8cbd98ca9b3756f006b1ff7158.jpg",
+        "fileType": "IMAGE",
+        "fileTypeLabel": "图片",
+        "issueDate": null,
+        "expireDate": null
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+## 四、`MpAgencyQualificationVO` 字段说明
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `name` | string | 资质名称(如 "呼籁国际营业执照") |
+| `qualificationType` | string | 类型常量,字典 `agency_qualification_type` |
+| `qualificationTypeLabel` | string | 类型中文(营业执照 / 旅行社业务经营许可证 / 增值电信业务经营许可证) |
+| `fileUrl` | string | 文件 URL(目前透传永久 url,后续切 30min OSS 临时签名) |
+| `fileType` | string | 文件类型常量(PDF / IMAGE / OTHER) |
+| `fileTypeLabel` | string | 中文(PDF / 图片 / 其他) |
+| `issueDate` | string | 颁发日期 yyyy-MM-dd,可空 |
+| `expireDate` | string | 过期日期 yyyy-MM-dd,**null = 长期有效** |
+
+**敏感字段不暴露**:`qualificationId / agencyId / sortOrder / remark / createTime / updateTime`(内部审计字段不返 mp)。
+
+## 五、前端处理建议
+
+### 列表渲染
+- 后端已按 `sortOrder` 升序返回,前端**直接遍历不要重排**
+- 空列表 `[]` 不要显示"暂无资质"区块,直接隐藏即可
+- 长度 1 条单卡片;长度 2+ 横向滑动或网格
+
+### 卡片 UI
+```
+┌─────────────────────────────────┐
+│  [营业执照]  ←qualificationTypeLabel │
+│  ┌──────────┐                    │
+│  │ <图片预览> │  ← fileType=IMAGE 时直接 <img src=fileUrl> │
+│  │  PDF icon  │  ← fileType=PDF  时 PDF 占位 + 点击新窗口打开 │
+│  └──────────┘                    │
+│  名称: 呼籁国际营业执照            │
+│  有效期至 2030-01-01 (or 长期有效) │
+└─────────────────────────────────┘
+```
+
+### 点击预览
+- IMAGE → 调微信小程序的 `wx.previewImage`(传 fileUrl)
+- PDF → `wx.downloadFile` + `wx.openDocument`(或 H5 `<a target=_blank>`)
+
+### 注意
+- `fileUrl` **目前是永久公开 url**(不是 30min 临时签名),后续 OSS STS 工具就绪后会切签名 url 有时效,**前端不要长期缓存**(过期重新请求接口)
+- expireDate=null → 显示"长期有效",不要显示"null"
+- 缩略图建议 OSS 图片处理参数 `?x-oss-process=image/resize,w_400` 减带宽(测试服已是 OSS,可直接拼)
+
+## 六、后端测试
+
+- 单测 4 个新增 case 全绿 (mp Controller 2 + mp Service 2)
+- 测试服 round-trip:`GET https://api.test.1814.love:9443/mp/agency/primary` 实测返 `qualifications[1]`,字段对齐
+- 内部字段泄漏检查:0 个(qualificationId/agencyId/sortOrder/remark/createTime/updateTime 全屏蔽)
+
+## 七、部署计划
+
+- 测试服已部 (deploy task `51b55da8` success)
+- 正式环境:等 release PR 合 main 后通知运维部署(本次和 PR #1737 一起)