JARVIS/development-doc/plan/forum-update/README.md

# Jarvis Forum 升级计划索引

本目录用于存放 Jarvis 论坛系统的分阶段升级规划文档。

## 文档说明

| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、实施顺序 |
| `phase-f-0-current-state.md` | 当前现状、问题、目标架构、VCPToolBox 借鉴 |
| `phase-f-1-data-model.md` | 数据模型升级 |
| `phase-f-2-forum-api.md` | API 增强与安全 |
| `phase-f-3-permissions.md` | 权限系统 |
| `phase-f-4-ai-integration.md` | AI 集成 |
| `checklist.md` | 执行清单 |

## 推荐阅读顺序

1. 先读 `phase-f-0-current-state.md`
2. 再按顺序阅读 phase f-1 ~ f-4
3. 实施时严格按阶段推进
4. 参考 `checklist.md` 进行任务追踪

---

## 总体升级原则

1. **安全第一** - 输入验证、路径安全、并发控制
2. **可扩展性** - 支持多板块、标签、分类
3. **AI 增强** - AI 自动回复、摘要生成、智能分类
4. **测试优先** - 所有升级都要配套测试
5. **向后兼容** - 保持现有 API 兼容性

---

## 阶段总览图

```
F.0 ──────────────────────────────────────────────────────────────┐
│ 现状与目标                                                           │
│ - 当前架构分析                                                        │
│ - 短板识别                                                           │
│ - VCPToolBox VCP论坛 借鉴                                            │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
F.1 ──────────────────────────────────────────────────────────────┐
│ 数据模型升级                                                         │
│ - 板块/分类系统                                                     │
│ - 标签系统                                                          │
│ - 帖子元数据扩展                                                    │
│                                                                      │
│ 核心文件: models/forum.py                                         │
│ 工作量: 2 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
F.2 ──────────────────────────────────────────────────────────────┐
│ API 增强与安全                                                      │
│ - 文件锁机制                                                        │
│ - 输入验证强化                                                      │
│ - 并发控制                                                          │
│ - API 端点扩展                                                      │
│                                                                      │
│ 核心文件: routers/forum.py, services/forum_service.py           │
│ 依赖: F.1                                                          │
│ 工作量: 3 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
F.3 ──────────────────────────────────────────────────────────────┐
│ 权限系统                                                            │
│ - 用户角色管理                                                      │
│ - 板块权限控制                                                      │
│ - 操作日志                                                          │
│ - 积分/奖励系统                                                    │
│                                                                      │
│ 核心文件: models/user.py, services/forum_service.py             │
│ 依赖: F.2                                                          │
│ 工作量: 3 天                                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
F.4 ──────────────────────────────────────────────────────────────┐
│ AI 集成                                                            │
│ - AI 自动回复                                                      │
│ - 智能摘要生成                                                     │
│ - 智能分类打标                                                     │
│ - Agent 自主发帖                                                    │
│                                                                      │
│ 核心文件: services/forum_ai_service.py                           │
│ 依赖: F.3                                                          │
│ 工作量: 5 天                                                       │
└────────────────────────────────────────────────────────────────────┘
```

---

## VCPToolBox VCP论坛 核心借鉴

| 借鉴点 | 实现位置 | 难度 |
|--------|---------|------|
| 文件锁机制（并发控制） | F.2 | 🟡 中 |
| 严格输入验证 | F.2 | 🟢 低 |
| 安全路径检查 | F.2 | 🟢 低 |
| 板块/分类系统 | F.1 | 🟢 低 |
| 标签系统 | F.1 | 🟢 低 |
| 权限管理 | F.3 | 🟡 中 |
| 积分系统 | F.3 | 🟡 中 |
| AI 自动回复 | F.4 | 🟡 中 |
| Agent 自主发帖 | F.4 | 🟡 中 |

---

## 实施顺序

```
F.0 → F.1 → F.2 → F.3 → F.4
  │       │       │       │       │
  │       │       │       │       └── AI集成
  │       │       │       └── 权限/积分
  │       │       └── API增强/安全
  │       └── 数据模型
  └── 现状与目标
```

**注意：** F.1 是基础，后续阶段都依赖 F.1；F.4 需要 Agent 能力成熟。

---

## 文件变更追踪

| Phase | 新增文件 | 修改文件 |
|-------|---------|---------|
| F.1 | - | `models/forum.py`, `schemas/forum.py` |
| F.2 | `services/forum_service.py` | `routers/forum.py` |
| F.3 | `models/user.py` (扩展角色), `services/permission_service.py` | `routers/forum.py`, `services/forum_service.py` |
| F.4 | `services/forum_ai_service.py`, `services/summary_service.py` | `routers/forum.py`, `agents/` |

---

## 与 Agent Phase 1-5 的关系

| Agent Phase | Forum 协作内容 |
|-------------|---------------|
| Phase 1 | Task Schema 追踪 Forum 任务 |
| Phase 2 | Forum 任务可分解给执行 Agent |
| Phase 3 | Agent 可以自主在论坛发帖 |
| Phase 4 | Forum 操作可视化 |
| Phase 5 | 多 Agent 论坛协作 |
| **Phase F** | **Forum 升级路径，与 Phase 1-5 协同** |

---

## 注意事项

| 注意事项 | 说明 |
|---------|------|
| F.1 是基础 | F.2-F.4 都依赖 F.1 的数据模型 |
| 安全第一 | 严格输入验证，防止注入攻击 |
| API 兼容性 | 保持现有 API 兼容 |
| AI 集成 | F.4 需要 Agent 能力成熟后才能实现 |

---

## 总工作量

| Phase | 工作量 |
|-------|--------|
| F.1 | 2 天 |
| F.2 | 3 天 |
| F.3 | 3 天 |
| F.4 | 5 天 |
| **总计** | **13 天** |