# Forum 升级执行清单

本清单用于追踪 Forum 升级计划的执行进度。

---

## 总进度

| Phase | 名称 | 状态 | 工作量 |
|-------|------|------|--------|
| F.0 | 现状与目标 | ✅ 完成 | - |
| F.1 | 数据模型升级 | ⬜ 待开始 | 2 天 |
| F.2 | API 增强与安全 | ⬜ 待开始 | 3 天 |
| F.3 | 权限系统 | ⬜ 待开始 | 3 天 |
| F.4 | AI 集成 | ⬜ 待开始 | 5 天 |
| **总计** | | | **13 天** |

---

## Phase F.1：数据模型升级

### 目标
升级 Forum 数据模型，支持多板块、标签系统、帖子元数据扩展。

### 任务清单

#### 数据库迁移
- [ ] 创建数据库迁移脚本
  - 新增 `forum_boards` 表
  - 新增 `forum_tags` 表
  - 新增 `forum_post_tags` 表
  - 新增 `forum_likes` 表
  - 新增 `forum_stats` 表
  - 扩展 `forum_posts` 表
  - 扩展 `forum_replies` 表

#### 模型实现
- [ ] 扩展 `models/forum.py`
  - [ ] 创建 `ForumBoard` 模型
  - [ ] 创建 `ForumTag` 模型
  - [ ] 创建 `ForumPostTag` 模型
  - [ ] 创建 `ForumLike` 模型
  - [ ] 创建 `ForumStats` 模型
  - [ ] 扩展 `ForumPost` 字段
  - [ ] 扩展 `ForumReply` 字段

#### Schema 实现
- [ ] 扩展 `schemas/forum.py`
  - [ ] 创建 `ForumBoardCreate/Out` Schema
  - [ ] 扩展 `ForumPostCreate/Out` Schema
  - [ ] 扩展 `ForumReplyCreate/Out` Schema
  - [ ] 创建 `ForumTagOut` Schema

#### 测试
- [ ] 编写单元测试
  - [ ] 测试 ForumBoard CRUD
  - [ ] 测试 ForumTag CRUD
  - [ ] 测试 ForumLike 功能
  - [ ] 测试 ForumStats 更新

### 产出文件
- `models/forum.py`
- `schemas/forum.py`

### 验收
- [ ] 迁移脚本可正常运行
- [ ] 所有新模型可正常创建
- [ ] Schema 验证正常工作
- [ ] 单元测试通过

---

## Phase F.2：API 增强与安全

### 目标
增强 Forum API 功能，实现文件锁、输入验证、限流、缓存。

### 任务清单

#### 基础服务
- [ ] 创建 `services/forum_service.py`
  - [ ] 实现 `ForumLockManager` 类
  - [ ] 实现 `ForumService` 类
  - [ ] 实现板块 CRUD 方法
  - [ ] 实现帖子 CRUD 方法
  - [ ] 实现回复 CRUD 方法
  - [ ] 实现点赞方法

#### 安全机制
- [ ] 实现输入验证
  - [ ] 实现 `sanitize_input` 函数
  - [ ] 实现 `validate_post_data` 函数
  - [ ] 实现配置常量
- [ ] 实现限流器
  - [ ] 实现 `RateLimiter` 类
  - [ ] 集成发帖限流
  - [ ] 集成回复限流
- [ ] 实现缓存
  - [ ] 实现 `ForumCache` 类
  - [ ] 实现帖子缓存
  - [ ] 实现标签缓存

#### API 端点
- [ ] 扩展 `routers/forum.py`
  - [ ] GET `/boards` - 列出板块
  - [ ] POST `/boards` - 创建板块
  - [ ] GET `/posts` - 分页获取帖子
  - [ ] POST `/posts` - 创建帖子
  - [ ] PATCH `/posts/{id}/pin` - 置顶
  - [ ] PATCH `/posts/{id}/lock` - 锁定
  - [ ] GET `/tags` - 列出/搜索标签
  - [ ] POST `/posts/{id}/tags` - 添加标签
  - [ ] POST `/like` - 切换点赞

#### 测试
- [ ] 编写单元测试
  - [ ] 测试 ForumLockManager
  - [ ] 测试输入验证
  - [ ] 测试限流器
  - [ ] 测试 API 端点

### 产出文件
- `services/forum_service.py`

### 验收
- [ ] 并发锁正常工作
- [ ] 输入验证可过滤危险字符
- [ ] 限流正常工作
- [ ] 缓存提升读取速度
- [ ] 所有 API 端点正常
- [ ] 单元测试通过

---

## Phase F.3：权限系统

### 目标
实现用户角色管理、板块权限控制、操作日志、积分系统。

### 任务清单

#### 用户扩展
- [ ] 扩展 `models/user.py`
  - [ ] 添加 `role` 字段
  - [ ] 添加 `forum_score` 字段
  - [ ] 添加论坛统计字段
  - [ ] 添加禁言相关字段
  - [ ] 添加 `moderated_boards` 字段

#### 权限服务
- [ ] 创建 `services/permission_service.py`
  - [ ] 实现 `UserRole` 枚举
  - [ ] 实现 `Permission` 枚举
  - [ ] 实现 `ROLE_PERMISSIONS` 映射
  - [ ] 实现 `PermissionService` 类
  - [ ] 实现 `has_permission` 方法
  - [ ] 实现 `can_edit_post` 方法
  - [ ] 实现 `can_delete_post` 方法
  - [ ] 实现 `ban_user` 方法
  - [ ] 实现 `unban_user` 方法

#### 日志系统
- [ ] 扩展 `models/forum.py`
  - [ ] 创建 `ForumLog` 模型
- [ ] 集成日志记录
  - [ ] 记录帖子操作
  - [ ] 记录回复操作
  - [ ] 记录用户操作

#### 积分服务
- [ ] 创建 `services/score_service.py`
  - [ ] 实现 `SCORE_RULES` 配置
  - [ ] 实现 `ScoreService` 类
  - [ ] 实现 `add_score` 方法
  - [ ] 实现 `get_leaderboard` 方法
  - [ ] 实现积分自动增减

#### 管理 API
- [ ] 扩展 `routers/forum.py`
  - [ ] POST `/admin/ban/{user_id}` - 禁言
  - [ ] POST `/admin/unban/{user_id}` - 解除禁言
  - [ ] GET `/admin/logs` - 查看日志
  - [ ] GET `/leaderboard` - 积分排行榜

#### 测试
- [ ] 编写单元测试
  - [ ] 测试权限检查
  - [ ] 测试禁言功能
  - [ ] 测试积分计算
  - [ ] 测试排行榜

### 产出文件
- `models/user.py`
- `models/forum.py` (ForumLog)
- `services/permission_service.py`
- `services/score_service.py`

### 验收
- [ ] 角色权限正确控制
- [ ] 禁言功能正常
- [ ] 操作日志正确记录
- [ ] 积分正确增减
- [ ] 排行榜正确排序
- [ ] 单元测试通过

---

## Phase F.4：AI 集成

### 目标
实现 AI 自动回复、摘要生成、智能打标、Agent 自主发帖。

### 任务清单

#### AI 服务
- [ ] 创建 `services/forum_ai_service.py`
  - [ ] 实现 `ForumAIConfig` 配置
  - [ ] 实现 `ForumAIService` 类
  - [ ] 实现 `generate_auto_reply` 方法
  - [ ] 实现 `_should_auto_reply` 判断
  - [ ] 实现 `generate_summary` 方法
  - [ ] 实现 `suggest_tags` 方法
  - [ ] 实现 `classify_category` 方法

#### 摘要服务
- [ ] 创建 `services/summary_service.py`
  - [ ] 实现 `SummaryService` 类
  - [ ] 实现 `get_post_summary` 方法
  - [ ] 实现 `get_thread_summary` 方法
  - [ ] 实现缓存失效

#### Agent 工具
- [ ] 创建 `agents/tools/forum_tools.py`
  - [ ] 实现 `create_forum_post` 工具
  - [ ] 实现 `reply_to_post` 工具
  - [ ] 实现 `search_forum_posts` 工具
  - [ ] 实现 `get_forum_trending` 工具
- [ ] 创建 `agents/prompts/forum_agent.py`
  - [ ] 编写 Forum Agent 提示词
  - [ ] 配置工具列表

#### 定时任务
- [ ] 创建 `tasks/forum_auto_reply.py`
  - [ ] 实现 `auto_reply_task` 函数
  - [ ] 实现 `setup_forum_scheduler` 函数

#### API 端点
- [ ] 扩展 `routers/forum.py`
  - [ ] POST `/posts/{id}/generate-summary` - 生成摘要
  - [ ] POST `/posts/suggest-tags` - 推荐标签
  - [ ] POST `/posts/classify` - 分类帖子
  - [ ] GET `/posts/{id}/ai-status` - AI 状态

#### 测试
- [ ] 编写单元测试
  - [ ] 测试自动回复生成
  - [ ] 测试摘要生成
  - [ ] 测试智能打标
  - [ ] 测试 API 端点

### 产出文件
- `services/forum_ai_service.py`
- `services/summary_service.py`
- `agents/tools/forum_tools.py`
- `agents/prompts/forum_agent.py`
- `tasks/forum_auto_reply.py`

### 验收
- [ ] AI 服务正常调用
- [ ] 自动回复正常生成
- [ ] 摘要生成正常
- [ ] 智能打标推荐
- [ ] 智能分类推荐
- [ ] Agent 工具可用
- [ ] 定时任务正常执行
- [ ] 单元测试通过

---

## 完成标准

- [ ] 所有 Phase F.1-F.4 任务完成
- [ ] 所有单元测试通过
- [ ] API 文档更新完成
- [ ] 用户文档更新完成
- [ ] 部署验证通过

---

## 风险与注意事项

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| F.4 AI 调用成本高 | 费用增加 | 设置每日调用上限 |
| 并发锁死锁 | 服务不可用 | 超时机制 + 定期清理 |
| 迁移数据丢失 | 用户流失 | 备份 + 分阶段迁移 |
| Agent 刷屏 | 用户体验下降 | 严格限流 + 人工审核 |

---

## 更新日志

| 日期 | Phase | 变更内容 |
|------|-------|----------|
| 2026-04-04 | F.0 | 创建文档 |