diff --git a/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md b/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md new file mode 100644 index 0000000..504881b --- /dev/null +++ b/changelogs/2026-05/06_frontend_notice_review_report_queue_pending.md @@ -0,0 +1,144 @@ +# frontend-notice: 评价举报处理页面 mmg 待接入(后端 #1668 已就绪 + #1755 BFF 已通) + +**通知对象**: @mmg +**关联**: [PR #1668](https://git.1814.love:8443/wx/HL/pulls/1668)(后端 admin API 5 个)+ [PR #1755](https://git.1814.love:8443/wx/HL/pulls/1755)(mp BFF 透传) +**问题反馈**: 2026-05-06 用户反馈"客户举报成功了应该在人工复审队列中展示 现在没有" + +--- + +## 背景 + +测试服客户从小程序点举报 `POST /mp/review/report` 已经能成功落库到 `review_report` 表 + `order_review.report_status`,但管理后台「内容安全 → 人工复审队列」页面查不到——因为那个页面后端只查 `traveler/user.audit_status`,**评价举报数据走的是另一个独立的 admin 队列**,前端 hl-ui 当前**没有对应的页面对接**。 + +PR #1668(Phase 2D, 已合 main 2026-05-05)后端把 5 个 admin 操作 API 都准备好了,前端漏建。本次需要 mmg 在 admin 后台「内容安全」一级菜单下新增二级菜单 **「评价举报处理」**,对接以下 5 个接口。 + +后端 0 改动。 + +--- + +## 推荐 UI 位置 + +「内容安全」一级菜单下,与「人工复审队列」并列,新增二级菜单 **「评价举报处理」**。 + +理由:评价举报跟出行人姓名、用户昵称、用户头像同属"内容安全"分类,但数据源/操作语义不同(隐藏/恢复 vs 通过/驳回),独立成页比硬塞进现有人工复审队列更清晰。 + +--- + +## 接口清单 + +### 1. 分页查询 + +``` +GET /admin/review/report-queue/page +``` + +**Query 参数**(`AdminReportQueuePageReqVO`): +- `page` (int, 默认 1) +- `pageSize` (int, 默认 20) +- `reportStatus` (String, 可选): `NORMAL` / `PENDING_REVIEW` / `HIDDEN` +- `keyword` (String, 可选): 评价内容/作者昵称模糊匹配 + +**响应**: `Result>` + +`AdminReportQueueItemRespVO` 字段: + +| 字段 | 类型 | 说明 | +|---|---|---| +| `reviewId` | Long (JsonFormat.STRING) | 评价 ID | +| `content` | String | 评价正文 | +| `userNickname` | String | 评价作者昵称 | +| `userId` | Long (JsonFormat.STRING) | 评价作者 ID | +| `productName` | String | 关联产品名 | +| `status` | String | 评价本身状态(PUBLISHED 等) | +| `reportCount` | Integer | 总举报数 | +| `reportStatus` | String | NORMAL / PENDING_REVIEW / HIDDEN | +| `hiddenAt` | LocalDateTime | 隐藏时间(null 未隐藏) | +| `hiddenReason` | String | 隐藏原因 | +| `createTime` | LocalDateTime | 评价创建时间 | +| `reasonStats` | Map | 各 reason 统计,e.g. `{"SPAM":3,"OFFENSIVE":1}` | +| `reporters` | List | 举报人列表,每个含 `reportId/reporterUserId(JsonString)/reporterOpenid(脱敏)/reason/detail/status/createTime` | + +### 2. 隐藏评价 + +``` +POST /admin/review/report-queue/{reviewId}/hide +Body: { "reason": "违规广告" } +``` + +后端动作: `review.report_status=HIDDEN` + 该评价所有 `review_report.status=HANDLED`。 + +### 3. 恢复评价 + +``` +POST /admin/review/report-queue/{reviewId}/restore +``` + +后端动作: `review.report_status=NORMAL` + `report_count=0` + 所有 `review_report.status=IGNORED`。 + +### 4. 单条忽略举报 + +``` +POST /admin/review/report-queue/report/{reportId}/ignore +``` + +后端动作: 仅改单条 `review_report.status=IGNORED`,不动评价本身。用于"举报不实/驳回单条举报"。 + +### 5. 警告作者 + +``` +POST /admin/review/report-queue/{reviewId}/warn-author +``` + +后端动作: 当前仅落操作日志(站内信 SDK 未集成,后端 TODO)。前端按钮可正常调用,文案"警告作者"即可。 + +--- + +## 字典 + +`review_report_reason`(举报原因)已通过 V20260505_007 + V20260507_001 初始化: + +| value | label | +|---|---| +| `SPAM` | 垃圾营销 | +| `OFFENSIVE` | 不友善/辱骂 | +| `FRAUD` | 欺诈/虚假 | +| `OTHER` | 其他 | + +前端展示 `reasonStats` 时,key 是 value(如 SPAM),需要通过字典查询接口 `/admin/system/dict-data/by-type?dictType=review_report_reason` 拿 label。 + +--- + +## 操作按钮文案建议 + +针对 `reportStatus`: +- **NORMAL**: 显示"忽略全部" / "警告作者"(举报数 < 3,无需隐藏) +- **PENDING_REVIEW**: 显示"隐藏评价" / "忽略全部" / "警告作者"(举报数 ≥ 3 或再机审命中) +- **HIDDEN**: 显示"恢复评价"(已隐藏) + +每条 `reporters` 行内显示"忽略本条举报"按钮(接口 4)。 + +--- + +## 开发提示 + +- 5 个接口都已有 swagger 文档,启 hl-admin-service 后访问 `/swagger-ui/` 可在线试。 +- `reviewId` / `userId` 都是 Long + `@JsonFormat(shape=STRING)`,前端用字符串接收防精度丢失。 +- `reporterOpenid` 已脱敏(前 4 + `***` + 后 4)。 +- 列表本身已按 `reportCount DESC, create_time DESC` 排序,前端不要重排。 + +--- + +## 不在本次范围(与前端无关) + +- 站内信通知作者(`hide` / `warnAuthor` 后端 TODO)— 需独立后端工单 +- Phase 2D-B 跨服务统一复审队列 — 已评估优先级低,不做 + +--- + +## 验收 + +1. 「内容安全 → 评价举报处理」菜单可见,有权限控制 +2. 列表能加载,各 status 切换正常 +3. 隐藏/恢复/忽略/警告 4 个操作按钮调通,操作完列表自动刷新 +4. `reasonStats` 字典 label 翻译正确 +5. 测试服 `reviewId=2048001001001001005` 已经有 1 条 SPAM 举报数据,前端接入后能直接看到