# 云酒馆项目进度管理

> **项目定位**：面向普通用户的类酒馆 AI 角色对话平台
> **核心理念**：让不懂代码的用户也能轻松导入角色卡、配置 AI、与角色对话
> **技术栈**：Go (Gin + GORM) + Vue 3 (Element Plus) + PostgreSQL
> **开始日期**：2026-02-10
> **当前状态**：阶段四 AI 对话核心功能已完成 P0

---

## 📊 总体进度

| 阶段 | 进度 | 状态 |
|------|------|------|
| 一、基础设施 | 100% | 🟢 已完成 |
| 二、用户系统 | 100% | 🟢 已完成 |
| 三、角色卡管理 | 100% | 🟢 已完成 |
| 四、AI 接入与对话（核心） | 80% | 🟡 P0 已完成 |
| 五、用户体验优化 | 0% | ⚪ 未开始 |
| 六、部署上线 | 0% | ⚪ 未开始 |

---

## 🎯 普通用户最小功能集

> 一个普通用户打开这个平台，最基本的使用流程：

```
注册/登录 → 浏览角色广场 → 选择/导入角色卡 → 配置 AI 接口 → 开始对话
```

### 必须有（MVP）

| 功能           | 说明              | 后端    | 前端    |
|--------------|-----------------|-------|-------|
| 注册/登录        | 邮箱注册            | ✅ 已完成 | ✅ 已完成 |
| 角色广场         | 浏览公开角色卡         | ✅ 已完成 | ✅ 已完成 |
| 导入角色卡        | 支持 PNG 卡片和 JSON | ✅ 已完成 | ✅ 已完成 |
| 创建角色卡        | 简易表单创建          | ✅ 已完成 | ✅ 已完成 |
| **配置 AI 接口** | 填 API Key + 选模型 | ✅ 已完成 | ✅ 已完成 |
| **AI 对话**    | 与角色卡聊天（SSE 流式） | ✅ 已完成 | ✅ 已完成 |
| **对话记录**     | 查看历史、多轮对话       | ✅ 已完成 | ✅ 已完成 |

### 第二优先级

| 功能     | 说明           | 后端      | 前端    |
|--------|--------------|---------|-------|
| 世界书    | 角色背景设定增强     | ✅ 已完成   | ✅ 已完成 |
| 预设管理   | AI 参数预设（温度等） | 🔸 模型已有 | ❌ 待开发 |
| 收藏角色   | 收藏喜欢的角色      | 🔸 模型已有 | ❌ 待开发 |
| 消息重新生成 | 不满意可重新生成回复   | ✅ 后端已有 | ❌ 待开发 |
| 消息编辑   | 编辑已发送的消息     | ✅ 后端已有 | ❌ 待开发 |

### 后续增强（不急）

| 功能     | 说明               | 状态        |
|--------|------------------|-----------|
| 正则脚本   | 高级文本处理           | ✅ 已完成（保留） |
| 扩展系统   | SillyTavern 扩展兼容 | ✅ 已完成（保留） |
| 群聊     | 多角色群聊            | 模型已有      |
| 向量记忆   | 长期记忆增强           | 模型已有      |
| 数据导入导出 | 从原版酒馆迁移数据        | 未开始       |

---

## 🟢 阶段一：基础设施（已完成）

- [x] 数据库设计：13张核心表（用户、角色卡、对话、消息、世界书、扩展等）
- [x] Go 后端框架搭建：GVA 框架 + 分层架构
- [x] Vue 3 前端项目初始化：Element Plus + UnoCSS + TypeScript
- [x] JWT 认证中间件
- [x] CORS 跨域配置
- [x] Swagger API 文档

---

## 🟢 阶段二：用户系统（已完成）

- [x] 用户注册/登录/登出
- [x] Token 刷新机制
- [x] 用户信息获取与更新
- [x] 密码修改
- [x] 前端登录/注册页面

---

## 🟢 阶段三：角色卡管理（已完成）

- [x] 角色卡 CRUD（创建、编辑、删除）
- [x] PNG 卡片导入（SillyTavern V1/V2 格式）
- [x] JSON 格式导入导出
- [x] 公开/私密切换
- [x] 角色广场（公开角色列表 + 搜索排序）
- [x] 我的角色卡列表
- [x] 角色详情页

---

## 🟡 阶段四：AI 接入与对话（核心 — P0 已完成）

> 这是整个平台最核心的功能。P0 核心功能已全部实现。

### 4.1 AI 提供商配置 ✅

- [x] **T4.1.1** 后端：AI 提供商管理 API
  - 提供商 CRUD（OpenAI/兼容、Claude、Gemini、自定义）
  - API Key 加密存储（XOR 混淆）
  - 模型管理（预设常见模型 + 自定义添加，支持 chat/image_gen 类型）
  - 连通性测试接口（OpenAI /models、Claude /messages、Gemini /models）
  - 设为默认提供商
  - 文件：`server/service/app/provider.go`、`server/api/v1/app/provider.go`、`server/router/app/provider.go`

- [x] **T4.1.2** 前端：AI 配置页面
  - 可视化平台选择器（OpenAI/Claude/Gemini/自定义 四选一）
  - 简洁配置表单：选平台 → 填 Key → 填地址 → 测试连接
  - 模型卡片管理（预设快捷添加 + 手动添加）
  - 提供商卡片列表展示
  - 文件：`web-app-vue/src/views/provider/ProviderList.vue`、`ProviderDialog.vue`、`ModelDialog.vue`

### 4.2 对话核心功能 ✅

- [x] **T4.2.1** 后端：对话管理 API
  - 创建对话（选角色卡 → 自动发送首条消息）
  - 对话列表（按最近活跃排序，含最后一条消息预览）
  - 对话详情（加载全部历史消息）
  - 删除对话
  - 文件：`server/service/app/chat.go`、`server/api/v1/app/chat.go`、`server/router/app/chat.go`

- [x] **T4.2.2** 后端：消息发送与 AI 回复
  - 统一多提供商 AI 客户端（OpenAI/Claude/Gemini）
  - SSE 流式响应（基于 Go channel）
  - Prompt 构建（系统提示 + 角色卡描述/性格/场景/示例消息 + 历史消息）
  - Token 计数记录
  - 文件：`server/service/app/ai_client.go`

- [x] **T4.2.3** 后端：消息操作
  - 消息编辑 API
  - 消息删除 API
  - 重新生成（Regenerate）后端接口已准备
  - 文件：同 `chat.go`

### 4.3 对话前端页面 ✅

- [x] **T4.3.1** 对话列表页
  - 角色头像 + 角色名 + 最后一条消息预览 + 时间
  - 新建对话入口（弹窗选角色卡）
  - 对话删除
  - 文件：`web-app-vue/src/views/chat/ChatList.vue`

- [x] **T4.3.2** 聊天界面
  - 消息气泡样式（用户蓝色/角色灰色）
  - 输入框 + 发送按钮（Enter 发送、Shift+Enter 换行）
  - SSE 流式打字效果（逐字显示 AI 回复）
  - 角色头像和名称
  - 加载历史消息 + 自动滚动到底部
  - 简单 Markdown 渲染（粗体、斜体、代码、换行）
  - 文件：`web-app-vue/src/views/chat/ChatView.vue`

- [ ] **T4.3.3** 对话增强（P1，待开发）
  - 前端重新生成按钮
  - 前端消息编辑 UI
  - 复制消息
  - 清空对话

---

## ⚪ 阶段五：用户体验优化

- [ ] 预设管理（"创意/平衡/精确"快捷预设）
- [ ] 角色卡收藏
- [ ] 移动端适配
- [ ] 深色/浅色主题
- [ ] 消息 Markdown 渲染
- [ ] 头像上传

---

## ⚪ 阶段六：部署上线

- [ ] Docker 容器化
- [ ] Nginx 反向代理 + HTTPS
- [ ] 数据库备份策略
- [ ] 监控与日志

---

## 📦 已完成但暂不在主线的功能（代码保留）

| 功能 | 后端 | 前端 | 备注 |
|------|------|------|------|
| 世界书管理 | ✅ | ✅ | 完整 CRUD + 条目管理 |
| 正则脚本 | ✅ | ✅ | 完整正则验证和管理 |
| 扩展系统 | ✅ | ✅ | 安装/启用/设置/资源管理 |
| 扩展运行时 | ✅ | ✅ | SillyTavern 兼容层 + Shim |
| 邮件插件 | ✅ | ✅ | 邮件发送功能 |

---

## 📅 开发优先级

```
P0（必须，阻塞上线）：
  AI 提供商配置 → 对话功能 → 聊天界面 → Prompt 构建

P1（重要，上线后快速补充）：
  消息重新生成 → 消息编辑 → 预设管理 → 收藏功能

P2（后续增强）：
  群聊 → 向量记忆 → 数据迁移 → 扩展系统
```