library-picturebook-activity/docs/design/super-admin/content-management.md

# 超管端内容管理模块 — 设计方案

> 所属端：超管端
> 状态：P0 已实现并优化
> 创建日期：2026-03-27
> 最后更新：2026-04-09

---

## 1. 背景

用户端升级为 UGC 绘本创作社区后，超管端需要新增**内容管理**一级菜单，承担内容审核和安全治理职能。

---

## 2. 菜单结构

```
内容管理（新增一级菜单）
├── 作品审核        — P0，审核用户发布的作品
├── 作品管理        — P0，全平台已发布作品的查看/下架/置顶
├── 标签管理        — P0，作品标签/分类的维护
├── 评论审核        — P1，审核用户评论
└── 举报处理        — P1，处理用户举报
```

---

## 3. 作品审核（P0）

### 3.1 审核流程

```
用户点击"发布" → status 变为 pending_review
  → 机器预审（敏感词检测 + 图片安全检测）→ 标记预审结果
  → 进入人工审核队列
  → 审核员操作：
      通过 → status 变为 published，通知用户
      拒绝 → status 变为 rejected + 拒绝原因，通知用户
```

### 3.2 页面设计

```
┌─ 标题卡片 ──────────────────────────────────────────────┐
│  作品审核                                                │
└─────────────────────────────────────────────────────────┘

┌─ 统计卡片 ──────────────────────────────────────────────┐
│ [待审核 28] [今日已审 56] [今日通过 50] [今日拒绝 6]      │
└─────────────────────────────────────────────────────────┘

┌─ 筛选栏 ────────────────────────────────────────────────┐
│ 审核状态:[下拉] 提交时间:[日期范围] 作者:[______]         │
│ 机器预审:[下拉]                       [搜索] [重置]      │
└─────────────────────────────────────────────────────────┘

┌─ 审核队列表格 ──────────────────────────────────────────┐
│ 封面 | 作品名称 | 页数 | 作者 | 标签 | 机器预审 |        │
│      | 提交时间 | 审核状态 | 操作                        │
└─────────────────────────────────────────────────────────┘
```

### 3.3 表格列

| 列 | 宽度 | 说明 |
|----|------|------|
| 封面 | 80 | 缩略图 |
| 作品名称 | 180 | 标题，可点击预览 |
| 页数 | 60 | 绘本页数 |
| 作者 | 120 | 昵称，点击可查看作者信息 |
| 标签 | 140 | Tag 列表 |
| 机器预审 | 90 | Tag：安全（绿）/ 疑似违规（红）/ 未检测（灰）|
| 提交时间 | 150 | YYYY-MM-DD HH:mm |
| 审核状态 | 90 | Tag：待审核（橙）/ 已通过（绿）/ 已拒绝（红）|
| 操作 | 180 | 快捷通过 / 快捷拒绝 / 查看详情 |

### 3.4 审核详情 Drawer

点击"查看详情"打开右侧 Drawer：

```
作品信息区
├── 作品名称 / 标签 / 可见性设置
├── 作者信息（昵称 / 账号 / 是否子女账号）
├── 提交时间
└── 机器预审结果（安全/疑似违规 + 标记原因）

绘本内容预览区
├── 封面大图
├── 内页翻页浏览（每页：插图 + 文字 + 播放配音按钮）
└── 页码指示器（1/8）

审核操作区
├── [通过] 按钮
├── [拒绝] 按钮 → 展开拒绝原因选择
│   ├── ○ 含不适宜未成年人的内容
│   ├── ○ 含个人隐私信息（姓名/地址/电话）
│   ├── ○ 涉嫌抄袭/侵权
│   ├── ○ 内容质量不符合发布标准
│   └── ○ 其他：[自定义填写]
└── 审核备注（可选文本框）
```

### 3.5 快捷操作

- 列表中"快捷通过"按钮：一键通过，无需打开 Drawer
- 列表中"快捷拒绝"按钮：弹出拒绝原因选择 Popover，选择后直接拒绝
- 支持键盘快捷键：Drawer 中按 A 通过、按 R 拒绝、按 → 下一个（提升审核效率）

### 3.6 后端 API

```
GET    /api/content-review/works              — 审核队列列表
  参数：page, pageSize, status(pending/approved/rejected), startTime, endTime, keyword, machineResult
GET    /api/content-review/works/stats         — 审核统计（待审核/今日已审/今日通过/今日拒绝）
GET    /api/content-review/works/:id           — 审核详情（含绘本分页内容）
POST   /api/content-review/works/:id/approve   — 通过
POST   /api/content-review/works/:id/reject    — 拒绝（body: { reason, note? }）
GET    /api/content-review/logs                — 审核操作日志
```

---

## 4. 作品管理（P0）

管理全平台已发布的作品，可查看数据、下架违规内容、推荐优质作品。

### 4.1 页面设计

```
┌─ 标题卡片 ──────────────────────────────────────────────┐
│  作品管理                                                │
└─────────────────────────────────────────────────────────┘

┌─ 统计卡片 ──────────────────────────────────────────────┐
│ [总作品数 520] [今日新增 12] [累计浏览 8.5万] [已下架 3]  │
└─────────────────────────────────────────────────────────┘

┌─ 筛选栏 ────────────────────────────────────────────────┐
│ 作品/作者:[______] 标签:[下拉] 发布时间:[日期范围]        │
│ 排序:[最新/最热/浏览最多]                [搜索] [重置]    │
└─────────────────────────────────────────────────────────┘

┌─ 作品表格 ──────────────────────────────────────────────┐
│ 封面 | 作品名称 | 作者 | 标签 | 浏览 | 点赞 | 收藏 |    │
│      | 评论 | 发布时间 | 状态 | 操作                     │
└─────────────────────────────────────────────────────────┘
```

### 4.2 表格列

| 列 | 宽度 | 说明 |
|----|------|------|
| 封面 | 80 | 缩略图 |
| 作品名称 | 180 | 标题 |
| 作者 | 120 | 昵称 |
| 标签 | 140 | Tag 列表 |
| 浏览 | 70 | viewCount |
| 点赞 | 70 | likeCount |
| 收藏 | 70 | favoriteCount |
| 评论 | 70 | commentCount |
| 发布时间 | 150 | |
| 状态 | 80 | Tag：正常（绿）/ 已下架（红）|
| 操作 | 140 | 查看详情 / 下架 或 恢复 / 置顶推荐 |

### 4.3 操作说明

| 操作 | 说明 |
|------|------|
| 查看详情 | Drawer 展示绘本内容 + 作者信息 + 互动数据 |
| 下架 | 弹窗确认 + 选择下架原因，status 改为 taken_down，通知用户 |
| 恢复 | 已下架的作品恢复为 published |
| 置顶推荐 | 标记为推荐作品，在广场优先展示（P2 可做推荐配置页面） |

### 4.4 后端 API

```
GET    /api/content-management/works           — 已发布作品列表
  参数：page, pageSize, keyword, tagId, sortBy(latest/hot/views), startTime, endTime, status(published/taken_down)
GET    /api/content-management/works/stats      — 统计（总数/今日新增/累计浏览/已下架）
GET    /api/content-management/works/:id        — 作品详情
POST   /api/content-management/works/:id/takedown  — 下架（body: { reason }）
POST   /api/content-management/works/:id/restore   — 恢复
POST   /api/content-management/works/:id/recommend  — 置顶推荐/取消推荐
```

---

## 5. 标签管理（P0）

维护作品标签/分类体系，用户发布作品时选择标签。

### 5.1 页面设计

```
┌─ 标题卡片 ──────────────────────────────────────────────┐
│  标签管理                                    [新增标签]   │
└─────────────────────────────────────────────────────────┘

┌─ 标签表格 ──────────────────────────────────────────────┐
│ 标签名称 | 分类 | 使用次数 | 排序 | 状态 | 操作          │
└─────────────────────────────────────────────────────────┘
```

### 5.2 表格列

| 列 | 宽度 | 说明 |
|----|------|------|
| 标签名称 | 150 | |
| 分类 | 120 | 一级分类（如：主题/风格/情感）|
| 使用次数 | 100 | 有多少作品使用了该标签 |
| 排序 | 80 | 数字，影响用户端展示顺序 |
| 状态 | 80 | Tag：启用 / 禁用 |
| 操作 | 150 | 编辑 / 启用或禁用 / 删除 |

### 5.3 新增/编辑弹窗

```
标签名称：[______]
所属分类：[下拉选择 / 新建分类]
排序权重：[数字]
状态：    [启用/禁用]
```

### 5.4 后端 API

```
GET    /api/tags                     — 标签列表（超管端，含使用统计）
POST   /api/tags                     — 创建标签
PUT    /api/tags/:id                 — 编辑标签
DELETE /api/tags/:id                 — 删除标签（无作品使用时才可删除）
PATCH  /api/tags/:id/status          — 启用/禁用
GET    /api/tags/categories          — 标签分类列表
POST   /api/tags/categories          — 创建分类
```

---

## 6. 评论审核（P1）

### 6.1 页面设计

```
┌─ 标题卡片 ──────────────────────────────────────────────┐
│  评论审核                                                │
└─────────────────────────────────────────────────────────┘

┌─ 统计卡片 ──────────────────────────────────────────────┐
│ [待审核 15] [今日已审 42] [今日通过 38] [今日拒绝 4]      │
└─────────────────────────────────────────────────────────┘

┌─ 筛选栏 ────────────────────────────────────────────────┐
│ 审核状态:[下拉] 提交时间:[日期范围] 评论者:[______]       │
│                                        [搜索] [重置]     │
└─────────────────────────────────────────────────────────┘

┌─ 审核队列表格 ──────────────────────────────────────────┐
│ 评论内容 | 评论者 | 所属作品 | 机器预审 |                │
│ 提交时间 | 审核状态 | 操作                               │
└─────────────────────────────────────────────────────────┘
```

### 6.2 表格列

| 列 | 宽度 | 说明 |
|----|------|------|
| 评论内容 | 250 | 评论文本，超长省略 |
| 评论者 | 120 | 昵称 |
| 所属作品 | 160 | 作品名称，可点击跳转 |
| 机器预审 | 90 | Tag：安全/疑似违规 |
| 提交时间 | 150 | |
| 审核状态 | 90 | Tag |
| 操作 | 160 | 通过 / 拒绝 / 查看上下文 |

支持批量操作：勾选多条 → 批量通过 / 批量拒绝

### 6.3 后端 API

```
GET    /api/content-review/comments            — 评论审核队列
GET    /api/content-review/comments/stats       — 统计
POST   /api/content-review/comments/:id/approve — 通过
POST   /api/content-review/comments/:id/reject  — 拒绝
POST   /api/content-review/comments/batch       — 批量操作（body: { ids, action }）
```

---

## 7. 举报处理（P1）

### 7.1 页面设计

```
┌─ 标题卡片 ──────────────────────────────────────────────┐
│  举报处理                                                │
└─────────────────────────────────────────────────────────┘

┌─ 统计卡片 ──────────────────────────────────────────────┐
│ [待处理 8] [今日已处理 12] [已忽略 3]                     │
└─────────────────────────────────────────────────────────┘

┌─ 筛选栏 ────────────────────────────────────────────────┐
│ 举报类型:[下拉] 处理状态:[下拉] 举报时间:[日期范围]       │
│                                        [搜索] [重置]     │
└─────────────────────────────────────────────────────────┘

┌─ 举报队列表格 ──────────────────────────────────────────┐
│ 举报类型 | 举报原因 | 被举报内容摘要 | 举报人 |           │
│ 被举报人 | 举报时间 | 处理状态 | 操作                     │
└─────────────────────────────────────────────────────────┘
```

### 7.2 处理操作

点击"处理"打开 Drawer：

```
举报信息
├── 举报类型（作品/评论/用户）
├── 举报原因
├── 举报人信息
├── 举报时间

被举报内容
├── 作品：展示绘本预览
├── 评论：展示评论内容+上下文
├── 用户：展示用户主页信息

处理操作
├── [下架内容] — 将被举报的作品/评论下架
├── [警告用户] — 向被举报用户发送警告通知
├── [禁用账号] — 禁用被举报用户的账号
├── [忽略举报] — 举报不成立，不做处理
└── 处理备注：[文本框]
```

### 7.3 后端 API

```
GET    /api/content-review/reports             — 举报队列
GET    /api/content-review/reports/stats        — 统计
GET    /api/content-review/reports/:id          — 举报详情
POST   /api/content-review/reports/:id/handle   — 处理举报
  body: { action: 'takedown'|'warn'|'ban'|'ignore', note? }
```

---

## 8. 实施记录

### Day5 (2026-03-31) — P0 全面优化

#### 作品审核
- [x] 基础功能：统计卡片、筛选、审核队列表格、拒绝弹窗（预设理由+自定义）、详情 Drawer（绘本翻页预览）
- [x] 批量审核：支持勾选待审核作品批量通过/批量拒绝
- [x] 撤销机制：已通过/已拒绝的作品支持撤销恢复为待审核（操作列常驻按钮+二次确认）
- [x] 操作日志：详情 Drawer 底部展示审核操作时间线（通过/拒绝/下架/恢复/撤销）
- [x] 体验优化：默认筛选待审核、表格加描述预览列+审核时间列、详情加「上一个/下一个」导航（审核完自动跳下一个）、统计卡片点击筛选、筛选下拉自动查询
- [x] 统计 Tab 与列表一致：「今日已审/今日通过/今日拒绝」按当日 `review_time` 区间查询（`reviewStartTime`/`reviewEndTime`）；「待审核」仅 `pending_review`

#### 作品管理
- [x] 基础功能：统计卡片、筛选（关键词+状态+排序）、作品表格、推荐/下架/恢复操作
- [x] 筛选修复：状态筛选支持 published+taken_down+推荐中，排序参数传后端真正生效
- [x] 下架原因：下架改为弹窗选择原因（4个预设+自定义），取代写死的「管理员下架」
- [x] 详情 Drawer：补全作品描述、标签、绘本预览、操作按钮（推荐/下架/恢复）、操作日志
- [x] 推荐联动：推荐作品在公众端广场顶部「编辑推荐」横栏展示，下架时自动取消推荐
- [x] 体验优化：统计卡片可点击筛选、表格加描述预览列、取消推荐二次确认、筛选自动查询
- [x] 统计 Tab 与列表一致：「今日新增」按当日 `create_time` 区间（`startTime`/`endTime`）且含已上架+已下架；「总作品数」为全量；「累计浏览」列表按浏览量排序；「已下架」仅下架状态

#### 标签管理
- [x] 基础功能：标签 CRUD、启用/禁用、删除保护（已使用不可删）
- [x] 分类分组：标签按分类分组展示（每组有颜色标识+计数），未分类单独一组
- [x] 分类下拉：新增/编辑时分类改为下拉选择（支持选已有+创建新分类），杜绝手动输入不一致
- [x] 标签颜色：数据库新增 color 字段，10个预设色+自定义 hex，卡片左侧颜色条+用户端预览
- [x] 排序按钮：每个标签有上/下箭头，点击交换排序值并持久化
- [x] 使用次数可点击：跳转作品管理页带标签名搜索
- [x] 实时预览：新增/编辑弹窗底部实时渲染用户端标签效果

#### 新增后端 API
```
POST   /api/content-review/works/batch-approve     — 批量通过
POST   /api/content-review/works/batch-reject      — 批量拒绝
POST   /api/content-review/works/:id/revoke        — 撤销审核
GET    /api/content-review/works (新增参数)          — sortBy 排序 + isRecommended 筛选；startTime/endTime 按创建时间；reviewStartTime/reviewEndTime 按审核时间
GET    /api/public/gallery/recommended              — 推荐作品列表（公众端）
POST   /api/tags/batch-sort                         — 标签批量排序
```

**公众端广场与 `status`（实现约定）**：`t_ugc_work.status` 为整型；管理端筛选参数里的 `published` 语义对应 **`status ∈ {3, 4, 5}`**（生成完成 / 已编目 / 已配音）。公众端 `GET /public/gallery`、`/public/gallery/recommended` 仅查询上述状态且 `visibility=public`、未删除；**不得**复用赛事/作业等模块的 `PublishStatus.PUBLISHED`（字符串 `"published"`）与整型列比较。

**标签筛选**：`GET /public/gallery` 查询参数 **`tagId`**（可选，对应 `t_ugc_tag.id`）表示仅返回在 **`t_ugc_work_tag`** 中与该标签有关联的公开已上架作品；`category` 参数预留，按标签大类筛选可后续与 `t_ugc_tag.category` 对齐。

#### 数据库变更
- `work_tags` 表新增 `color` 字段（VARCHAR(20)，标签颜色）