fix(mp-common): merchant-qualifications 改返非主体列表+附件 (PR #1751 修正 #1745)

changelogs/2026-05/06_fix_mp_merchant_qualifications_returns_non_primary_list.md

@@ -0,0 +1,116 @@
+# fix(mp-common): /mp/common/merchant-qualifications 改返「非主体公司列表+附件」(响应 shape 由 object → array)
+
+**日期**: 2026-05-06 20:25
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1751 (已 merge dev + 测试服部署 + round-trip 验收通过)
+**关联工单**: wx/HL #1746
+**接续/修正**: changelog `06_feat_mp_merchant_qualifications_alias_landed.md` (PR #1745 实现错位)
+
+---
+
+## 一、变更概要
+
+`/mp/common/merchant-qualifications` 这个接口的语义和返回结构**全部改了**,**前端逻辑必须配合改**。
+
+之前 PR #1745 把它做成 `/mp/agency/primary` 的 alias(返主体单对象)。但用户(产品)的真实意图是:
+
+> "返回除了主体之外的全部公司,包括资质附件"
+
+所以 PR #1751 把端点正名:
+
+| | 旧行为 (PR #1745, 已废) | 新行为 (PR #1751, 当前) |
+|---|---|---|
+| 数据范围 | 主体单家(hulai) | **除主体外的全部启用公司(N 家)** |
+| 响应 shape | `Result<MpAgencyDTO>` (data 是 object) | `Result<List<MpAgencyDTO>>` (data 是 **array**) |
+| 与 `/mp/agency/primary` 关系 | 完全等同(alias) | **互补**:primary 取主体,common 取其它 |
+
+## 二、新响应结构(测试服真实数据)
+
+```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
+        },
+        { ...第二张资质... }
+      ]
+    },
+    {
+      "code": "qianshou",
+      "agencyName": "内蒙古呼籁山河国际旅行社有限公司",
+      "qualifications": [ ...2 张... ]
+    },
+    {
+      "code": "hulai-wenlu",
+      "agencyName": "内蒙古呼籁文旅投资开发有限公司",
+      "qualifications": []
+    }
+  ]
+}
+```
+
+每个数组元素的字段与之前 `/mp/agency/primary` 单对象的字段**完全相同**,只是从 1 个变成 N 个。
+
+## 三、前端必须改的点
+
+### 1. 解析逻辑
+
+```js
+// 旧 (data 是 object)
+const company = res.data;
+this.agencyName = company.agencyName;
+this.qualifications = company.qualifications;
+
+// 新 (data 是数组)
+const companies = res.data;
+companies.forEach(c => {
+  // 每家公司一行/一卡片渲染
+});
+```
+
+### 2. UI 展示
+
+按你们的页面设计渲染:每家公司一个区块,含公司名/许可证号/营业执照号/投诉电话/地址 + qualifications 数组(资质附件)。`qualifications: []` 的公司不展示资质区块。
+
+### 3. 主体公司另外取
+
+如果页面同时要展示主体公司,继续调 `GET /mp/agency/primary`(返单对象,字段一致)。两个接口配合:
+
+| 接口 | 内容 |
+|---|---|
+| `GET /mp/agency/primary` | **主体公司**(单对象) |
+| `GET /mp/common/merchant-qualifications` | **非主体的合作公司**(数组,本 PR 修正) |
+
+## 四、兼容性说明
+
+PR #1745 今天刚合,前端代码假设是 list(因为 url 是复数 qualifications),所以这次改回 list **匹配前端真实诉求**。如果前端已经按 PR #1745 的 object shape 改过解析逻辑,需要回退到 list 解析。
+
+## 五、测试服已可用
+
+```
+GET https://api.test.1814.love:9443/mp/common/merchant-qualifications
+→ HTTP 200, data.length = 3 (hulai/qianshou/hulai-wenlu),不含主体 kj
+```
+
+合 main 暂不做(随后续 release 一起上)。
+
+## 六、其他
+
+- 工单 wx/HL #1746 已关闭
+- @MpCache deps 不变(`table:travel_agency` + `table:travel_agency_qualification`),写公司或资质时缓存自动失效