qingsongping-AIDevelop/docs/report-block-api.md

举报与屏蔽 API（V33）

版本：V33 实现版 状态：已编码实现，待黑盒验收 适用范围：举报、屏蔽、ADMIN 举报处理；仅允许对 MessagingService 增加屏蔽校验。 OpenAPI 117 → 125 paths（新增 8 path / 9 operation）。

1. 定位与边界

接口 / 模块	是否改动	关系
投递、Offer、面试、评分、治理、看板、匹配	不改	屏蔽不影响系统通知、投递、Offer、面试、评分、评价
MessagingService	仅改两方法	createOrGetDirectConversation、sendMessage 增加屏蔽校验
listMessages / getConversation / listConversations	不改	历史消息不删除，按现有权限读取
NotificationService	不改语义	复用，处理完成后向举报人发送通知，不新增 NotificationType 枚举
AI 自动审核 / 自动封禁 / 自动警告 / 公平性算法	不实现	本轮明确排除

2. 数据库（V33，三张表）

• reports：举报单。(reporter_user_id, idempotency_key) 唯一；active_key 唯一；target_type 仅 USER/MESSAGE；status 仅 PENDING/RESOLVED/REJECTED；message_id 外键 ON DELETE SET NULL；reporter_user_id/reported_user_id 外键关联 users；@Version 乐观锁；evidence_urls 使用 TEXT 存 JSON 字符串（不采用 MySQL JSON 列）。
• block_relations：(blocker_user_id, blocked_user_id) 唯一；禁止自己屏蔽自己；外键 ON DELETE CASCADE。
• report_decision_history：report_id 外键 ON DELETE CASCADE；记录 from_status → to_status、操作人、角色、note。

约束强校验：target_type=USER 时 target_user_id 非空且 message_id 为空；target_type=MESSAGE 反之。

3. 举报接口

POST /reports           提交举报
GET  /reports/me        我的举报列表（status/page/size）
GET  /reports/{id}      举报详情（本人或 ADMIN）

• 身份全取 JWT，不接受 userId/reporterId/reportedUserId 注入。
• USER 举报：客户端传 targetUserId，服务端校验存在，targetUserId ≠ 本人，reportedUserId = targetUserId。
• MESSAGE 举报：仅传 messageId，服务端校验存在 + 本人是会话参与者（无权返回 403/2002，不泄露消息是否存在），reportedUserId 从消息真实 sender 推导，禁止客户端覆盖。
• 路由：/reports/me 必须在 /reports/{id} 之前注册，并有路由回归测试。

幂等与防重：

场景	行为
同 reporter + idempotencyKey + 相同请求体	返回原举报，200（不新增）
同 reporter + idempotencyKey + 不同请求体	409 / 9606
同 reporter + 同目标 + 同 category + 同 messageId/targetUserId + 已有 PENDING	409 / 9603
已 RESOLVED/REJECTED	不占用 active_key，允许重新提交

evidenceUrls 校验：最多 5 个、每个 ≤500 字符、仅 http/https；后端不主动请求/抓取 URL（防 SSRF）。

4. 屏蔽接口

PUT    /blocks/{blockedUserId}   屏蔽
DELETE /blocks/{blockedUserId}   解除屏蔽（幂等）
GET    /blocks/me                我的屏蔽列表（page/size）

• 屏蔽自己 → 400 / 9608；目标不存在复用以有用户不存在错误码。
• PUT 已存在返回 200 不新增；DELETE 不存在返回 200 不报错；GET 仅返回本人主动屏蔽的用户。
• 响应不返回对方手机号/邮箱/密码/简历地址。
• 屏蔽不影响系统通知、投递、Offer、面试、评分、评价。

5. MessagingService 屏蔽控制

• createOrGetDirectConversation：若 A 屏蔽 B 或 B 屏蔽 A 任一方向存在，禁止新建 DIRECT 会话。
• sendMessage：会话内任一方向存在屏蔽，禁止发送新消息。
• 对外统一 403 / 2002 / "message cannot be sent"，不返回“你已被屏蔽”，不泄露哪一方屏蔽了谁。
• 内部审计记录 BLOCKED_SEND_PROHIBITED。
• 屏蔽期间发送失败的消息直接丢弃，解除屏蔽后不补发。
• listMessages、getConversation、listConversations 保持现有语义。

6. ADMIN 举报处理接口

GET  /admin/reports                    举报列表（status/targetType/category/page/size）
GET  /admin/reports/{id}               举报详情（含处理历史、脱敏证据 URL、MESSAGE 脱敏内容）
POST /admin/reports/{id}/decision      处理决定

• 仅 ADMIN；COMPANY / STUDENT / 未登录分别 403 / 403 / 401。
• decision 仅 RESOLVED / REJECTED；REJECTED 必填 note。
• 仅 PENDING 可处理，重复 → 409 / 9604；非法流转 → 409 / 9605；乐观锁冲突 → 409 / 9605。
• 处理不自动封禁、不删除消息、不修改投递/面试/评分状态。
• 权限矩阵：

身份/场景	HTTP	code
未登录	401	2001
COMPANY / STUDENT	403	2002
ADMIN	200	—
非本人非 ADMIN 查详情	403	2002
举报不存在	404	9601

7. 错误码

code	枚举	HTTP	说明
9601	REPORT_NOT_FOUND	404	举报不存在
9602	CANNOT_REPORT_SELF	400	不能举报自己
9603	REPORT_DUPLICATE	409	同目标同分类已有 PENDING
9604	ALREADY_DECIDED	409	重复决定
9605	INVALID_TRANSITION	409	非法流转 / 乐观锁冲突
9606	IDEMPOTENCY_CONFLICT	409	幂等键冲突（不同请求体）
9607	REASON_REQUIRED	400	理由缺失（注意复用 BAD_REQUEST 由校验层触发）
9608	CANNOT_BLOCK_SELF	400	不能屏蔽自己
9609	REPORT_RATE_LIMITED	429	举报频率超限
9610	BLOCKED_SEND_PROHIBITED	内部	仅内部审计/日志，HTTP 不直接暴露

复用：BAD_REQUEST(1001)、UNAUTHORIZED(2001)、FORBIDDEN(2002)、用户/消息不存在错误码。

8. 举报限流

• 使用现有 Redis，不新增数据库表；仅限制 POST /reports。
• 每用户默认每小时最多 10 次；key：report:rate:{userId}:{hour}。
• 超限 → 429 / 9609，记录 REPORT_RATE_LIMITED 审计。
• 不影响屏蔽、查询、ADMIN 处理接口；不实现自动封禁。

9. 通知闭环

• 处理完成后向举报人发送一条通知，复用 NotificationService，不新增枚举。
• type=REPORT_DECISION、businessType=REPORT、businessId=reportId、idempotencyKey=report-decision-{reportId}。
• RESOLVED / REJECTED 均可通知；同一举报最多一条处理结果通知（幂等）。
• 举报提交时不通知被举报人，不通知被举报人的联系方式。

10. 审计

新增 action：REPORT_CREATED、REPORT_DECIDED、BLOCK_CREATED、BLOCK_REMOVED、BLOCKED_SEND_PROHIBITED、REPORT_RATE_LIMITED。

details 仅含：reportId、userId、category、decision、targetType、messageId、requestId、timestamp。 禁止写入：phone、email、password、JWT、resumeUrl、消息全文、文件绝对路径、evidence 文件内容、数据库连接信息。

11. 并发与幂等

• 举报：(reporter_user_id, idempotency_key) 唯一 + active_key 唯一 + 创建事务；并发重复仅一条成功，另一条 9603 或同幂等返回原记录。
• 屏蔽：唯一约束保证并发 PUT 不产生重复关系；DELETE 幂等；屏蔽检查与发送消息在同一业务事务内。
• 处理：@Version 乐观锁，冲突 409/9605。

12. 脱敏策略

• 响应永不返回 phone、email、passwordHash、resumeUrl、JWT、消息全文、举报人内部 ID（非 ADMIN）。
• MESSAGE 举报仅返回脱敏 messagePreview，不返回会话内其他敏感内容。
• 对外屏蔽发送统一模糊错误，不泄露屏蔽关系方向。

13. OpenAPI 变化

• 新增 8 path / 9 operation，117 → 125 paths。
• 新 path：/reports、/reports/me、/reports/{id}、/blocks/{blockedUserId}（PUT+DELETE）、/blocks/me、/admin/reports、/admin/reports/{id}、/admin/reports/{id}/decision。
• 声明：bearerAuth、请求/响应 DTO、USER/MESSAGE 枚举、PENDING/RESOLVED/REJECTED 枚举、400/401/403/404/409/429、屏蔽模糊错误、MESSAGE 需 messageId、USER 需 targetUserId。

14. 测试覆盖要点

1. USER 举报；2. MESSAGE 举报；3. MESSAGE 发送者服务端推导；4. 无权访问 messageId；5. 举报自己；6. 不存在 targetUserId；7. evidenceUrls 校验；8. 幂等同请求体；9. 幂等不同请求体；10. PENDING 重复；11. ADMIN 决定；12. 重复决定；13. 决定历史；14. 屏蔽/解除；15. 重复屏蔽/解除；16. 屏蔽后禁止 DIRECT；17. 屏蔽后禁止发送；18. 历史消息可读；19. 失败消息不补发；20. 频率限制；21. 通知幂等；22. 权限矩阵；23. 脱敏；24. 乐观锁并发；25. 业务数据不删除；26. V33 迁移 H2(MODE=MySQL)/MySQL 兼容。