feat(mp): /mp/common/merchant-qualifications alias 已落地, 前端无需改 (#1745)

changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md

@@ -0,0 +1,86 @@
+# feat(mp-common): /mp/common/merchant-qualifications 已落地兼容 alias (前端无需改)
+
+**日期**: 2026-05-06 21:10
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1745 (已 merge dev + 测试服部署 + round-trip 字段结构 100% 对齐)
+**关联工单**: wx/HL #1732
+**接续**: changelog `06_feat_mp_agency_qualifications.md`(BUG3)
+
+---
+
+## 一、好消息
+
+之前那条 `06_feat_mp_agency_qualifications.md` 提到「前端可以从 `/mp/agency/primary` 取 qualifications」。**现在 BUG4 也做完了**:
+
+后端在 `/mp/common/merchant-qualifications` 也加了同样的接口(alias)。**已发版小程序代码无需改任何东西**,继续调原 url 就能直接拿到主体公司 + 资质附件,字段结构与 `/mp/agency/primary` 100% 一致。
+
+## 二、测试服 round-trip 实测对比
+
+```
+=== /mp/agency/primary ===
+keys: agencyAddress, agencyName, businessLicenseNumber, code,
+      complaintPhone, licenseNumber, qualifications
+qualifications length: 2
+
+=== /mp/common/merchant-qualifications ===
+keys: agencyAddress, agencyName, businessLicenseNumber, code,
+      complaintPhone, licenseNumber, qualifications
+qualifications length: 2
+
+字段差异: 无
+qual[0].name 一致: 呼籁国际营业执照
+qual[0].fileUrl 一致: ✓
+```
+
+## 三、给前端的最终方案
+
+| 场景 | URL | 备注 |
+|---|---|---|
+| **已发版小程序** | `GET /mp/common/merchant-qualifications` | **不动**,后端 alias 兼容 |
+| 新前端版本(可选) | `GET /mp/agency/primary` | 推荐,少一跳 mp-service → order-v2,响应略快 |
+
+**两个 URL 字段结构完全一样**,任选其一,前端代码完全相同的解析逻辑。
+
+## 四、响应字段(参考 BUG3 changelog)
+
+```json
+{
+  "code": 200, "message": "成功",
+  "data": {
+    "code": "hulai",
+    "agencyName": "内蒙古呼籁国际旅行社有限公司",
+    "licenseNumber": "L-NMG-100953",
+    "businessLicenseNumber": "91150702MACYFE851R",
+    "complaintPhone": "12301",
+    "agencyAddress": "...",
+    "qualifications": [
+      {
+        "name": "呼籁国际营业执照",
+        "qualificationType": "BUSINESS_LICENSE",
+        "qualificationTypeLabel": "营业执照",
+        "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...",
+        "fileType": "IMAGE",
+        "fileTypeLabel": "图片",
+        "issueDate": null,
+        "expireDate": null
+      }
+    ]
+  }
+}
+```
+
+`qualifications: []` 时不要展示资质区块,直接隐藏即可(后端按 sortOrder 升序返回)。
+
+## 五、合 main 计划
+
+按用户指令,**本 PR 暂不合 main**。所以正式环境短期内仍是旧行为(`/mp/common/merchant-qualifications` 返"接口不存在"+ `/mp/agency/primary` 返不带 qualifications)。
+
+新需求积累几条后再统一发 release。前端可以先在测试服联调:
+- 测试服 `https://api.test.1814.love:9443/mp/common/merchant-qualifications` 已可用 ✓
+
+## 六、其他相关 BUG 一并通报
+
+同期还修了几条:
+- `06_fix_insurance_recharge_pay_url.md` — 保险充值返支付链接(已上 prod ✓)
+- `06_feat_mp_agency_qualifications.md` — `/mp/agency/primary` 加 qualifications(本 changelog 接续)
+- `06_fix_admin_set_primary_method_post_to_put.md` — admin 切换主体接口请用 PUT 不是 POST(前端改一行)