# 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(前端改一行)