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

changelogs/2026-05/06_diag_mp_merchant_qualifications_not_found.md

@@ -0,0 +1,68 @@
+# 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` 即可,不需要后端改动。