docs: mp 端产品详情接口回显 agencyId+agencyName (wx/HL #1753)

changelogs/2026-05/06_fix_mp_product_detail_agency_resp.md

@@ -0,0 +1,83 @@
+# fix(mp-product): /mp/product/{id} 详情接口回显 agencyId + agencyName
+
+**日期**: 2026-05-06 20:30
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1753 (已 merge dev,等测试服部署后 round-trip)
+**关联工单**: wx/HL #1748
+
+---
+
+## 一、用户反馈
+
+小程序产品详情页希望展示「出团旅行社」公司信息,但 `GET /mp/product/{id}` 返回的 50+ 字段里没有任何 agency/公司字段,前端无法展示。
+
+## 二、根因
+
+PR #1707 已在 `product` 表加 `agency_id` 字段 (NOT NULL,Flyway 回填 hulai 主体)。
+PR #1722 给 admin 详情接口补了 agencyId/agencyName,但 **mp 端 `MpProductDetailAssembler` 完全未补 agency 字段**;快照路径 `MpProductSnapshotService` 同样未处理。
+
+## 三、修复
+
+| 文件 | 改动 |
+|---|---|
+| `MpProductDetailRespVO` | 顶层加 `agencyId: Long` + `agencyName: String` |
+| `MpProductDetailAssembler` (实时路径) | 注入 `AgencyFeignClient`,显式 `setAgencyId(product.getAgencyId())` + Feign 调 order-v2 拿 `agencyName` (异常 catch 不阻断主流程) |
+| `MpProductSnapshotService.fillAgency` (快照路径) | `productHelperService.selectById(productId).getAgencyId()` + Feign 取 agencyName。**agency 不冻结进快照**,公司主体保持当前真值 (与 refundPolicy 同样语义) |
+| 单测 | 新增 5 例覆盖实时/快照 + Feign 成功/异常/agencyId=null 各种分支 |
+
+## 四、API 改动
+
+### 4.1 实时路径 `GET /mp/product/{id}`
+
+```json
+{
+  "code": 200,
+  "data": {
+    "productId": 2043595351268519937,
+    "name": "草原环线 5 日",
+    "agencyId": 2051922156798779394,                // ← 新增
+    "agencyName": "内蒙古呼籁国际旅行社有限公司",      // ← 新增, Feign 拿中文
+    "productType": "CORE",
+    ...
+  }
+}
+```
+
+### 4.2 快照路径 `GET /mp/product/{id}?orderId=X`
+
+同样返 `agencyId` + `agencyName`,但**不冻结进订单产品快照** (订单内的产品 snapshot JSON 仍不含这俩字段),公司主体永远取实时值。
+
+## 五、前端建议
+
+详情页直接读 `data.agencyName` 展示「出团旅行社: 内蒙古呼籁国际旅行社有限公司」即可。
+若想做点击跳转旅行社详情页,可用 `data.agencyId` 拼接路径。
+
+Feign 极少数失败场景下 `agencyName` 可能为 null,前端建议加 placeholder 兜底:
+
+```vue
+<span>出团旅行社: {{ detail.agencyName || '呼籁旅行' }}</span>
+```
+
+## 六、测试服 round-trip 验证 (待 dev 部署后补)
+
+部署完成后调用:
+
+```bash
+curl -sk "https://api.test.1814.love:9443/mp/product/2043595351268519937" \
+  | python -c "
+import json,sys
+d = json.load(sys.stdin)['data']
+print(f'agencyId   = {d.get(\"agencyId\")}')
+print(f'agencyName = {d.get(\"agencyName\")}')
+"
+# 预期: agencyId 非 null Long, agencyName 非 null 中文
+```
+
+## 七、关联 PR
+
+- PR #1722 (admin 端产品详情 agency 回显, 已合并)
+- **PR #1753 (本 PR, mp 端产品详情 agency 回显)**
+
+---
+
+cc @mmg