Add project documentation and specs

2026-03-21 10:13:45 +08:00
parent e76f0828b9
commit 3a7f4174ab
20 changed files with 11179 additions and 0 deletions
--- a/docs/superpowers/specs/2026-03-21-forum-redesign-design.md
+++ b/docs/superpowers/specs/2026-03-21-forum-redesign-design.md
@@ -0,0 +1,473 @@
+# 交互广场重新设计
+
+## 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生成摘要 → 前端展示
+```