# 交互广场重新设计

## 1. 概述与目标

将现有的论坛（交互广场）从传统的帖子/回复模式，重构为三个AI驱动的智能板块：
1. **AI学习板块** - 模型分析用户活动，学习客观知识并加入知识图谱，向用户汇报学习成果
2. **AI建议板块** - 基于用户习惯和数据，提供个性化建议
3. **AI交互板块** - 用户发起学习主题，或AI主动探索补充知识

## 2. 设计风格

沿用项目现有的深色赛博朋克/终端风格：
- 背景：`var(--bg-void)` 深空黑
- 强调色：紫色 `#a855f7` (用于交互广场专属色调)
- 卡片背景：`var(--bg-card)`
- 边框：`1px solid var(--border-dim)`，hover时发光
- 字体：等宽字体 `var(--font-mono)`，标题用 `var(--font-display)`

## 3. 页面结构

```
┌─────────────────────────────────────────────────────────────┐
│  // INTERACTIVE PLAZA                         [页面标题]    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [MODEL LEARNING]  AI学习板块                         │   │
│  │ AI分析你的活动，学习知识并汇报                        │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ • 今日学习摘要                                      │   │
│  │ • 学习历史时间线                                    │   │
│  │ • 知识图谱更新统计                                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [SUGGESTIONS]  AI建议板块                           │   │
│  │ 基于你的习惯提供个性化建议                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ • 知识补充建议                                      │   │
│  │ • 效率优化建议                                      │   │
│  │ • 技能深耕建议                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ [INTERACTIVE]  AI交互学习板块                        │   │
│  │ 用户发起学习主题，AI主动探索                         │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ • 用户发起的学习主题                                │   │
│  │ • AI主动学习的内容                                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 4. 功能详情

### 4.1 AI学习板块 (MODEL LEARNING)

**数据来源：**
- 对话记录（`messages` 表，Message模型）- 分析对话内容提取概念
- 看板任务（`tasks` 表，Task模型）- 识别技术栈和工作流程
- 知识库（`documents`, `kg_nodes` 表）- 补充知识缺口

**学习流程：**
```
定时任务触发 → 分析近期活动 → 提取概念/术语/事实
→ 存入知识图谱(KGNode) → 生成学习报告 → 存入learning_records表
```

**数据库扩展：**

```python
# 新增 learning_records 表
# 继承 app.models.base.BaseModel，自动获得 id, created_at, updated_at
from app.models.base import BaseModel

class LearningRecord(BaseModel):
    __tablename__ = "learning_records"

    user_id = Column(String(36), ForeignKey("users.id"), nullable=False, index=True)
    learning_type = Column(String(50), nullable=False)  # concept, technology, workflow
    topic = Column(String(500), nullable=False)  # 学习主题
    summary = Column(Text, nullable=False)  # AI生成的学习摘要
    source = Column(String(50), nullable=False)  # conversation, kanban, knowledge
    source_ids = Column(JSON, nullable=True)  # 来源ID列表，如 {conversation_ids: [...], task_ids: [...]}
    kg_nodes_created = Column(JSON, nullable=True)  # 创建的KGNode ID列表
```

**KGNode实体类型扩展：**
- `learned_concept` - 从对话中学到的概念
- `technology` - 识别出的技术栈
- `workflow` - 从看板任务中提取的工作流程

**前端展示：**

1. **今日学习摘要卡片**
   - AI生成的自然语言总结
   - 示例："今日学习了依赖注入和异步编程两个概念，它们都来自你关于FastAPI的讨论"
   - 显示来源标签：对话/看板/知识库

2. **学习历史时间线**
   - 垂直时间线布局
   - 每条记录显示：时间、主题、摘要
   - 点击展开查看详情

3. **知识图谱更新统计**
   - 今日新增节点数
   - 今日新建关系数
   - 迷你柱状图显示各类别占比（可复用 MiniBarChart）

### 4.2 AI建议板块 (SUGGESTIONS)

**建议类型：**

1. **知识补充建议 (knowledge)**
   - 检测知识图谱薄弱领域
   - 基于用户提问推断知识缺口
   - 示例："你的知识图谱在'微服务架构'领域较为薄弱，建议深入学习"

2. **效率优化建议 (efficiency)**
   - 分析用户使用模式
   - 推荐最佳实践
   - 示例："你通常在下午工作效率最高，建议将复杂任务安排在这个时段"

3. **技能深耕建议 (skill)**
   - 基于高频话题
   - 推荐深入学习方向
   - 示例："你最近频繁讨论API设计，建议学习REST最佳实践和GraphQL"

**数据库扩展：**

```python
# 新增 suggestions 表
from app.models.base import BaseModel

class Suggestion(BaseModel):
    __tablename__ = "suggestions"

    user_id = Column(String(36), ForeignKey("users.id"), nullable=False, index=True)
    suggestion_type = Column(String(50), nullable=False)  # knowledge, efficiency, skill
    title = Column(String(500), nullable=False)  # 建议标题
    content = Column(Text, nullable=False)  # 建议内容
    source_data = Column(JSON, nullable=True)  # 分析依据，如 {knowledge_gaps: [...], usage_patterns: {...}}
    is_read = Column(Boolean, default=False)  # 是否已读
    is_dismissed = Column(Boolean, default=False)  # 是否忽略
```

**前端展示：**
- 卡片列表布局
- 每个建议显示：图标、类型标签、标题、内容
- 右侧显示建议来源分析
- 提供"查看详情"和"忽略"按钮

### 4.3 AI交互板块 (INTERACTIVE)

**用户发起学习：**

1. 用户输入想学习的主题
2. AI分析主题，搜索知识库
3. 如有需要，AI主动抓取外部资源
4. 生成学习报告
5. 自动存入知识图谱
6. 在交互板块展示

**数据库扩展：**

```python
# 新增 interactive_topics 表
from app.models.base import BaseModel

class InteractiveTopic(BaseModel):
    __tablename__ = "interactive_topics"

    user_id = Column(String(36), ForeignKey("users.id"), nullable=False, index=True)
    topic = Column(String(500), nullable=False)  # 学习主题
    status = Column(String(50), nullable=False)  # pending, learning, completed, failed
    result = Column(Text, nullable=True)  # 学习结果/报告
    kg_nodes_created = Column(JSON, nullable=True)  # 创建的KGNode ID列表
    source = Column(String(50), nullable=False)  # user_initiated, ai_proactive
    completed_at = Column(DateTime, nullable=True)
```

**AI主动学习：**

1. AI分析用户历史提问
2. 发现知识缺口或关联主题
3. 主动学习并生成报告
4. 在交互板块标记为"AI主动"

**前端展示：**
- 两个子区块：用户发起 / AI主动
- 输入框："让AI学习 [主题]"
- 正在进行的学习任务显示进度
- 已完成的学习显示结果摘要

## 5. API 设计

### 5.1 后端接口

```
GET  /api/forum/learning/summary
     - 获取今日学习摘要
     - 返回: { summary, records[], stats{ nodes_created, edges_created } }

GET  /api/forum/learning/history?page=1&limit=20
     - 获取学习历史
     - 返回: { records[], total }

GET  /api/forum/suggestions
     - 获取所有建议
     - 返回: { suggestions[] }

GET  /api/forum/suggestions/{id}
     - 获取单个建议详情
     - 返回: Suggestion

PATCH /api/forum/suggestions/{id}/read
     - 标记建议为已读

DELETE /api/forum/suggestions/{id}/dismiss
     - 忽略/删除建议

GET  /api/forum/interactive/topics
     - 获取交互主题列表
     - 返回: { user_initiated[], ai_proactive[] }

POST /api/forum/interactive/learn
     - 用户发起学习
     - Body: { topic: string }
     - 返回: { topic_id, status }

GET  /api/forum/interactive/topics/{id}
     - 获取学习主题详情/结果
```

### 5.2 前端API

```typescript
// TypeScript 类型定义
interface LearningSummary {
  summary: string
  records: LearningRecord[]
  stats: {
    nodes_created: number
    edges_created: number
  }
}

interface LearningRecord {
  id: string
  learning_type: 'concept' | 'technology' | 'workflow'
  topic: string
  summary: string
  source: string
  source_ids?: { conversation_ids?: string[]; task_ids?: string[] }
  kg_nodes_created?: string[]
  created_at: string
}

interface Suggestion {
  id: string
  suggestion_type: 'knowledge' | 'efficiency' | 'skill'
  title: string
  content: string
  source_data?: Record<string, any>
  is_read: boolean
  is_dismissed: boolean
  created_at: string
}

interface InteractiveTopic {
  id: string
  topic: string
  status: 'pending' | 'learning' | 'completed' | 'failed'
  result?: string
  kg_nodes_created?: string[]
  source: 'user_initiated' | 'ai_proactive'
  created_at: string
  completed_at?: string
}

// API 方法
const forumApi = {
  // learning
  fetchLearningSummary(): Promise<LearningSummary>,
  fetchLearningHistory(params: { page: number, limit: number }): Promise<{ records: LearningRecord[], total: number }>,

  // suggestions
  fetchSuggestions(): Promise<Suggestion[]>,
  getSuggestion(id: string): Promise<Suggestion>,
  markSuggestionRead(id: string): Promise<void>,
  dismissSuggestion(id: string): Promise<void>,

  // interactive
  fetchInteractiveTopics(): Promise<{ user_initiated: InteractiveTopic[], ai_proactive: InteractiveTopic[] }>,
  initiateLearning(topic: string): Promise<InteractiveTopic>,
  getTopicDetail(id: string): Promise<InteractiveTopic>,
}
```

## 6. 组件结构

```
frontend/src/views/ForumView.vue     # 主页面，三板块布局
frontend/src/components/forum/
├── LearningSection.vue              # AI学习板块
│   ├── LearningSummaryCard.vue      # 今日摘要卡片
│   ├── LearningTimeline.vue         # 学习历史时间线
│   └── LearningStats.vue           # 图谱更新统计（复用MiniBarChart）
├── SuggestionSection.vue            # AI建议板块
│   ├── SuggestionCard.vue          # 建议卡片
│   └── SuggestionList.vue          # 建议列表
└── InteractiveSection.vue           # AI交互板块
    ├── LearningInput.vue            # 学习主题输入框
    ├── UserInitiatedList.vue        # 用户发起列表
    └── AIProactiveList.vue          # AI主动列表

# 新增通用组件
frontend/src/components/forum/MiniDonutChart.vue   # 环形图（用于知识类别占比）
```

## 7. 服务层

### 7.1 LearningService

```python
from app.core.llm import get_llm_client

class LearningService:
    def __init__(self, db: AsyncSession):
        self.llm = get_llm_client()

    async def generate_daily_summary(user_id: str) -> str:
        """分析用户今日活动，生成学习摘要"""
        # 使用 LLM 分析提取的概念，生成自然语言摘要
        concepts = await self.extract_concepts(...)
        prompt = f"根据以下学习内容生成简短摘要：{concepts}"
        return await self.llm.chat(prompt)

    async def extract_concepts_from_conversations(user_id: str, since: datetime) -> list[dict]:
        """从对话中提取概念"""

    async def identify_technologies_from_kanban(user_id: str) -> list[dict]:
        """从看板任务中识别技术栈"""

    async def create_kg_nodes(user_id: str, learnings: list[dict]) -> list[str]:
        """创建知识图谱节点"""

    async def record_learning(...) -> LearningRecord:
        """记录学习成果"""
```

### 7.2 SuggestionService

```python
class SuggestionService:
    def __init__(self, db: AsyncSession):
        self.llm = get_llm_client()

    async def generate_suggestions(user_id: str) -> list[Suggestion]:
        """生成个性化建议"""
        # 分析知识缺口、使用模式、技能机会
        gaps = await self.analyze_knowledge_gaps(user_id)
        patterns = await self.analyze_usage_patterns(user_id)
        skills = await self.analyze_skill_opportunities(user_id)

        # 使用 LLM 生成建议
        prompt = f"基于以下分析生成建议：知识缺口{gaps}，使用模式{patterns}，技能机会{skills}"
        return await self.llm.chat(prompt)

    async def analyze_knowledge_gaps(user_id: str) -> list[dict]:
        """分析知识图谱缺口"""

    async def analyze_usage_patterns(user_id: str) -> dict:
        """分析使用模式"""

    async def identify_skill_opportunities(user_id: str) -> list[dict]:
        """识别技能提升机会"""
```

### 7.3 InteractiveService

```python
class InteractiveService:
    def __init__(self, db: AsyncSession):
        self.llm = get_llm_client()

    async def initiate_learning(user_id: str, topic: str) -> InteractiveTopic:
        """用户发起学习"""

    async def execute_learning(topic_id: str) -> dict:
        """执行学习任务：
        1. 搜索知识库相关节点
        2. 使用 LLM 深入学习主题
        3. 生成学习报告
        4. 创建 KGNode
        5. 更新 topic 状态
        """
        topic = await self.get_topic(topic_id)
        content = await self.research_topic(topic.topic)
        report = await self.generate_learning_report(topic, content)
        await self.create_kg_nodes_from_report(report)
        await self.update_topic_status(topic_id, 'completed', report)

    async def generate_learning_report(self, topic: InteractiveTopic, content: str) -> str:
        """使用 LLM 生成结构化学习报告"""
```

## 8. 定时任务

每日凌晨生成学习报告：
- 分析昨日用户活动
- 提取新概念和技术栈
- 更新知识图谱
- 生成学习摘要存入数据库

**集成方式：** 使用项目现有的 `scheduler_service.py`

```python
# 在 scheduler_service.py 的 start_scheduler() 中添加
from app.services.learning_service import LearningService

async def daily_learning_job():
    """每日凌晨0:30生成学习报告"""
    from app.database import get_db_session

    async for db in get_db_session():
        service = LearningService(db)
        users = await get_all_active_users(db)
        for user in users:
            await service.generate_and_record_daily_learning(user.id)
        break

# 在 start_scheduler() 中注册
scheduler.add_job(daily_learning_job, "cron", hour=0, minute=30, id="daily_learning")
```

## 9. 错误处理

| 场景 | 处理 |
|------|------|
| 无活动数据 | 显示"今日暂无学习成果"，不生成空记录 |
| 知识图谱更新失败 | 回滚学习记录，标记为失败状态 |
| AI生成失败 | 记录原始数据，标记需要重试 |
| 用户发起学习主题为空 | 前端验证拦截，不发送请求 |

## 10. 访问控制

所有板块需要用户登录后访问：
- 未登录用户显示"请先登录"提示
- 不发送无效API请求
- 保持页面结构完整

## 11. 技术实现

**前端：**
- Vue 3 + TypeScript
- 复用现有组件样式（StatsView.vue模式）
- CSS实现迷你图表
- lucide-vue-next图标

**后端：**
- FastAPI + SQLAlchemy
- 复用现有数据库连接
- 新增三个Service类
- 复用现有认证机制

**数据流：**
```
用户活动 → LearningService分析 → KGNode创建 → LearningRecord存储
                                    ↓
                              AI生成摘要 → 前端展示
```