From 2ae056d5def8f1412922482ace7f14f2b0440e4f Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 6 May 2026 19:17:55 +0800 Subject: [PATCH] =?UTF-8?q?feat(mp-agency):=20/mp/agency/primary=20?= =?UTF-8?q?=E5=8A=A0=20qualifications[]=20=E6=9B=BF=E4=BB=A3=20BUG2=20?= =?UTF-8?q?=E8=AF=AF=E8=B0=83=20(#1738)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../06_feat_mp_agency_qualifications.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 changelogs/2026-05/06_feat_mp_agency_qualifications.md diff --git a/changelogs/2026-05/06_feat_mp_agency_qualifications.md b/changelogs/2026-05/06_feat_mp_agency_qualifications.md new file mode 100644 index 0000000..a9aa753 --- /dev/null +++ b/changelogs/2026-05/06_feat_mp_agency_qualifications.md @@ -0,0 +1,106 @@ +# 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` 字段,前端从这里取资质。**不要再调** `/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 时直接 │ +│ │ PDF icon │ ← fileType=PDF 时 PDF 占位 + 点击新窗口打开 │ +│ └──────────┘ │ +│ 名称: 呼籁国际营业执照 │ +│ 有效期至 2030-01-01 (or 长期有效) │ +└─────────────────────────────────┘ +``` + +### 点击预览 +- IMAGE → 调微信小程序的 `wx.previewImage`(传 fileUrl) +- PDF → `wx.downloadFile` + `wx.openDocument`(或 H5 ``) + +### 注意 +- `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 一起)