# 评价审核与防刷基础模块接口说明

> 轻松聘 (mydreamjob) · 评价审核与防刷基础模块
> 基础路径:`/api/v1` · 审核管理接口仅 ADMIN;评价公开接口保持原路径

## 1. 概述

在岗位评价基础上加入**确定性规则预审(非 AI)**与**管理员审核**:

- 无风险评价 → `moderationStatus = AUTO_APPROVED`,行为与旧版一致(同步 200、公开展示);
- 命中规则 → 评价**仍保存成功**,`moderationStatus = PENDING`,**不进入**公开列表/详情/汇总;
- 管理员可 `APPROVED`(进入公开)或 `REJECTED`(永不公开);
- 公开查询只返回 `status=PUBLISHED` 且 `moderationStatus ∈ {AUTO_APPROVED, APPROVED}`。

审核状态值:`AUTO_APPROVED` / `PENDING` / `APPROVED` / `REJECTED`。

## 2. 防刷规则(确定性 MVP)

| 原因码 | 规则 | 权重 |
|---|---|---|
| `SENSITIVE_WORD` | 内容包含配置中的敏感词(`app.review-moderation.sensitive-words`) | +2 |
| `CONTACT_INFO` | 包含手机号 / QQ / 微信 / 外链 | +2 |
| `PATTERN_ANOMALY` | 连续重复字符或异常超长(≥800 字) | +1 |
| `RAPID_SUBMISSION` | 同一用户窗口期内重复提交(默认 60s 内 ≥3) | +1 |
| `DUPLICATE_CONTENT` | 同岗位窗口期内出现相同内容 SHA-256(默认 300s) | +2 |
| `ABUSIVE_BATCH` | 同一 IP/User-Agent 哈希窗口期批量(默认 300s 内 ≥5) | +2 |

- 敏感词来自配置项,不硬编码在 Controller;命中时**只返回原因码,不返回敏感词原文**;
- 原始 IP / User-Agent **不落明文**,仅存 SHA-256 哈希;
- 内容哈希只用于风险识别,不影响正常评价。

## 3. 公开查询兼容(不变路径)

- `GET /jobs/{jobId}/reviews` / `GET /jobs/{jobId}/reviews/{reviewId}` / `GET /jobs/{jobId}/reviews/summary`
  仅返回/统计 `AUTO_APPROVED` 与 `APPROVED` 的评价;`PENDING`/`REJECTED` 不公开。
- 八维 `dimensionScores` 与 `dimensionSummary` 逻辑不变。

## 4. 审核管理接口(仅 ADMIN,身份来自 JWT)

### 4.1 待审列表 `GET /admin/reviews/pending`

- 仅 ADMIN(非 ADMIN → 403,未登录 → 401);分页;
- 可选筛选:`jobId`、`riskLevel`(LOW/MEDIUM/HIGH)、`createdFrom`、`createdTo`;
- 返回:`reviewId, jobId, studentUserId, rating, content, tags, dimensionScores,
  moderationStatus, reasonCodes, riskLevel, moderationScore, createdAt`;
- **不返回**明文 IP / User-Agent / 内部哈希。

### 4.2 审核决策 `POST /admin/reviews/{reviewId}/decision`

```json
{ "decision": "APPROVED|REJECTED", "reason": "人工审核说明(可选)" }
```

- 仅 ADMIN;仅 `PENDING` 可审,已审核重复提交 → **409 `REVIEW_ALREADY_DECIDED`**;
- `APPROVED` → 进入公开列表/汇总;`REJECTED` → 永不公开;
- 决策写入 `review_moderation_history` 与 `audit_logs`;审核人从 JWT 获取。

### 4.3 审核历史 `GET /admin/reviews/history`

- 仅 ADMIN;分页;返回 `id, reviewId, action, actorUserId, reasonCodes, reason, createdAt`
  (含自动预审标记与管理员决策)。

## 5. 权限

| 操作 | ADMIN | 学生本人 | 其他学生 | 企业 | 未登录 |
|---|---|---|---|---|---|
| 创建评价 | — | ✅ | 403(重复→409) | 403 | 401 |
| 评价列表/详情/汇总 | 公开 | 公开 | 公开 | 公开 | ✅ |
| 待审/决策/历史 | ✅ | 403 | 403 | 403 | 401 |

审核人/操作者一律来自 JWT,不信任请求体 userId。

## 6. 数据库(V18)

`V18__job_review_moderation.sql`:
- `job_reviews` 增加:`moderation_status`(默认 `AUTO_APPROVED`,历史数据自动生效)、`moderation_reason`(原因码 JSON)、`moderation_score`、`moderation_updated_at`、`risk_level`、`content_hash`、`ip_hash`、`ua_hash`(SHA-256,不存明文);`moderation_status` 建索引;
- 新表 `review_moderation_history`(自动预审标记 + 管理员决策,级联删除);
- 不改既有表结构,V1-V17 历史迁移不动。

## 7. 测试

覆盖:普通评价 AUTO_APPROVED 且公开、敏感词/联系方式 PENDING 且不公开、内容哈希风险、IP/UA 仅存哈希、审核通过后公开、审核拒绝不公开、非 ADMIN 403、未登录 401、重复审核 409、历史迁移默认 AUTO_APPROVED、维度仍可保存读取、并发重复仅一条成功、审核写入 audit_logs、既有 526 测试回归。

## 8. 已知限制

1. 规则为确定性 MVP,不声称 AI;权重/窗口为默认配置,可按运营调整。
2. `moderation_reason` 仅存原因码,敏感词原文不落库、不返回。
3. 已审核(`APPROVED/REJECTED`)评价如需复审需产品确认(当前不可重复决策)。
4. OpenAPI 快照:`docs/openapi-rc.json` 由 H2 集成测试上下文导出(**59 路径**),现网可用 `GET /api/v1/v3/api-docs` 重新导出。