diff --git a/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md b/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md new file mode 100644 index 0000000..f0c0889 --- /dev/null +++ b/changelogs/2026-05/06_feat_mp_agency_get_by_id_and_id_field.md @@ -0,0 +1,175 @@ +# mp-agency: 新增 GET /mp/agency/{id} + 全部 mp 公司接口补返 agencyId + +> **服务**: hl-order-service-v2 (端口 8084) + hl-mp-service (端口 8085) +> **PR**: #1761(GET /mp/agency/{id}) + #1763(VO/DTO 补 agencyId) +> **Issue**: #1759 + #1762 +> **日期**: 2026-05-06 +> **影响范围**: C 端公司公开信息所有接口(/mp/agency/primary、/mp/agency/{id}、/mp/common/merchant-qualifications) +> **@mmg** + +--- + +## 一、背景 + +PR #1748(2026-05-06)让 `/mp/product/{id}` 详情接口返出团旅行社公司 ID(`agencyId`/`agencyName`)。前端拿到 agencyId 后需查公司详细信息(营业执照号/统一社会信用代码/客服电话/地址/资质附件)用于产品详情页/合同页/客服联系页展示。 + +之前只有 `/mp/agency/primary` 一个接口,只能查主体公司,无法支持"按非主体公司 ID 查"。本次新增 `/mp/agency/{id}` 闭环。 + +同时发现 `/mp/common/merchant-qualifications` 列表只返 code 不返 agencyId,前端拿到列表后无法用 `/mp/agency/{id}` 闭环查详情;`/mp/agency/primary`、`/mp/agency/{id}` 自己也不返 agencyId 无法做 cache key。**根因**:`MpAgencyRespVO` 评审 PR #1732 时为不暴露主键剔除了 agencyId,但 PR #1748 已让 `/mp/product/{id}` 暴露 agencyId,这条防线已失效。统一让所有 mp 公司接口都带 agencyId。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 按公司ID查公开详情 | GET | `/mp/agency/{id}` | **新增** | 免登录,字段结构 = /primary | +| 2 | 主体公司公开详情 | GET | `/mp/agency/primary` | 响应字段新增 | + `agencyId` | +| 3 | 合作公司公开列表 | GET | `/mp/common/merchant-qualifications` | 响应字段新增 | 每家公司元素 + `agencyId` | + +--- + +## 三、接口详情 + +### 1. 按公司ID查公开详情 `GET /mp/agency/{id}`(新增) + +**VO**: `MpAgencyRespVO`(等同 `/primary`) + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 公司ID(来自 `/mp/product/{id}` 返的 `agencyId` 或 `/mp/common/merchant-qualifications` 列表元素 `agencyId`) | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| agencyId | Long(JSON 序列化为 String 防 JS 精度丢失) | 公司ID | +| code | String | 公司编码 | +| agencyName | String | 公司名称 | +| licenseNumber | String | 旅行社业务经营许可证号 | +| businessLicenseNumber | String | 统一社会信用代码 | +| complaintPhone | String | 客服电话 | +| agencyAddress | String | 公司地址 | +| visible | Integer | 是否在小程序展示(1=展示/0=隐藏) | +| qualifications | List | 公开资质列表 | + +#### 鉴权 + +- **免登录**(网关 `/mp/agency/**` 已配 JwtAuthFilter 白名单) + +#### 请求示例 + +``` +GET /mp/agency/2051985889785012226 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "agencyId": "2051985889785012226", + "code": "kj", + "agencyName": "内蒙古呼伦文化科技有限公司", + "licenseNumber": "", + "businessLicenseNumber": "91150702MAK1T8Q0XG", + "complaintPhone": "", + "agencyAddress": "", + "visible": 1, + "qualifications": [ + { + "name": "公司科技营业执照", + "qualificationType": "BUSINESS_LICENSE", + "qualificationTypeLabel": "营业执照", + "fileUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/...", + "fileType": "IMAGE", + "fileTypeLabel": "图片", + "issueDate": null, + "expireDate": null + } + ] + }, + "success": true +} +``` + +#### 错误响应 + +```json +{ "code": 594001, "message": "旅行社公司不存在(id=999999999999999999)", "success": false, "data": null } +``` + +```json +{ "code": 400, "message": "参数类型错误: id='abc'(需要 Long 类型)", "success": false, "data": null } +``` + +--- + +### 2. 主体公司公开详情 `GET /mp/agency/primary`(已存在,新增 agencyId 字段) + +响应结构完全等同新接口 `/mp/agency/{id}`,字段集相同;`agencyId` 为新增字段。 + +--- + +### 3. 合作公司公开列表 `GET /mp/common/merchant-qualifications`(已存在,新增 agencyId 字段) + +每个数组元素新增 `agencyId` + `visible` 字段(对齐 RespVO 字段集)。 + +```json +{ + "code": 200, + "data": [ + { + "agencyId": "2051985000000000001", + "code": "hulai", + "agencyName": "...", + "qualifications": [...] + } + ] +} +``` + +--- + +## 四、不影响范围 + +- **仅影响**: 上述 3 个 mp 公司接口(`/mp/agency/primary`、`/mp/agency/{id}`、`/mp/common/merchant-qualifications`)的响应结构(向前兼容: 只新增字段,不删不改) +- **零影响**: + - admin 端 agency 接口(`/admin/agency/**`)结构不变 + - 12301 凭据(appId/signKey)、支付配置(mchId/apiV3Key)依然不暴露给前端 + - 其他 mp 接口结构不变 + +--- + +## 五、测试环境已验证 + +``` +GET /mp/agency/primary → 200 + data.agencyId 非空 ✓ +GET /mp/agency/2051985889785012226 → 200 + data.agencyId == path id ✓ +GET /mp/agency/999999999999999999 → 200 + code:594001 AGENCY_NOT_FOUND ✓ +GET /mp/agency/abc → 200 + code:400 参数类型错 ✓ +``` + +`/mp/common/merchant-qualifications` 因 mp-service 端 `@MpCache` 30 min Redis 缓存,部署完成后**新结构(带 agencyId)在缓存自然过期后(< 30 min)自动生效**,无需重启;前端可在 30 min 后接入或直接以 `/mp/agency/primary` + `/mp/agency/{id}` 闭环。 + +--- + +## 六、前端建议接入方式 + +1. 产品详情页:`/mp/product/{id}` 拿到 `agencyId` → `/mp/agency/{id}` 拉公司详情(显示出团旅行社营业执照、资质附件等) +2. 合同页/协议页落款:沿用 `/mp/agency/primary`(主体公司) +3. 关于我们/合作公司列表:`/mp/common/merchant-qualifications` 列表 → 点击进详情 `/mp/agency/{agencyId}` + +--- + +## 七、相关文档 + +- Issue #1759: https://git.1814.love:8443/wx/HL/issues/1759 +- Issue #1762: https://git.1814.love:8443/wx/HL/issues/1762 +- PR #1761: https://git.1814.love:8443/wx/HL/pulls/1761 +- PR #1763: https://git.1814.love:8443/wx/HL/pulls/1763 +- 上游 PR #1748: `/mp/product/{id}` 补返 agencyId