审核与处罚
两块能力都在 Account 服务:举报(任何登录用户可用)与处罚(需要管理权限)。审核在 Flask 管理面板进行,服务端只负责记录与列表。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /reports |
需认证 | 提交举报 |
| GET | /reports/mine?limit= |
需认证 | 我提交过的举报(默认 50,上限 100) |
POST /reports{ "target_type": "post", "target_id": 123, "reason": "垃圾广告" }| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
target_type |
string | ✅ | post | message | user |
target_id |
int | ✅ | 被举报内容的 id |
reason |
string | ✅ | 1–500 字符 |
成功 201 + 举报记录。
| 列 | 含义 |
|---|---|
reporter_id |
举报人(级联删除) |
target_type / target_id |
目标类型与 id |
reason |
自由文本,≤500 字符 |
status |
pending / reviewed / dismissed |
reviewer_id / reviewer_username |
处理人及反规范化名字(历史不受账号变更影响) |
review_note |
运营备注 |
created_at / reviewed_at |
提交与处理时间 |
(target_type, target_id) 刻意不设外键:三类目标分处三张表,且目标被删除后不应抹掉“曾被举报”的记录。id 在写入时校验,面板对被删目标显式标注。
| 条件 | 响应 |
|---|---|
未知 target_type |
400 |
target_id ≤ 0、reason 为空或超长 |
400 |
举报自己(user 类型且 id 是自己) |
400 |
| 目标不存在 | 404 |
| 同一目标已有待处理举报 | 409 |
| 一小时内举报超过 20 条 | 429 |
409 来自部分唯一索引 idx_reports_one_open ON (reporter_id, target_type, target_id) WHERE status = 'pending';冲突被翻译成明确错误而不是 500。举报被处理后槽位释放,同一目标可再次举报。
在管理面板(/reports,能力 reports.manage)进行:默认列出待处理,可按状态与目标类型筛选;处理时写入 status、reviewer_*、review_note、reviewed_at 并记 admin_audit_log。已处理的可重开(回到 pending 并清空审核字段),除非同一举报人此后又提交了更新的待处理举报(会撞部分唯一索引,故拒绝并给出说明)。
处理举报只是记账:它本身不处罚谁、也不删除内容。运营需另行删除帖子或处罚用户。
删除用户会因 reporter_id ... ON DELETE CASCADE 连带删除他提交的举报;别人举报他的记录保留,只是 target_id 不再能解析——面板会显式显示目标缺失。
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /users/:id/punishments |
user.punish |
施加处罚 |
| GET | /users/:id/punishments |
user.punish |
处罚历史 + 当前生效的权限剥夺 |
| 类型 | 含义 | 副作用 |
|---|---|---|
warning |
警告 | 仅记录 |
demerit |
记过 | 仅记录 |
revoke |
剥夺权限 | 写 user_permission_bans |
temp_ban |
暂时封禁 | users.status = 'banned' + banned_until |
ban |
永久封禁 | users.status = 'banned',banned_until = NULL |
unban |
解除封禁 | 恢复 status = 'active',清空全部权限剥夺 |
restore |
恢复权限 | 删除对应的 user_permission_bans 行 |
POST /users/:id/punishments{ "type": "temp_ban", "reason": "刷屏", "duration_minutes": 120 }| 字段 | 必填 | 说明 |
|---|---|---|
type |
✅ | 上表之一 |
reason |
说明文本 | |
permission_key |
revoke/restore 必填 |
要剥夺/恢复的权限键 |
duration_minutes |
temp_ban 必填 |
封禁时长(分钟) |
记录插入与副作用在同一事务内完成。
| 条件 | 响应 |
|---|---|
| 处罚自己 | 403 cannot punish yourself |
| 处罚管理员 | 403 cannot punish an administrator |
| 权限等级不足以处罚该用户(下级不能罚上级) | 403 insufficient rank to punish this user |
revoke/restore 缺 permission_key |
400 |
temp_ban 缺 duration_minutes |
400 |
| 未知类型 | 400 |
user_permission_bans 保存当前生效的被剥夺权限,GetEffectivePermissions 解析时排除它——被剥夺的键在所有地方失效,直到 restore 或 unban。
封禁如何生效
Section titled “封禁如何生效”users.status / banned_until 会拦下登录与后续每个请求:
| 环节 | 行为 |
|---|---|
| 登录 / OIDC 回调 / refresh | 拒绝 status = 'banned' 的用户 |
temp_ban |
banned_until 过期后自动解除(与 NOW() 比较) |
| 请求链路 | 网关每个已认证请求检查一次(IsBannedCached),命中直接 403 {"error":"account is banned","banned":true},不转发后端。结果缓存 30 秒——新封禁半分钟内生效,不必等下次登录 |
| 已签发的 access token | 不吊销;封禁靠每请求状态检查实现,而非使 token 失效 |
| 部分路由仍可达 | GET /users/me、GET /users/me/punishments、POST /auth/refresh(refresh 只让客户端看见封禁,不会为封禁用户签发 token) |
公开路由(authPublic) |
不检查封禁:被封用户仍能读公开内容,token 在那里仍被用于个性化。封的是动作,不是读 |
| 被封禁的 bot | static token 在解析阶段就失败,所有请求(含公开路由)返回 401 {"error":"invalid bot token"} |
与 bot 的关系
Section titled “与 bot 的关系”bot 默认组没有 user.punish,因此 bot 不能封禁或处罚任何人,只能举报。详见 Bot 开发指南。