# 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`),写公司或资质时缓存自动失效
