# feat(mp-agency): /mp/agency/primary 新增公开资质附件列表 (替代 BUG2 误调)

**日期**: 2026-05-06 19:50
**通知对象**: @mmg (前端)
**关联 PR**: wx/HL #1738 (已 merge dev + 测试服部署 + round-trip ✓)
**关联工单**: wx/HL #1732
**取代**: changelog `06_diag_mp_merchant_qualifications_not_found.md`(那个不需要 mmg 回复了)

---

## 一、用户原本反馈

`/mp/common/merchant-qualifications` 接口不存在 + `/mp/agency/primary` 应返回附件。

## 二、后端实现

后端在 `/mp/agency/primary` 加了 `qualifications: List<MpAgencyQualificationVO>` 字段,前端从这里取资质。**不要再调** `/mp/common/merchant-qualifications`(本来就不存在)。

## 三、API 改动

**接口路径不变**:`GET /mp/agency/primary`(无需 token,公开接口)

**响应新增 `data.qualifications` 字段**(测试服 round-trip 实测):

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "code": "hulai",
    "agencyName": "内蒙古呼籁国际旅行社有限公司",
    "licenseNumber": "L-NMG-100953",
    "businessLicenseNumber": "91150702MACYFE851R",
    "complaintPhone": "12301",
    "agencyAddress": "内蒙古自治区呼伦贝尔市海拉尔区奋斗镇学府路煤校3号楼211号",
    "qualifications": [
      {
        "name": "呼籁国际营业执照",
        "qualificationType": "BUSINESS_LICENSE",
        "qualificationTypeLabel": "营业执照",
        "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/rich-text/2026/05/06/ca98ae8cbd98ca9b3756f006b1ff7158.jpg",
        "fileType": "IMAGE",
        "fileTypeLabel": "图片",
        "issueDate": null,
        "expireDate": null
      }
    ]
  },
  "success": true
}
```

## 四、`MpAgencyQualificationVO` 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `name` | string | 资质名称(如 "呼籁国际营业执照") |
| `qualificationType` | string | 类型常量,字典 `agency_qualification_type` |
| `qualificationTypeLabel` | string | 类型中文(营业执照 / 旅行社业务经营许可证 / 增值电信业务经营许可证) |
| `fileUrl` | string | 文件 URL(目前透传永久 url,后续切 30min OSS 临时签名) |
| `fileType` | string | 文件类型常量(PDF / IMAGE / OTHER) |
| `fileTypeLabel` | string | 中文(PDF / 图片 / 其他) |
| `issueDate` | string | 颁发日期 yyyy-MM-dd,可空 |
| `expireDate` | string | 过期日期 yyyy-MM-dd,**null = 长期有效** |

**敏感字段不暴露**:`qualificationId / agencyId / sortOrder / remark / createTime / updateTime`(内部审计字段不返 mp)。

## 五、前端处理建议

### 列表渲染
- 后端已按 `sortOrder` 升序返回,前端**直接遍历不要重排**
- 空列表 `[]` 不要显示"暂无资质"区块,直接隐藏即可
- 长度 1 条单卡片;长度 2+ 横向滑动或网格

### 卡片 UI
```
┌─────────────────────────────────┐
│  [营业执照]  ←qualificationTypeLabel │
│  ┌──────────┐                    │
│  │ <图片预览> │  ← fileType=IMAGE 时直接 <img src=fileUrl> │
│  │  PDF icon  │  ← fileType=PDF  时 PDF 占位 + 点击新窗口打开 │
│  └──────────┘                    │
│  名称: 呼籁国际营业执照            │
│  有效期至 2030-01-01 (or 长期有效) │
└─────────────────────────────────┘
```

### 点击预览
- IMAGE → 调微信小程序的 `wx.previewImage`(传 fileUrl)
- PDF → `wx.downloadFile` + `wx.openDocument`(或 H5 `<a target=_blank>`)

### 注意
- `fileUrl` **目前是永久公开 url**(不是 30min 临时签名),后续 OSS STS 工具就绪后会切签名 url 有时效,**前端不要长期缓存**(过期重新请求接口)
- expireDate=null → 显示"长期有效",不要显示"null"
- 缩略图建议 OSS 图片处理参数 `?x-oss-process=image/resize,w_400` 减带宽(测试服已是 OSS,可直接拼)

## 六、后端测试

- 单测 4 个新增 case 全绿 (mp Controller 2 + mp Service 2)
- 测试服 round-trip:`GET https://api.test.1814.love:9443/mp/agency/primary` 实测返 `qualifications[1]`,字段对齐
- 内部字段泄漏检查:0 个(qualificationId/agencyId/sortOrder/remark/createTime/updateTime 全屏蔽)

## 七、部署计划

- 测试服已部 (deploy task `51b55da8` success)
- 正式环境:等 release PR 合 main 后通知运维部署(本次和 PR #1737 一起)
