hl-api-changelog/changelogs/2026-05/06_diag_mp_merchant_qualifications_not_found.md

diag(mp): /mp/common/merchant-qualifications 接口不存在 — 需 mmg 确认意图

日期: 2026-05-06 19:30 通知对象: @mmg (前端) 关联 BUG 反馈: 用户报告 "/mp/common/merchant-qualifications 接口不存在"

---

一、调研结论

后端确认:/mp/common/merchant-qualifications 从未实现过,也无任何接近名称的同义接口。

排查点	结果
MpCommonController 现有端点	/config / /faq / /feedback / /agreement/{type} / /agreement/list / /contact 仅 6 个
MpAgencyController 端点	仅 /mp/agency/primary
Admin 资质接口	/admin/travel-agency/{agencyId}/qualification (admin 端 CRUD)
设计文档 / 最近 7 天 PR	docs/requirements/ 无"商户资质 / merchant qualifications"需求,git log 无相关
hl-ui repo 全量 grep	零引用(不在管理后台代码里)

二、可能的来源

调用源不在 hl-ui (Vue admin) 里,推测可能:

1. 小程序原生代码(wx/miniapp 代码不在 hl-ui repo,后端无法溯源调用方)
2. 前端在写新需求,本地未 push
3. 前端误调 (路径拼写或语义错)

三、语义澄清

• 项目里 merchant ≠ agency
  • merchant = 微信支付商户号(merchantId / mchId,paymentInfo 表)
  • agency = 旅行社公司(travel_agency 表 + agency_qualification 表存营业执照/法人证件等资质)
• 资质数据存在 agency_qualification 表,挂在 agency 维度,不是 merchant
• 想展示"商家资质"应该是 agency qualifications,不是 merchant qualifications

四、需要 mmg 确认

请在群里回复:

1. 这个调用是从哪来? (hl-ui? 小程序? 路径或 API 文件位置?)
2. 想展示什么内容?
   • (a) 旅行社营业执照、法人证、许可证等(agency qualifications)?
   • (b) 微信支付商户主体信息(merchant 主体)?
   • (c) 其他(品牌、合作伙伴…)?
3. 页面位置 — 在哪个页面/弹窗展示?

五、后端可提供的备选方案

确认意图后,后端可按以下任一路径实施:

方案 A: 用现有 /mp/agency/primary(零成本)

返回主体公司公开字段(licenseNumber / businessLicenseNumber / 公司名 / logo 等),如果只要一两个字段足够展示就用这个。

方案 B: 新增 GET /mp/agency/qualifications(推荐)

• 路径 /mp/agency/qualifications (语义对齐,不是 /mp/common/,因为这是 agency 维度的资质)
• 返回 agency_qualification 表里所有 type=主体类资质(营业执照、法人证件、其他经营许可证)
• 字段:type / typeLabel / fileUrl / issuedDate / expiryDate / status
• 复用 admin 端 TravelAgencyQualificationServiceImpl 的查询逻辑,加 mp 过滤(只暴露已审核 + 未过期)
• 估时:0.5 天(controller + VO + 单测)

方案 C: 新增 GET /mp/common/merchant-qualifications(不推荐)

仅当确实是支付商户主体维度(payment_info 表)的资质才走这个,但当前业务场景不存在这种需求 — 项目里 merchant 是支付层概念,用户面不感知。

六、建议结论

优先方案 B(语义清晰、可扩展)。如果确认想要,请回复任意确认信息或提供需求描述,我会建后端工单 + 派 /@dev 实施 + 测试 + 部署。

如果调用是误造/路径笔误,前端改成 /mp/agency/primary 即可,不需要后端改动。