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)

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

3.2 KiB 原始文件 Blame 文件历史