diff --git a/changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md b/changelogs/2026-05/06_feat_mp_merchant_qualifications_alias_landed.md new file mode 100644 index 0000000..2497adb --- /dev/null +++ b/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(前端改一行)