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