docs(2026-05-06): mp/review/report BFF 透传 (wx/HL #1757)

changelogs/2026-05/06_fix_mp_review_report_bff_passthrough.md

@@ -0,0 +1,75 @@
+# fix(mp-service): 补 BFF 端 POST /mp/review/report 透传
+
+**日期**: 2026-05-06 20:35
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1757 (已 merge dev,等测试服自动部署后 round-trip)
+**关联工单**: wx/HL #1755
+
+---
+
+## 一、用户反馈
+
+`POST https://api.test.1814.love:9443/mp/review/report` 返回:
+
+```json
+{"code":404,"message":"接口不存在: POST /mp/review/report"}
+```
+
+之前我已告知前端"举报评价接口可用",基于 `hl-order-service-v2` 的 `InternalMpReviewController#report` 已实现 + 字典 review_report_reason 已补回(PR #1739)的事实判断,**漏检 BFF 透传那一段**,实际接口未对外暴露。本次修复后真正可用,致歉。
+
+## 二、根因
+
+工单 #1662 Phase 2B 完成的范围只到 order-v2 内部端点 + Service + 字典 + 单测,**漏写 hl-mp-service 这层 BFF**:
+
+- `MpReviewController` 没暴露 `POST /mp/review/report`
+- `MpReviewFeignClient` 没对应 `report` 方法
+- `MpReviewFeignFallbackFactory` 没兜底实现
+
+→ 前端调测试服 endpoint, 网关路由到 mp-service, 没匹配 controller, 返 404 "接口不存在"。
+
+跟 PR #1754 (Closes #1752, `/mp/review/filter-tags` 网关白名单) 是同根因 —— Phase 2B BFF 收尾遗漏。
+
+## 三、修复
+
+`hl-mp-service` 模块加 4 处:
+
+1. 新建 `dto/MpReviewReportRequest.java` (BFF 入参 DTO, 字段与 order-v2 `ReviewReportReqVO` 一致)
+2. `MpReviewFeignClient.report(MpReviewReportRequest, X-User-Id)` 方法
+3. `MpReviewFeignFallbackFactory.report` 兜底实现
+4. `MpReviewController POST /report` 端点, 透传 userId 到 Feign
+
+## 四、API 字段
+
+`POST /mp/review/report` (需登录, 网关 JwtAuthFilter 默认拦截):
+
+| 字段 | 类型 | 必填 | 限制 | 说明 |
+|------|------|------|------|------|
+| `reviewId` | String(雪花 Long, 双向 String 防精度丢失) | ✅ | - | 评价 ID |
+| `reason` | String | ✅ | max 32 | 字典 `review_report_reason`: SPAM / INSULT / PORN / POLITICS / FAKE / LEAK_PRIVACY / OTHER |
+| `detail` | String | - | max 500 | 补充说明 |
+
+返回: `{"code":200,"message":"成功","data":null,"success":true}`
+
+幂等: 同一用户对同一评价重复举报触发 `uk_review_reporter` 唯一索引返业务错误(无需前端处理, BFF 不加 `@Idempotent`)。
+
+## 五、前端建议
+
+举报弹窗前端调用示例:
+
+```js
+http.post('/mp/review/report', {
+  reviewId: review.id,        // 字符串透传, 不要 Number(...)
+  reason: 'SPAM',             // 用字典 review_report_reason 的 dictValue
+  detail: userInputOrEmpty,   // 可选, max 500
+})
+```
+
+字典拉取走现有 `GET /mp/dict/review_report_reason`(已在 PR #1739 补回), 渲染下拉选项。
+
+## 六、验收(待测试服部署)
+
+- [ ] 真 mp token round-trip: `POST /mp/review/report` body `{"reviewId":"<真实评价ID>","reason":"SPAM","detail":"测试"}` 返 `{"code":200}`
+- [ ] 重复举报触发唯一索引返业务错误
+- [ ] 不带 token 调用返 401 (网关拦截)
+- [ ] 超长 reason(>32) / detail(>500) 返参数校验错误
+- [ ] 部署后 INFO 日志含 `submitted` 落库