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 实测):

{
  "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 一起)

4.4 KiB 原始文件 Blame 文件历史