# 举报与反馈系统设计

> **状态**：设计已确认 ✅
> **创建时间**：2026-06-11
> **作者**：Claude
> **目标**：在 TopFans 平台新增内容举报与用户反馈两大工单系统，支撑运营/审核员通过独立 web 后台对违规内容（数字藏品/用户/AI 描述词）和用户反馈（BUG/咨询/合作/建议）进行审核处理

---

## 目录

1. [背景与目标](#1-背景与目标)
2. [架构概览](#2-架构概览)
3. [数据模型](#3-数据模型)
4. [状态机](#4-状态机)
5. [API 设计](#5-api-设计)
6. [关键流程](#6-关键流程)
7. [错误码](#7-错误码)
8. [通知机制](#8-通知机制)
9. [安全与防护](#9-安全与防护)
10. [实施步骤](#10-实施步骤)
11. [附录](#11-附录)

---

## 1. 背景与目标

### 1.1 背景

TopFans 是粉丝/明星数字藏品平台。当前平台缺少：
- 用户对违规内容（藏品/用户/AI 描述词）的举报通道
- 用户对平台体验问题的反馈通道
- 运营/审核员对举报和反馈的审核处理后台

### 1.2 目标

- 提供客户端（uni-app）举报与反馈的提交入口
- 提供运营 web 后台（基于 `D:\shanghai\TopFans-activity`）的工单审核界面
- 支持"举报达到阈值自动隐藏 + 管理员审核动作（标记状态）"的闭环
- 设计可扩展、易维护、易观测

### 1.3 范围

**包含**：
- 客户端提交接口（uni-app 端）
- 审核员后台（Vue3 + Element Plus）
- 数据模型与迁移
- 状态机、自动隐藏、动作流水
- 通知机制

**不包含（YAGNI）**：
- 举报人/被举报人间的对话沟通
- 申诉/上诉流程
- 举报人积分/奖励体系
- 复杂的多级管理员（仅一种角色）
- 工单 SLA 监控告警

---

## 2. 架构概览

### 2.1 整体架构

```
┌──────────────────────────────────────────────────────────────────┐
│                       客户端 (uni-app)                           │
│  ┌─────────────────────────┐  ┌──────────────────────────────┐  │
│  │ 举报弹窗 (藏品/用户/描述词)│  │ 我的 → 意见反馈              │  │
│  └────────────┬────────────┘  └────────────┬─────────────────┘  │
└───────────────┼──────────────────────────────┼──────────────────┘
                │ REST                          │
                ▼                              ▼
┌──────────────────────────────────────────────────────────────────┐
│   topfans gateway (Go, 已有)                                    │
│   /api/v1/moderation/*  客户端 API                              │
└───────────────────────────┬──────────────────────────────────────┘
                            │ Dubbo RPC
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│   topfans moderationService (Go, 新建微服务)                     │
│   - ReportService / FeedbackService / CategoryService           │
│   - 写 PostgreSQL reports/feedbacks/categories/状态表            │
│   - Redis 计数 (自动隐藏阈值)                                   │
│   - 触发自动隐藏：UPDATE reports + UPSERT moderation_target_status│
└────────┬─────────────────────────────────────────┬───────────────┘
         │ 共享 PG 库                              │
         │                                         │
         ▼                                         ▼
┌────────────────────────────┐  ┌──────────────────────────────────┐
│  PostgreSQL (topfans 库)    │  │  Redis (topfans 已有实例)        │
│  - report_categories       │  │  - mod:report:counter:*          │
│  - feedback_categories     │  │  - mod:report:user:*             │
│  - reports                 │  │  - mod:report:lock:*             │
│  - report_evidence         │  └──────────────────────────────────┘
│  - feedbacks               │
│  - feedback_evidence       │
│  - moderation_target_status│  ← 业务服务读路径 JOIN 此表
│  - moderation_actions      │
│  - admin_audit_logs        │
└────────┬───────────────────┘
         │ 共享 PG 库 (直接读写，不调对方接口)
         ▼
┌──────────────────────────────────────────────────────────────────┐
│   TopFans-Activity 后台 (FastAPI + Vue3, 已有项目)                │
│   D:\shanghai\TopFans-activity                                   │
│   - backend/handlers/moderation_admin.py (后台 API)              │
│   - backend/crud/moderation_crud.py                              │
│   - backend/schemas/moderation.py                                │
│   - frontend/src/views/moderation/ (举报/反馈工单 UI)            │
└──────────────────────────────────────────────────────────────────┘
```

### 2.2 模块职责

| 模块 | 职责 |
|------|------|
| `ReportService` (Go) | 接收举报、查询我的举报、触发自动隐藏 |
| `FeedbackService` (Go) | 接收反馈、查询我的反馈 |
| `CategoryService` (Go+FastAPI) | 维护分类（动态配置），客户端读取 + 后台 CRUD |
| `AutoHideExecutor` (Go) | Redis 计数 + 触发自动隐藏（写 reports + 状态表） |
| 后台 Moderation Admin (FastAPI) | 审核员认领/动作/分类管理 |
| `moderation_target_status` 表 | 业务服务读路径 JOIN，呈现"隐藏/封禁/警告"状态 |

### 2.3 复用现有资产

- **OSS 上传**：举报证据图、反馈截图复用 `assetService` 的 OSS 签名接口（`GET /api/v1/assets/oss/signature?type=asset`）
- **认证**：客户端 JWT 用 topfans userService；后台 JWT 用 `TopFans-activity` 已有的 `verify_token`
- **通知中心**：处理结果通过 topfans `notificationService` 模板下发（新增 5 个模板）
- **数据迁移**：遵循 topfans 现有 `backend/migrations/00x_*.sql` 命名规范
- **序列同步**：手动指定 ID 时必须 `SELECT setval('table_id_seq', MAX(id))`（CLAUDE.md 强制规范）

---

## 3. 数据模型

### 3.1 核心表

```
report_categories      举报分类（动态配置）
feedback_categories    反馈分类（动态配置）
reports                举报工单主表
report_evidence        举报证据图（一对多）
feedbacks              反馈工单主表
feedback_evidence      反馈截图（一对多）
moderation_actions     审核动作流水
moderation_target_status  共享"对象受管控状态"表（业务服务读路径 JOIN）
admin_audit_logs       管理员操作日志
```

### 3.2 `report_categories` 举报分类

```sql
CREATE TABLE report_categories (
    id BIGSERIAL PRIMARY KEY,
    code VARCHAR(50) NOT NULL UNIQUE,
    name VARCHAR(50) NOT NULL,
    description VARCHAR(200),
    severity SMALLINT NOT NULL DEFAULT 1,
    enabled BOOLEAN NOT NULL DEFAULT TRUE,
    sort_order INT NOT NULL DEFAULT 0,
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL
);
CREATE INDEX idx_report_categories_enabled ON report_categories(enabled, sort_order);

-- 初始数据
INSERT INTO report_categories (code, name, description, severity, sort_order, created_at, updated_at) VALUES
  ('pornographic', '色情低俗', '含裸露、性暗示内容', 5, 1, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000),
  ('violence',    '暴力血腥',  '含暴力、血腥画面', 5, 2, ...),
  ('infringing',  '侵权盗版',  '侵犯他人著作权/商标权', 4, 3, ...),
  ('false_info',  '虚假信息',  '虚假、欺骗性内容', 3, 4, ...),
  ('political',   '政治敏感',  '涉及政治敏感话题', 5, 5, ...),
  ('ad_spam',     '广告骚扰',  '垃圾广告、骚扰信息', 2, 6, ...),
  ('other',       '其他',      '其他违规情况', 1, 99, ...);

SELECT setval('report_categories_id_seq', (SELECT MAX(id) FROM report_categories));
```

### 3.3 `feedback_categories` 反馈分类

```sql
CREATE TABLE feedback_categories (
    id BIGSERIAL PRIMARY KEY,
    code VARCHAR(50) NOT NULL UNIQUE,
    name VARCHAR(50) NOT NULL,
    description VARCHAR(200),
    enabled BOOLEAN NOT NULL DEFAULT TRUE,
    sort_order INT NOT NULL DEFAULT 0,
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL
);

INSERT INTO feedback_categories (code, name, description, sort_order, created_at, updated_at) VALUES
  ('bug',        'BUG 报告',  '使用中遇到的问题', 1, ...),
  ('consult',    '使用咨询',  '不知道怎么用', 2, ...),
  ('business',   '内容合作',  '合作/商务联系', 3, ...),
  ('suggestion', '功能建议',  '希望增加什么功能', 4, ...);

SELECT setval('feedback_categories_id_seq', (SELECT MAX(id) FROM feedback_categories));
```

### 3.4 `reports` 举报工单

```sql
CREATE TABLE reports (
    id BIGSERIAL PRIMARY KEY,
    reporter_id BIGINT NOT NULL,
    star_id BIGINT,
    target_type VARCHAR(30) NOT NULL,    -- asset | user_profile | description_word
    target_id BIGINT NOT NULL,
    target_snapshot JSONB NOT NULL,      -- 提交时的对象快照
    
    category_code VARCHAR(50) NOT NULL,
    description VARCHAR(500),
    is_anonymous BOOLEAN NOT NULL DEFAULT FALSE,
    
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
        -- pending / reviewing / auto_hidden / resolved / dismissed
    is_auto_hidden BOOLEAN NOT NULL DEFAULT FALSE,
    
    resolved_action VARCHAR(20),         -- takedown | ban | warn | dismissed
    resolved_by BIGINT,
    resolved_at BIGINT,
    resolution_note VARCHAR(500),
    
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    
    CONSTRAINT fk_reports_category FOREIGN KEY (category_code)
        REFERENCES report_categories(code) ON DELETE RESTRICT
);
CREATE INDEX idx_reports_status_created ON reports(status, created_at DESC);
CREATE INDEX idx_reports_target ON reports(target_type, target_id, status);
CREATE INDEX idx_reports_reporter ON reports(reporter_id, created_at DESC);

-- 防重复：同一举报人对同一对象在未结案前只能有一条
CREATE UNIQUE INDEX uk_reports_reporter_target_pending
    ON reports(reporter_id, target_type, target_id)
    WHERE status IN ('pending', 'reviewing', 'auto_hidden');
```

### 3.5 `report_evidence` 举报证据图

```sql
CREATE TABLE report_evidence (
    id BIGSERIAL PRIMARY KEY,
    report_id BIGINT NOT NULL,
    oss_key VARCHAR(255) NOT NULL,
    oss_url VARCHAR(500),
    sort_order INT NOT NULL DEFAULT 0,
    created_at BIGINT NOT NULL,
    CONSTRAINT fk_report_evidence_report
        FOREIGN KEY (report_id) REFERENCES reports(id) ON DELETE CASCADE
);
CREATE INDEX idx_report_evidence_report ON report_evidence(report_id, sort_order);
```

### 3.6 `feedbacks` 反馈工单

```sql
CREATE TABLE feedbacks (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    star_id BIGINT,
    category_code VARCHAR(50) NOT NULL,
    title VARCHAR(100) NOT NULL,
    content TEXT NOT NULL,
    contact VARCHAR(100),
    is_anonymous BOOLEAN NOT NULL DEFAULT FALSE,
    
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
        -- pending / reviewing / replied / closed / archived
    
    replied_by BIGINT,
    replied_at BIGINT,
    reply_content TEXT,
    
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    
    CONSTRAINT fk_feedbacks_category FOREIGN KEY (category_code)
        REFERENCES feedback_categories(code) ON DELETE RESTRICT
);
CREATE INDEX idx_feedbacks_status_created ON feedbacks(status, created_at DESC);
CREATE INDEX idx_feedbacks_user ON feedbacks(user_id, created_at DESC);
CREATE INDEX idx_feedbacks_category ON feedbacks(category_code, status);
```

### 3.7 `feedback_evidence` 反馈截图

```sql
CREATE TABLE feedback_evidence (
    id BIGSERIAL PRIMARY KEY,
    feedback_id BIGINT NOT NULL,
    oss_key VARCHAR(255) NOT NULL,
    oss_url VARCHAR(500),
    sort_order INT NOT NULL DEFAULT 0,
    created_at BIGINT NOT NULL,
    CONSTRAINT fk_feedback_evidence_feedback
        FOREIGN KEY (feedback_id) REFERENCES feedbacks(id) ON DELETE CASCADE
);
CREATE INDEX idx_feedback_evidence_feedback ON feedback_evidence(feedback_id, sort_order);
```

### 3.8 `moderation_actions` 审核动作流水

```sql
CREATE TABLE moderation_actions (
    id BIGSERIAL PRIMARY KEY,
    report_id BIGINT,
    feedback_id BIGINT,
    admin_id BIGINT NOT NULL,
    action_type VARCHAR(30) NOT NULL,   -- takedown | unhide | ban | warn | dismiss | reply | close | archive
    target_type VARCHAR(30),
    target_id BIGINT,
    note VARCHAR(500),
    success BOOLEAN NOT NULL,
    error_message VARCHAR(500),
    created_at BIGINT NOT NULL,
    CONSTRAINT chk_moderation_actions_xor
        CHECK ((report_id IS NOT NULL) OR (feedback_id IS NOT NULL))
);
CREATE INDEX idx_moderation_actions_report ON moderation_actions(report_id, created_at DESC);
CREATE INDEX idx_moderation_actions_feedback ON moderation_actions(feedback_id, created_at DESC);
CREATE INDEX idx_moderation_actions_admin ON moderation_actions(admin_id, created_at DESC);
```

### 3.9 `moderation_target_status` 共享"对象受管控状态"

```sql
CREATE TABLE moderation_target_status (
    id BIGSERIAL PRIMARY KEY,
    target_type VARCHAR(30) NOT NULL,        -- asset | user | description_word
    target_id BIGINT NOT NULL,
    
    is_hidden BOOLEAN NOT NULL DEFAULT FALSE,   -- 隐藏/下架
    is_banned BOOLEAN NOT NULL DEFAULT FALSE,   -- 封禁（仅 user）
    is_warned BOOLEAN NOT NULL DEFAULT FALSE,   -- 已警告（仅 user）
    
    reason VARCHAR(200),
    source VARCHAR(30) NOT NULL,                -- auto | admin
    source_report_id BIGINT,
    operator_admin_id BIGINT,
    
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    
    CONSTRAINT uk_moderation_target UNIQUE (target_type, target_id)
);
CREATE INDEX idx_mts_hidden ON moderation_target_status(is_hidden) WHERE is_hidden = TRUE;
CREATE INDEX idx_mts_banned ON moderation_target_status(is_banned) WHERE is_banned = TRUE;
```

**写入方**：
- `moderationService` (Go) — 自动隐藏时 UPSERT
- `TopFans-Activity` 后台 (FastAPI) — 审核员手动下架/封禁/警告时 UPSERT

**读取方**：
- `assetService` 藏品查询/详情/列表：`LEFT JOIN moderation_target_status ON target_type='asset' AND target_id=assets.id WHERE COALESCE(is_hidden, false) = false`
- `userService` 登录/操作校验：`LEFT JOIN ... WHERE COALESCE(is_banned, false) = false`
- AI 描述词服务查询时同样 JOIN

### 3.10 `admin_audit_logs` 管理员操作日志

```sql
CREATE TABLE admin_audit_logs (
    id BIGSERIAL PRIMARY KEY,
    admin_id BIGINT NOT NULL,
    action VARCHAR(50) NOT NULL,
    resource_type VARCHAR(30),
    resource_id BIGINT,
    ip VARCHAR(50),
    user_agent VARCHAR(500),
    extra JSONB,
    created_at BIGINT NOT NULL
);
CREATE INDEX idx_admin_audit_logs_admin ON admin_audit_logs(admin_id, created_at DESC);
CREATE INDEX idx_admin_audit_logs_resource ON admin_audit_logs(resource_type, resource_id);
```

### 3.11 Redis 数据结构

| Key 模式 | 类型 | 用途 | TTL |
|----------|------|------|-----|
| `mod:report:counter:{target_type}:{target_id}` | String (INCR) | 自动隐藏阈值计数（独立用户数）| 7 天 |
| `mod:report:user:{target_type}:{target_id}:{user_id}` | String | 防重复（仅独立用户才计数）| 24h |
| `mod:report:lock:{target_type}:{target_id}` | String | 防并发触发自动隐藏 | 5s |
| `mod:auto_hide_threshold` | String (缓存) | 自动隐藏阈值 N（默认 5） | 永久 |

### 3.12 序列同步规范

遵循 CLAUDE.md 规范：所有手动指定 ID 的 INSERT 末尾必须 `SELECT setval('table_id_seq', (SELECT MAX(id) FROM table))`。

新表起始值：`CREATE SEQUENCE table_id_seq START WITH 10000;` 预留测试数据空间。

---

## 4. 状态机

### 4.1 举报状态机

```
                    ┌──────────────────────────────────┐
                    │           pending                │
                    │         (待处理)                  │
                    └─────┬─────────────┬──────────────┘
              管理员认领   │             │  阈值 N 触发
                          ▼             ▼
              ┌──────────────────┐  ┌──────────────────┐
              │    reviewing     │  │   auto_hidden    │
              │    (审核中)       │  │  (已自动隐藏)     │
              └────┬────┬────┬───┘  └────┬─────────────┘
        下架/封禁  │    │驳回│ 解除隐藏  │ 管理员认领
        /警告     │    │    │            ▼
                   ▼    │    ▼    ┌──────────────────┐
              ┌──────┐  │  ┌──────────────┐         │
              │resolved│ │  │  dismissed   │         │
              │(已处理)│ │  │  (已驳回)    │         │
              └──────┘  │  └──────────────┘         │
                         │                          │
                         └────→ resolved / dismissed
```

| 状态 | 含义 | 进入 | 退出 |
|------|------|------|------|
| `pending` | 新提交待处理 | 创建 | 认领 OR 自动隐藏 |
| `reviewing` | 管理员已认领 | 认领 | 做出处理动作 |
| `auto_hidden` | 触发自动隐藏 | 阈值达成 | 管理员认领并做最终裁决 |
| `resolved` | 已处理 | takedown/ban/warn | 终态 |
| `dismissed` | 已驳回 | dismiss | 终态 |

**并发认领防护**：
```sql
UPDATE reports
SET status = 'reviewing', updated_at = ?
WHERE id = ? AND status IN ('pending', 'auto_hidden')
```
用 affected rows = 1 判断是否抢锁成功。

### 4.2 反馈状态机

```
         ┌────────────┐
         │  pending   │
         └─────┬──────┘
               │ 认领
               ▼
       ┌────────────────┐
       │   reviewing    │
       └─┬──────┬────┬──┘
         │      │    │
   已回复 │      │关闭│ 归档
         ▼      ▼    ▼
   ┌────────┐ ┌────────┐ ┌────────┐
   │replied │ │closed  │ │archived│
   └────────┘ └────────┘ └────────┘
```

| 状态 | 进入 | 备注 |
|------|------|------|
| `pending` | 创建 | 初始 |
| `reviewing` | 认领 | |
| `replied` | 填写 `reply_content` | 终态，触发用户通知 |
| `closed` | 点击关闭 | 终态，重复/无效 |
| `archived` | 归档 | 终态，已处理保留记录 |

---

## 5. API 设计

### 5.1 客户端 API（uni-app 端调用，路径前缀 `/api/v1/moderation`）

| Method & Path | 说明 |
|---------------|------|
| `GET  /api/v1/moderation/report-categories` | 获取启用中的举报分类 |
| `POST /api/v1/moderation/reports` | 提交举报 |
| `GET  /api/v1/moderation/reports?status=&page=&page_size=` | 我的举报记录 |
| `GET  /api/v1/moderation/reports/{id}` | 查看举报进度与结果 |
| `GET  /api/v1/moderation/feedback-categories` | 获取反馈分类 |
| `POST /api/v1/moderation/feedbacks` | 提交反馈 |
| `GET  /api/v1/moderation/feedbacks?status=&page=&page_size=` | 我的反馈记录 |
| `GET  /api/v1/moderation/feedbacks/{id}` | 查看反馈详情（含回复）|

**提交举报请求体**：
```json
{
  "target_type": "asset",
  "target_id": 12345,
  "category_code": "pornographic",
  "description": "图片含有裸露内容",
  "is_anonymous": true,
  "evidence_keys": ["report/2026/06/11/uuid1.png"]
}
```

**响应**：
```json
{
  "code": 200,
  "data": {
    "report_id": 67890,
    "status": "pending",
    "auto_hidden": true,
    "target_hidden": true,
    "created_at": 1718123456789
  }
}
```

**错误响应**：
```json
{ "code": 50004, "message": "您已举报过该对象，请等待处理" }
```

> **证据上传**：客户端先调用 `GET /api/v1/assets/oss/signature?type=asset` 直传 OSS，再把返回的 `key` 提交给本接口。

### 5.2 后台 API（Vue3 后台调用，路径前缀 `/api/admin/moderation`）

| Method & Path | 说明 |
|---------------|------|
| `GET  /api/admin/moderation/reports?status=&category=&target_type=&keyword=&page=&page_size=` | 举报工单列表 |
| `GET  /api/admin/moderation/reports/{id}` | 举报详情 |
| `POST /api/admin/moderation/reports/{id}/claim` | 认领 |
| `POST /api/admin/moderation/reports/{id}/release` | 释放认领 |
| `POST /api/admin/moderation/reports/{id}/actions` | 执行审核动作 |
| `GET  /api/admin/moderation/feedbacks?status=&category=&keyword=&page=&page_size=` | 反馈列表 |
| `GET  /api/admin/moderation/feedbacks/{id}` | 反馈详情 |
| `POST /api/admin/moderation/feedbacks/{id}/claim` | 认领反馈 |
| `POST /api/admin/moderation/feedbacks/{id}/reply` | 回复（→ replied）|
| `POST /api/admin/moderation/feedbacks/{id}/close` | 关闭 |
| `POST /api/admin/moderation/feedbacks/{id}/archive` | 归档 |
| `GET/POST/PUT/DELETE /api/admin/moderation/report-categories` | 举报分类 CRUD |
| `GET/POST/PUT/DELETE /api/admin/moderation/feedback-categories` | 反馈分类 CRUD |
| `GET  /api/admin/moderation/stats` | 看板：今日待处理/平均处理时长/分类分布 |

**执行审核动作请求**：
```json
{
  "action": "takedown",
  "note": "图片含裸露，已下架",
  "send_notification": true
}
```

---

## 6. 关键流程

### 6.1 用户提交举报（含自动隐藏）

```
用户点击"举报"
   │
   ▼
uni-app → POST /api/v1/moderation/reports
   │
   ▼
gateway → moderationService.SubmitReport()
   │
   ├─ 1. 验证：target_type 合法、分类启用、description ≤ 500 字、evidence ≤ 5 张
   ├─ 2. 验证：目标对象存在（assetService.GetAssetRPC / userService.GetUserRPC）
   ├─ 3. 防重复检查：同 (reporter, target, type) 在 pending/reviewing/auto_hidden 已有？
   │       有 → 返回 50004 错误
   ├─ 4. 写入 reports 表（status='pending'，snapshot 拿当前对象信息）
   ├─ 5. 写 report_evidence（OSS keys）
   ├─ 6. Redis Lua 计数（独立用户才 INCR）：
   │       首次计数 → 检查 counter >= threshold (默认 5)
   │       └─ 达到 → 触发自动隐藏：
   │             ① UPDATE reports WHERE target=... AND status='pending' 
   │                SET status='auto_hidden', is_auto_hidden=true
   │             ② INSERT INTO moderation_target_status
   │                (asset, is_hidden=true, source='auto', source_report_id=...)
   │             ③ 发通知给被举报方："您的内容被多人举报已自动隐藏"
   ├─ 7. 返回 {report_id, status, auto_hidden, target_hidden, created_at}
```

### 6.2 后台审核流程

```
审核员登录后台 → 列表页 (筛选 status=pending OR auto_hidden)
   │
   ▼
详情 → GET /api/admin/moderation/reports/{id}
   │
   ▼
认领 → POST /api/admin/moderation/reports/{id}/claim
   │   UPDATE reports SET status='reviewing', updated_at=now
   │   WHERE id=? AND status IN ('pending','auto_hidden')
   │   affected=1 才返回成功
   │
   ▼
查看证据、目标快照、举报人、流水
   │
   ▼
执行动作 → POST /api/admin/moderation/reports/{id}/actions
   │
   ├─ takedown（藏品/描述词/用户内容）:
   │     UPSERT moderation_target_status (is_hidden=true, source='admin', ...)
   │     UPDATE reports SET status='resolved', resolved_action='takedown', ...
   │     发通知给被举报方
   │
   ├─ ban（用户）:
   │     UPSERT moderation_target_status (is_banned=true, source='admin', ...)
   │     UPDATE reports SET status='resolved', resolved_action='ban', ...
   │     发通知给被封禁用户
   │
   ├─ warn（用户）:
   │     UPSERT moderation_target_status (is_warned=true, source='admin', ...)
   │     UPDATE reports SET status='resolved', resolved_action='warn', ...
   │     发站内信给用户
   │
   ├─ dismiss（驳回）:
   │     如果当前 auto_hidden：UPSERT is_hidden=false（解除隐藏）
   │     UPDATE reports SET status='dismissed', resolved_action='dismissed', ...
   │     发通知给举报人："您的举报已驳回"
   │
   └─ 写 moderation_actions 流水 + admin_audit_logs
```

### 6.3 反馈流程

```
用户提交反馈 → POST /api/v1/moderation/feedbacks
   │  moderationService 写 feedbacks (status='pending')
   ▼
后台列表 → GET /api/admin/moderation/feedbacks
   ▼
认领 → POST /api/admin/moderation/feedbacks/{id}/claim
   ▼
回复 → POST /api/admin/moderation/feedbacks/{id}/reply
   │  body: { content: "..." }
   │  UPDATE feedbacks SET status='replied', reply_content=?, replied_by=?, replied_at=now
   │  发通知给反馈人
```

### 6.4 自动隐藏 Lua 脚本

```lua
-- KEYS[1]=counter, KEYS[2]=user_marker, KEYS[3]=lock
-- ARGV[1]=threshold, ARGV[2]=ttl_counter, ARGV[3]=ttl_marker
local first = redis.call('SET', KEYS[2], '1', 'NX', 'EX', ARGV[3])
if not first then
  return {0, tonumber(redis.call('GET', KEYS[1]) or '0')}
end
local n = redis.call('INCR', KEYS[1])
if n == 1 then
  redis.call('EXPIRE', KEYS[1], ARGV[2])
end
if n >= tonumber(ARGV[1]) then
  return {1, n}
end
return {0, n}
```

返回 `{triggered, count}`：triggered=1 时上层触发自动隐藏。

---

## 7. 错误码

| 码 | 含义 | HTTP |
|----|------|------|
| 50001 | 举报分类不存在 | 400 |
| 50002 | 反馈分类不存在 | 400 |
| 50003 | 目标对象不存在 | 404 |
| 50004 | 同一对象已举报过（未结案）| 429 |
| 50005 | 描述过长（>500 字）| 400 |
| 50006 | 证据图超限（>5 张）| 400 |
| 50007 | 工单不存在 | 404 |
| 50008 | 工单已被他人认领 | 409 |
| 50009 | 工单已结案 | 400 |
| 50010 | 管理员权限不足 | 403 |

---

## 8. 通知机制

复用 `notificationService` 模块，注册 5 个模板：

| 事件 | 接收方 | 模板名 | 渠道 |
|------|--------|--------|------|
| 举报状态变更为 resolved/dismissed | 举报人 | `report_resolved` | 站内信 + 通知中心 |
| 举报成立 + takedown | 被举报方 | `report_takedown_notice` | 站内信 |
| 举报成立 + ban | 被举报用户 | `report_ban_notice` | 站内信 + 短信 |
| 举报成立 + warn | 被举报用户 | `report_warn_notice` | 站内信 |
| 反馈被回复 | 反馈人 | `feedback_replied` | 站内信 + 通知中心 |

> 模板字段：`{reporter_nickname, target_type, target_id, action, reason, related_url}`

---

## 9. 安全与防护

### 9.1 防护机制

| 机制 | 实现 |
|------|------|
| 防重复举报 | DB 局部唯一索引 `uk_reports_reporter_target_pending`（结案后允许再次举报）|
| 防 Redis 计数重复 | Lua 脚本用 `user_marker` SETNX 保证独立用户才 INCR |
| 防自动隐藏并发 | Redis 短锁 `mod:report:lock:*` 5s |
| 证据图校验 | OSS 签名接口限定目录 `report/` 和 `feedback/` 前缀 |
| 描述长度 | 服务端校验 ≤ 500 字（DB 字段 VARCHAR(500)）|
| 证据图数量 | 服务端校验 ≤ 5 张 |
| 匿名保护 | `is_anonymous=true` 时：`reporter_id` 仍记录但 API 响应中不返回给被举报方；后台仅对超级管理员可见 |

### 9.2 数据隔离

- 客户端 JWT 仅可看自己的举报/反馈（`reporter_id = current_user_id`）
- 后台 JWT 走 `TopFans-activity` 现有 `verify_token`，所有接口都需 `Depends(verify_token)`
- 后续如要分级权限（仅超管可恢复隐藏等），在 JWT payload 加 `role` 字段

### 9.3 数据保留

- `reports` / `feedbacks` 永久保留（合规需要）
- `moderation_actions` 永久保留（审计）
- `moderation_target_status` UPSERT 保留最新状态，历史可查 `moderation_actions`

---

## 10. 实施步骤

### 阶段 1：数据库（topfans 库）
- 1.1 写迁移 `D:\shanghai\topfans\backend\migrations\2026_06_11_010_moderation_tables.sql`
- 1.2 包含 8 张表 + 索引 + 默认分类种子数据
- 1.3 末尾必须 `SELECT setval('xxx_id_seq', (SELECT MAX(id) FROM xxx))`（CLAUDE.md 强制）
- 1.4 在 `backend/scripts/` 加 Go 脚本生成种子数据（带序列重置）

### 阶段 2：Go moderationService（topfans）
- 2.1 `D:\shanghai\topfans\backend\services\moderationService\` 新建目录
  - `main.go` / `config/` / `repository/` / `service/` / `provider/` / `client/` / `go.mod` / `start.sh`
  - 复用 socialService 类似的分层
- 2.2 `D:\shanghai\topfans\backend\proto\moderation\moderation.proto`
  - `SubmitReportRequest/Response`
  - `ListMyReportsRequest/Response`
  - `GetReportRequest/Response`
  - `GetReportCategoriesRequest/Response`
  - `SubmitFeedbackRequest/Response`
  - `ListMyFeedbacksRequest/Response`
  - `GetFeedbackRequest/Response`
  - `GetFeedbackCategoriesRequest/Response`
- 2.3 `D:\shanghai\topfans\backend\pkg\proto\moderation\` 编译生成 `.pb.go`
- 2.4 `D:\shanghai\topfans\backend\pkg\models\moderation.go` ORM 模型
- 2.5 `D:\shanghai\topfans\backend\services\moderationService\repository\moderation_repository.go` 数据访问
- 2.6 `D:\shanghai\topfans\backend\services\moderationService\service\`:
  - `report_service.go`
  - `feedback_service.go`
  - `category_service.go`
  - `auto_hide_service.go`（含 Redis Lua 脚本）
- 2.7 `D:\shanghai\topfans\backend\services\moderationService\client\`:
  - `asset_client.go`（验证目标存在）
  - `user_client.go`（验证用户/封禁查询）
- 2.8 `D:\shanghai\topfans\backend\services\moderationService\provider\social_provider.go` Dubbo 注册
- 2.9 `D:\shanghai\topfans\backend\go.work` 加入新服务
- 2.10 Gateway 层：
  - `D:\shanghai\topfans\backend\gateway\controller\moderation_controller.go`
  - `D:\shanghai\topfans\backend\gateway\dto\moderation_dto.go`
  - `D:\shanghai\topfans\backend\gateway\dto\moderation_converter.go`
  - `D:\shanghai\topfans\backend\gateway\router\router.go` 注册 `/api/v1/moderation/*`

### 阶段 3：TopFans-Activity 后台 API（FastAPI）
- 3.1 `D:\shanghai\TopFans-activity\backend\models\moderation.py` SQLAlchemy ORM（与 PG 表结构对应）
- 3.2 `D:\shanghai\TopFans-activity\backend\schemas\moderation.py` Pydantic 模型
- 3.3 `D:\shanghai\TopFans-activity\backend\crud\moderation_crud.py` 数据库操作
  - `list_reports(filters, page) / get_report_detail(id) / claim_report(id) / execute_action(id, action, ...) / list_categories() / upsert_category() / ...`
- 3.4 `D:\shanghai\TopFans-activity\backend\handlers\moderation_admin.py` 路由层
  - 复用现有 `verify_token` 中间件
- 3.5 `D:\shanghai\TopFans-activity\backend\router\__init__.py` 注册路由
- 3.6 数据库迁移（如 ORM 与 PG 表不一致时）：
  - `D:\shanghai\TopFans-activity\backend\migrations\010_moderation_init.sql`（如果用 SQLAlchemy create_all 可省略）

### 阶段 4：后台前端 (Vue3)
- 4.1 `D:\shanghai\TopFans-activity\frontend\src\api\moderation.js` axios 封装
  - `getReports()` / `getReportDetail()` / `claimReport()` / `executeAction()` / ... 
  - `getReportCategories()` / `createCategory()` / `updateCategory()` / `deleteCategory()` / ...
- 4.2 `D:\shanghai\TopFans-activity\frontend\src\views\moderation\`
  - `ReportList.vue` 举报工单列表（筛选：状态/分类/目标类型/关键词）
  - `ReportDetail.vue` 举报详情（证据图、目标快照、举报人、流水）+ 审核动作按钮
  - `FeedbackList.vue` 反馈列表
  - `FeedbackDetail.vue` 反馈详情 + 回复表单
  - `ReportCategoryConfig.vue` 举报分类 CRUD
  - `FeedbackCategoryConfig.vue` 反馈分类 CRUD
  - `Dashboard.vue` 审核看板（可选）
- 4.3 `D:\shanghai\TopFans-activity\frontend\src\router\index.js` 加路由
  - `/moderation/reports`
  - `/moderation/reports/:id`
  - `/moderation/feedbacks`
  - `/moderation/feedbacks/:id`
  - `/moderation/categories/report`
  - `/moderation/categories/feedback`
- 4.4 菜单注册（按 `Layout.vue` 现成结构）
- 4.5 Element Plus 组件复用：el-table / el-form / el-dialog / el-image / el-tag / el-pagination

### 阶段 5：客户端 uni-app
- 5.1 `D:\shanghai\topfans\frontend\utils\api.js` 加：
  - `getReportCategoriesApi()` / `submitReportApi(payload)` / `getMyReportsApi()` / `getMyReportDetailApi(id)`
  - `getFeedbackCategoriesApi()` / `submitFeedbackApi(payload)` / `getMyFeedbacksApi()` / `getMyFeedbackDetailApi(id)`
- 5.2 `D:\shanghai\topfans\frontend\components\ReportModal.vue` 通用举报弹窗
  - props: `targetType, targetId, targetName`
  - 表单：分类单选 + 描述 textarea + 证据图上传（最多 5 张）+ 匿名开关
  - 调 `submitReportApi`，成功后提示"已提交"+ 自动隐藏提示
- 5.3 在以下位置接入 `ReportModal`：
  - 藏品详情页 (`NftDetailModal.vue` 等) 长按或"..."菜单
  - 用户主页（粉丝身份下）"..."菜单
  - 描述词展示组件（如果有）的"..."菜单
- 5.4 `D:\shanghai\topfans\frontend\pages\profile\feedback.vue` 意见反馈页
  - 复用 `ReportModal` 的 evidence 上传组件
  - 表单：分类下拉 + 标题 + 内容 + 联系方式（可选） + 截图
- 5.5 `D:\shanghai\topfans\frontend\pages\profile\myReports.vue` 我的举报列表
- 5.6 `D:\shanghai\topfans\frontend\pages\profile\myFeedbacks.vue` 我的反馈列表
- 5.7 页面间跳转：从"我的" → 各项入口

### 阶段 6：业务服务读路径加 JOIN（按需展开）
- 6.1 `D:\shanghai\topfans\backend\services\assetService\repository\` 藏品查询
  - 详情/列表 SQL：`LEFT JOIN moderation_target_status ON target_type='asset' AND target_id=assets.id WHERE COALESCE(is_hidden, false) = false`
- 6.2 `D:\shanghai\topfans\backend\services\userService\repository\` 用户校验
  - 登录/操作校验：`LEFT JOIN ... ON target_type='user' AND target_id=users.id WHERE COALESCE(is_banned, false) = false`
- 6.3 描述词相关服务（`aiChatService` 或新）查询时同样 JOIN
- 6.4 性能优化（如果热路径压力变大）：
  - Redis 缓存 `mod:status:cache:{target_type}:{target_id}` TTL 60s
  - 命中即跳过 JOIN

### 阶段 7：通知与测试
- 7.1 通知模板注册到 `notificationService`（5 个模板）
- 7.2 Go 单元测试
  - `report_service_test.go` 防重复、自动隐藏触发
  - `feedback_service_test.go` 状态机
  - `auto_hide_service_test.go` Lua 脚本逻辑
- 7.3 FastAPI 单元测试
  - `test_moderation_admin.py` 列表/详情/认领/动作
  - 鉴权测试（无 token 401）
- 7.4 集成测试
  - 端到端：提交举报 → 后台审核 → 状态变更 → 用户收到通知
  - 自动隐藏：5 个独立用户举报 → 自动隐藏 + 状态表写入
- 7.5 前端联调
  - uni-app → gateway → Go service
  - Vue3 后台 → FastAPI → PG

---

## 11. 附录

### 11.1 配置文件

在 `D:\shanghai\topfans\backend\services\moderationService\config\moderation_config.go`：
```go
type ModerationConfig struct {
    AutoHideThreshold int           // 默认 5
    CounterTTL        time.Duration // 7 天
    UserMarkerTTL     time.Duration // 24h
    LockTTL           time.Duration // 5s
    MaxDescriptionLen int           // 500
    MaxEvidenceCount  int           // 5
}
```

### 11.2 跨服务调用清单

| 调用方 | 被调服务 | 触发时机 | 失败处理 |
|--------|----------|----------|----------|
| moderationService | assetService.GetAssetRPC | 提交举报验证目标 | 返回 50003 |
| moderationService | userService.GetUserRPC | 提交举报验证用户 | 返回 50003 |
| moderationService | notificationService | 触发自动隐藏后通知 | 仅日志，不影响主流程 |
| TopFans-Activity | (无 — 仅读写 DB) | - | - |
| assetService | (无 — 仅读 DB) | - | - |
| userService | (无 — 仅读 DB) | - | - |

### 11.3 监控指标（建议）

- `moderation.report.submitted.count` (counter, tags: target_type, category_code)
- `moderation.report.auto_hidden.count` (counter)
- `moderation.report.resolve.duration` (histogram, 从 created_at 到 resolved_at)
- `moderation.feedback.reply.duration` (histogram)
- `moderation.actions.failed.count` (counter, tags: action_type, error)

### 11.4 变更历史

| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-06-11 | Claude | 初始设计 |

---

**📝 设计方案已确认，可以开始实现！** ✅