# new-rag-chat-vue

**Repository Path**: weh_coder/new-rag-chat-vue

## Basic Information

- **Project Name**: new-rag-chat-vue
- **Description**: 本项目是一个基于 Vue 3 + Element Plus 的 RAG（检索增强生成）知识问答系统前端应用，并提供用户友好的对话界面与知识库管理功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, vite, 知识库问答

## README

# 📖 RAG Knowledge Vue — 开发文档 (Development Documentation)

> **项目版本**：1.0.0  
> **最后更新**：2026-08-11  
> **项目地址**：`rag-knowledge-base/web/rag-knowledge-vue`

---

## 1. 项目概述

本项目是一个基于 **Vue 3 + Element Plus** 的 RAG（检索增强生成）知识问答系统前端应用。提供用户友好的对话界面与知识库管理功能，核心能力包括：

- **知识库问答**：基于向量检索 + RAG 模式回答问题，附带来源卡片
- **AI 直接对话**：不经过知识库的纯对话模式
- **多会话管理**：支持会话创建、切换、重命名、删除、收藏
- **文档管理**：知识库文档的上传、版本管理、权限控制
- **用户身份切换**：支持多用户/多租户身份切换
- **流式输出**：支持 SSE 流式输出，打字机效果显示
- **本地持久化**：对话历史、会话状态自动持久化到 localStorage

---

## 2. 技术栈

### 2.1 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | ^3.5.0 | 核心框架 |
| Vue Router | ^4.5.0 | 路由管理 |
| Pinia | ^2.3.0 | 状态管理 |
| Element Plus | ^2.9.0 | UI 组件库 |
| Element Plus Icons | ^2.3.0 | 图标库 |
| Axios | ^1.8.0 | HTTP 请求库 |
| Vite 5 | ^8.0.16 | 构建工具 |
| @vitejs/plugin-vue | ^5.2.0 | Vue 支持插件 |
| unplugin-auto-import | ^19.0.0 | API 自动导入 |
| unplugin-vue-components | ^28.0.0 | 组件自动导入 |

### 2.2 项目结构

```
src/
├── main.js                    # 入口文件
├── App.vue                    # 根组件（布局：侧边栏 + 主内容区）
├── router/                    # 路由配置
│   └── index.js
├── stores/                    # Pinia 状态管理
│   ├── chat.js                # 聊天/对话存储
│   ├── conversation.js        # 会话管理存储
│   ├── knowledge.js           # 知识库文档存储
│   └── user.js                # 用户存储
├── api/                       # API 请求封装
│   ├── auth.js                # 认证 API
│   ├── chat.js                # 聊天 API (RAG 问答 / AI 对话 / SSE 流式)
│   ├── document.js            # 文档 API
│   ├── history.js             # 历史 API
│   └── index.js               # API 索引
├── components/                # 公共组件
│   ├── Chat/                  # 对话组件
│   │   ├── MessageBubble.vue  # 消息气泡组件
│   │   ├── PipelineInfo.vue   # 检索链路信息组件
│   │   ├── SourceCards.vue    # 来源卡片组件
│   │   ├── ThinkingIndicator.vue # 思考指示器
│   │   └── WelcomePanel.vue   # 欢迎页组件
│   ├── Sidebar/               # 侧边栏组件
│   │   ├── ConversationList.vue  # 会话列表
│   │   ├── DataManager.vue      # 数据管理面板
│   │   ├── DocumentList.vue     # 文档列表
│   │   ├── DocumentUpload.vue   # 文档上传
│   │   ├── GeneralSettings.vue  # 通用设置
│   │   └── UserSelector.vue     # 用户选择
│   └── index.vue               # 侧边栏主组件
├── composables/               # 组合式函数
│   ├── useSidebar.js          # 侧边栏展开/收起
│   └── useTheme.js            # 主题管理
├── utils/                     # 工具函数
│   └── msgId.js               # 全局消息 ID 生成器
├── styles/                    # 全局样式
│   └── global.css
├── auto-imports.d.ts          # 自动导入类型声明（Vite 生成）
├── components.d.ts            # 组件类型声明（Vite 生成）
└── assets/                    # 静态资源

.env                           # 环境变量配置
vite.config.js                 # Vite 配置文件
package.json                   # 项目依赖配置
index.html                     # HTML 入口
```

---

## 3. 快速开始

### 3.1 环境要求

- Node.js >= 18.0
- npm >= 9.0 或 pnpm >= 8.0

### 3.2 安装依赖

```bash
npm install
# 或
pnpm install
```

### 3.3 启动开发服务器

```bash
npm run dev
```

开发服务器启动后，访问 `http://localhost:5173`

### 3.4 构建生产版本

```bash
npm run build
```

产物输出到 `dist/` 目录。

### 3.5 预览生产构建

```bash
npm run preview
```

### 3.6 更新依赖

```bash
npm update
```

---

## 4. 关键配置说明

### 4.1 Vite 配置 (vite.config.js)

```js
import { defineConfig, resolve } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import { resolve } from 'path'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()],
      imports: ['vue', 'vue-router', 'pinia'],
      dts: 'src/auto-imports.d.ts',
    }),
    Components({
      resolvers: [ElementPlusResolver()],
      dts: 'src/components.d.ts',
    }),
  ],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),  // @ 指向 src 目录
    },
  },
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:3000',  // 后端 API 地址
        changeOrigin: true,
      },
    },
  },
})
```

**路径别名**：`@` 指向 `src` 目录，所有导入使用 `@/xxx` 形式。

**代理配置**：开发模式下，所有 `/api` 请求自动代理到 `http://127.0.0.1:3000`，用于解决开发环境跨域问题。

### 4.2 环境变量 (.env)

| 变量 | 值 | 说明 |
|------|-----|------|
| `VITE_API_BASE_URL` | `/api` | API 基础路径，通过代理转发 |

> ⚠️ 当前 `.env` 中未定义 `VITE_API_BASE_URL`，系统默认使用 `/api` 前缀。

### 4.3 Element Plus 主题配置

使用 CSS 变量定义主题颜色（通过全局 CSS 文件 `src/styles/global.css` 管理）：

| CSS 变量 | 用途 |
|----------|------|
| `--primary-color` | 主色（蓝色系） |
| `--primary-bg` | 主色背景 |
| `--bg-primary` | 页面主背景 |
| `--bg-secondary` | 卡片/面板背景 |
| `--text-primary` | 主文本色 |
| `--text-secondary` | 次文本色 |
| `--border-color` | 边框色 |
| `--border-light` | 浅边框色 |
| `--success-color` | 成功色 |
| `--danger-color` | 错误色 |
| `--info-color` | 信息色 |
| `--warning-color` | 警告色 |
| `--gradient-primary` | 主色渐变 |
| `--gradient-bg` | 页面背景渐变 |
| `--gradient-secondary` | 次色渐变 |

> 完整变量清单请参考 `src/styles/global.css`。

---

## 5. 开发规范

### 5.1 代码风格

- 使用 ES 模块语法（`import/export`）
- Vue 组件推荐使用 `<script setup>` 语法糖
- 单个文件的导入/导出不宜超过 30 行，保持函数职责单一

### 5.2 路径引用

使用 `@` 别名引用 src 下的文件：

```javascript
// 组件导入
import HelloWorld from '@/components/HelloWorld.vue'
import { useUserStore } from '@/stores/user'
import { api } from '@/api'
```

### 5.3 API 请求

所有 API 请求通过 Axios 封装，基础路径为 `/api`：

```javascript
// src/api/index.js
import axios from 'axios'

const apiClient = axios.create({
  baseURL: '/api',  // 部署时需覆盖为后端实际地址
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' },
})

export default apiClient
```

### 5.4 组件自动导入

- **Vue API 自动导入**：`ref`, `reactive`, `computed` 等无需手动导入
- **Element Plus 组件自动导入**：直接使用 `<el-button>` 等标签，无需 import
- **自定义组件**：放置在 `src/components/` 目录下，按 PascalCase 命名即可自动识别

### 5.5 异步操作处理

所有异步操作应使用 `async/await` 模式，并使用 `try/catch` 捕获错误。错误信息应通过 `ElMessage` 或 `ElMessageBox` 展示。

---

## 6. 后端对接说明

| 配置项 | 值 |
|--------|-----|
| 后端地址 | `http://127.0.0.1:3000` |
| 代理路径 | `/api` → `http://127.0.0.1:3000/api` |
| 跨域处理 | `changeOrigin: true`（开发环境代理解决） |
| 认证方式 | `Authorization: Bearer <token>` |

### 6.1 API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/chat` | POST | AI 对话（同步） |
| `/api/chat/stream` | POST | AI 对话（流式 SSE） |
| `/api/knowledge/query/:conversationId` | POST | 知识库 RAG 问答（同步） |
| `/api/knowledge/stream/:conversationId` | POST | 知识库 RAG 问答（流式 SSE） |
| `/api/knowledge/query/:conversationId` | POST | 获取知识库文档列表 |
| `/api/document` | POST | 上传文档 |
| `/api/document/:id` | PUT | 更新文档版本 |
| `/api/document/:id` | DELETE | 删除文档 |
| `/api/session` | POST | 创建会话 |
| `/api/session/:id/messages` | GET | 获取会话消息 |
| `/api/histories` | GET | 获取用户历史会话列表 |
| `/api/session/:id` | GET | 获取会话详情 |

### 6.2 认证与鉴权

- **Token**：存储于 `localStorage` 中（`rag_token`）
- **Header**：每次请求携带 `Authorization: Bearer <token>`
- **用户信息**：存储于 `localStorage` 中（`rag_user`）

### 6.3 SSE 格式

流式 API 返回的响应体为 SSE 格式，事件类型如下：

| 事件类型 | 数据结构 | 说明 |
|----------|----------|------|
| `retrieving` | `{}` | 检索开始 |
| `sources` | `{ sources, pipeline }` | 来源信息 + pipeline |
| `chunk` | `{ content }` | 答案文本片段 |
| `done` | `{ answer, sources, pipeline }` | 流结束 |
| `error` | `{ message }` | 错误 |
| `warning` | `{ message }` | 警告 |

---

## 7. 常见命令速查

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产包 |
| `npm run preview` | 预览生产构建 |
| `npm install` | 安装依赖 |
| `npm update` | 更新依赖 |

---

## 8. 部署说明

### 8.1 构建产物

执行 `npm run build` 后，产物输出到 `dist/` 目录。

### 8.2 Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /path/to/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

### 8.3 生产环境注意事项

- 确保后端服务监听在 `http://127.0.0.1:3000`
- `VITE_API_BASE_URL` 应配置为后端实际地址
- `VITE_PROXY` 仅在开发环境生效，生产环境需配置 Nginx 反向代理

---

## 9. 关键模块详解

### 9.1 聊天 Store（`src/stores/chat.js`）

管理对话核心逻辑：

- **消息管理**：维护消息列表（`messages`），支持用户/AI/系统消息
- **模式切换**：支持 `knowledge`（知识库 RAG）和 `ai`（直接对话）两种模式
- **流式/同步切换**：通过 `useStream` 状态控制流式与同步输出
- **流式输出**：通过 AbortController 控制请求取消
- **重新生成**：按消息 id 定位并重新生成单个 AI 回复
- **状态机**：`thinking` → `streaming` → `done` / `error`

### 9.2 会话 Store（`src/stores/conversation.js`）

- **会话生命周期**：创建、切换、删除、重命名、收藏
- **持久化**：会话数据自动持久化到 localStorage
- **后端同步**：与 `/api/history/*` 接口同步
- **离线降级**：后端不可用时自动降级到本地缓存

### 9.3 知识库 Store（`src/stores/knowledge.js`）

- **文档管理**：加载、上传、更新、删除文档
- **缓存**：文档列表自动缓存到 localStorage
- **权限控制**：支持公司/部门可见性

### 9.4 用户 Store（`src/stores/user.js`）

- **用户信息**：当前用户、可用用户列表
- **Token 管理**：自动持久化到 localStorage
- **会话恢复**：`restoreUser()` 从 localStorage 恢复会话

---

## 10. 数据流与状态管理

### 10.1 消息 ID 分配

全局唯一消息 ID 由 `src/utils/msgId.js` 管理，使用自增计数器确保：

1. 前端新建的消息 ID 绝对唯一
2. 后端加载的消息 ID 也经 `nextMsgId()` 重新分配
3. 避免同一会话内消息 id 冲突导致的 `Vue :key` 冲突
4. 避免后端加载的消息用 timestamp 作 id 与同秒内的 user 消息撞 id 的隐患

### 10.2 状态流转

| 状态 | 说明 |
|------|------|
| `loading` | 正在发送请求 |
| `retrieving` | 正在知识库检索 |
| `thinking` | AI 正在生成中（流式显示中） |
| `done` | 回复已完成 |
| `error` | 请求出错 |
| `streaming` | 正在流式输出中 |

---

## 11. 错误处理策略

### 11.1 请求层错误处理

所有 API 请求通过 Axios 封装，错误处理分为：

1. **网络错误**：捕获并提示用户
2. **401/403**：自动清除 Token，向上抛异常
3. **500+**：提示用户服务异常

### 11.2 缓存策略

- 对话消息本地缓存（`localStorage`）
- 文档列表本地缓存
- 会话历史本地缓存
- 知识库 Token 持久化

### 11.3 重试机制

- 流式请求自动重试机制
- 切换会话后旧请求结果被丢弃（通过 `_requestToken` 机制）

---

## 12. 性能优化

### 12.1 虚拟滚动

- 消息列表采用 `max-width: 820px` 的居中布局
- `scrollToBottom()` 仅在距底部 80px 内时才停止自动滚动

### 12.2 流式输出

- 流式模式下，使用 `AbortController` 实时中止过时请求
- 流式输出通过 SSE 逐段渲染，避免阻塞主线程

### 12.3 组件懒加载

- 路由配置使用动态 `import()` 实现组件懒加载
- 侧边栏组件通过条件渲染切换

---

## 13. 开发与调试

### 13.1 调试环境

```bash
# 查看构建产物
npm run build
# 确认 dist/ 目录生成

# 实时日志
npm run dev  # 启动开发服务器，日志输出到 console

# Vite 构建调试
npm run build -- --mode development
```

### 13.2 常用调试工具

| 工具 | 用途 |
|------|------|
| Vue DevTools | 组件树/响应式追踪 |
| Browser DevTools | Network 面板查看 API 请求 |
| Vite 构建日志 | 构建过程信息 |

### 13.3 性能监控

- 消息构建时间使用 `performance.now()` 估算
- 关键路径上的网络请求通过 `fetch` + `AbortController` 监控

---

## 14. 相关文档

- [API 文档](https://github.com/example/rag-knowledge-api)（后端 API 参考）
- [后端对接说明](https://github.com/example/rag-knowledge-api)（接口规范）
- [部署说明](https://github.com/example/rag-knowledge-api)（生产环境部署）

---

> **提示**：`auto-imports.d.ts` 和 `components.d.ts` 由 Vite 插件自动生成，无需手动编辑。

---

*文档版本：1.0.0 | 编写时间：2026-08-11*