X-Agents/teams/chat_history_plan.md

# 对话内容记录实现计划

> 创建时间：2026-03-13 11:30
> 计划周期：2026-03-13 ~ 2026-03-15

## 目标
在 Chat 页面创建新对话时，持久化记录对话内容，支持历史会话查看和刷新页面不丢失。

## 一、数据库设计

### 1. 会话表 (chat_sessions)
```sql
CREATE TABLE IF NOT EXISTS chat_sessions (
    id VARCHAR(191) PRIMARY KEY,
    user_id VARCHAR(191) NOT NULL,
    agent_id VARCHAR(191) NOT NULL,
    title VARCHAR(255) NOT NULL,
    model_id VARCHAR(191),
    status VARCHAR(20) DEFAULT 'active',  -- active/archived
    created_at DATETIME(3),
    updated_at DATETIME(3),
    INDEX idx_sessions_user (user_id),
    INDEX idx_sessions_agent (agent_id),
    INDEX idx_sessions_updated (updated_at DESC)
);
```

### 2. 消息表 (chat_messages)
```sql
CREATE TABLE IF NOT EXISTS chat_messages (
    id VARCHAR(191) PRIMARY KEY,
    session_id VARCHAR(191) NOT NULL,
    role VARCHAR(20) NOT NULL,  -- user/assistant/system
    content TEXT NOT NULL,
    tokens_used INT DEFAULT 0,
    duration_ms INT DEFAULT 0,
    metadata TEXT,  -- JSON格式存储额外信息
    created_at DATETIME(3),
    INDEX idx_messages_session (session_id),
    INDEX idx_messages_created (created_at)
);
```

## 二、后端接口设计

### 1. 会话管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /chat/sessions | 创建新会话 |
| GET | /chat/sessions | 获取用户会话列表 |
| GET | /chat/sessions/:id | 获取会话详情(含消息) |
| PUT | /chat/sessions/:id | 更新会话(如标题) |
| DELETE | /chat/sessions/:id | 删除会话 |

### 2. 消息管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /chat/sessions/:id/messages | 获取会话消息历史 |
| POST | /chat/messages | 记录单条消息(可选) |

## 三、实现步骤

### 阶段一：后端 (小尧、小陈)
- [ ] 1. 创建 chat_sessions 和 chat_messages 表的 GORM 模型
- [ ] 2. 添加数据库表初始化代码到 main.go
- [ ] 3. 实现 SessionRepository (会话 CRUD)
- [ ] 4. 实现 MessageRepository (消息 CRUD)
- [ ] 5. 创建 ChatSessionHandler 和 ChatMessageHandler
- [ ] 6. 注册路由并测试接口

### 阶段二：Python 服务 (小泽、小明)
- [ ] 1. 修改 api/routes.py 接入后端会话服务
- [ ] 2. 每次对话结束后调用后端保存消息
- [ ] 3. 支持历史消息加载(从后端获取)
- [ ] 4. 异常处理和重试机制

### 阶段三：前端 (小荣、狗蛋)
- [ ] 1. 创建 useChatSession composable
- [ ] 2. 新建对话时调用后端创建会话
- [ ] 3. 发送消息时持久化到后端
- [ ] 4. 加载历史会话和消息
- [ ] 5. 会话列表展示和切换

## 四、详细时间计划

### 阶段一：后端开发 (2026-03-13 ~ 2026-03-13)
| 日期 | 任务 | 负责人 |
|------|------|--------|
| 03-13 下午 | 创建 chat_sessions 和 chat_messages 表的 GORM 模型 | 小尧 |
| 03-13 下午 | 添加数据库表初始化代码到 main.go | 小尧 |
| 03-13 下午 | 实现 SessionRepository (会话 CRUD) | 小尧 |
| 03-13 下午 | 实现 MessageRepository (消息 CRUD) | 小陈 |
| 03-13 下午 | 创建 ChatSessionHandler 和 ChatMessageHandler | 小陈 |
| 03-13 下午 | 注册路由并测试接口 | 小陈 |

### 阶段二：Python 服务接入 (2026-03-14)
| 日期 | 任务 | 负责人 |
|------|------|--------|
| 03-14 上午 | 修改 api/routes.py 接入后端会话服务 | 小泽 |
| 03-14 上午 | 每次对话结束后调用后端保存消息 | 小泽 |
| 03-14 下午 | 支持历史消息加载(从后端获取) | 小明 |
| 03-14 下午 | 异常处理和重试机制 | 小明 |

### 阶段三：前端对接 (2026-03-14 ~ 2026-03-15)
| 日期 | 任务 | 负责人 |
|------|------|--------|
| 03-14 下午 | 创建 useChatSession composable | 小荣 |
| 03-14 下午 | 新建对话时调用后端创建会话 | 小荣 |
| 03-15 上午 | 发送消息时持久化到后端 | 小荣 |
| 03-15 上午 | 加载历史会话和消息 | 狗蛋 |
| 03-15 下午 | 会话列表展示和切换 | 狗蛋 |

## 五、技术细节

### 前端消息流程
```
1. 用户点击"新建对话"
   → 调用 POST /chat/sessions 创建会话
   → 保存 sessionId 到状态

2. 用户发送消息
   → 前端发送消息到 Python 服务
   → Python 服务返回响应后
   → 前端调用 POST /chat/messages 保存用户消息
   → 前端调用 POST /chat/messages 保存 AI 响应

3. 加载历史会话
   → 调用 GET /chat/sessions 获取会话列表
   → 选择会话后调用 GET /chat/sessions/:id/messages 获取消息
```

### 消息结构
```typescript
interface ChatMessage {
  id: string
  session_id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  tokens_used?: number
  duration_ms?: number
  metadata?: Record<string, any>
  created_at: string
}
```

## 五、分工汇总

| 人员 | 任务 | 阶段 |
|------|------|------|
| 小尧 | 后端 - 会话/消息模型和 Repository | 阶段一 |
| 小陈 | 后端 - Handler 和路由注册 | 阶段一 |
| 小泽 | Python - 接入后端会话服务 | 阶段二 |
| 小明 | Python - 历史消息加载 | 阶段二 |
| 小荣 | 前端 - 会话管理和消息持久化 | 阶段三 |
| 狗蛋 | 前端 - UI 对接和测试 | 阶段三 |

## 六、待确认问题
1. 是否需要支持消息撤回/编辑？
2. 会话标题是否需要 AI 自动生成还是用户手动输入？
3. 是否需要消息搜索功能？