220 lines
6.7 KiB
Markdown
220 lines
6.7 KiB
Markdown
# 前端项目共识文档 (CONSENSUS)
|
||
|
||
## 任务名称
|
||
frontend-vue3
|
||
|
||
## 需求描述
|
||
在项目根目录下创建名为 `frontend` 的前端项目文件夹，使用 Vue3 架构构建简易前端页面，实现所有后端 API 功能。
|
||
|
||
## 技术实现方案
|
||
|
||
### 核心技术栈
|
||
- **框架**: Vue 3.3+ (Composition API)
|
||
- **构建工具**: Vite 5.x
|
||
- **UI组件库**: Element Plus 2.x
|
||
- **HTTP客户端**: Axios 1.x
|
||
- **路由管理**: Vue Router 4.x
|
||
- **CSS方案**: Element Plus + 少量自定义样式
|
||
|
||
### 项目结构
|
||
```
|
||
frontend/
|
||
├── public/
|
||
├── src/
|
||
│ ├── api/ # API调用封装
|
||
│ │ ├── client.js # Axios实例配置
|
||
│ │ ├── models.js # 模型管理API
|
||
│ │ ├── kb.js # 知识库API
|
||
│ │ ├── conversations.js # 对话API
|
||
│ │ └── agent.js # Agent API
|
||
│ ├── components/ # 公共组件
|
||
│ ├── views/ # 页面组件
|
||
│ │ ├── Models.vue # 模型管理页
|
||
│ │ ├── KnowledgeBase.vue # 知识库页
|
||
│ │ ├── Conversations.vue # 对话列表页
|
||
│ │ ├── Chat.vue # 聊天页
|
||
│ │ └── Agent.vue # Agent执行页
|
||
│ ├── router/ # 路由配置
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── App.vue # 根组件
|
||
│ └── main.js # 入口文件
|
||
├── .env.development # 开发环境配置
|
||
├── .env.production # 生产环境配置
|
||
├── vite.config.js # Vite配置
|
||
├── package.json # 依赖管理
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
### 路由设计
|
||
```
|
||
/ # 首页（重定向到/models）
|
||
/models # 模型管理
|
||
/knowledge-base # 知识库管理
|
||
/conversations # 对话列表
|
||
/conversations/:id/chat # 具体会话聊天页
|
||
/agent # Agent执行
|
||
```
|
||
|
||
### API集成方案
|
||
**Base URL**: `http://localhost:8000/api/v1` (通过环境变量配置)
|
||
|
||
**API模块映射**:
|
||
1. **模型管理** (`/models`)
|
||
- 列表展示（支持类型筛选：llm/embedding）
|
||
- 创建模型配置表单
|
||
- 编辑/删除操作
|
||
- 设置默认模型
|
||
|
||
2. **知识库管理** (`/kb`)
|
||
- 知识库列表
|
||
- 创建知识库
|
||
- 文档摄取（仅显示提交成功）
|
||
- 向量检索（查询界面）
|
||
- 状态查看（文档数量、索引状态）
|
||
- 删除知识库
|
||
|
||
3. **对话管理** (`/conversations`)
|
||
- 会话列表
|
||
- 创建会话
|
||
- 聊天界面（支持RAG切换）
|
||
- 消息历史（分页加载，limit/offset）
|
||
- 删除会话
|
||
|
||
4. **Agent执行** (`/agent`)
|
||
- 任务输入表单
|
||
- 执行结果展示
|
||
- 工具调用日志（自动展示）
|
||
|
||
### 技术约束
|
||
1. **环境配置**
|
||
- API_BASE_URL 通过 `.env` 文件配置
|
||
- 不提交 `.env.local` 到版本控制
|
||
|
||
2. **错误处理**
|
||
- HTTP 错误统一拦截（Axios interceptor）
|
||
- 业务错误详细展示（ElMessage）
|
||
- 表单验证使用 Element Plus 规则
|
||
|
||
3. **状态管理**
|
||
- 不使用 Pinia（组件级状态足够）
|
||
- 跨页面数据通过路由参数传递
|
||
|
||
4. **分页策略**
|
||
- 对话消息：limit=50, offset支持
|
||
- 其他列表暂不分页（数据量小）
|
||
|
||
## 功能边界
|
||
|
||
### 已确认实现 ✅
|
||
1. **文件夹命名**: `frontend`
|
||
2. **文档摄取**: 仅显示提交成功，不追踪任务状态
|
||
3. **对话历史**: 分页加载（limit/offset）
|
||
4. **Agent日志**: 执行后自动展示
|
||
5. **错误处理**: 详细错误信息展示
|
||
|
||
### 明确不包含 ❌
|
||
- 用户认证和权限管理
|
||
- 复杂UI动画
|
||
- 单元测试和E2E测试
|
||
- 国际化多语言
|
||
- 数据持久化到localStorage
|
||
- 任务状态轮询机制
|
||
|
||
## 验收标准
|
||
|
||
### 功能完整性
|
||
- [ ] 所有API接口都有对应的前端调用
|
||
- [ ] 模型管理：CRUD + 列表筛选 + 默认模型设置
|
||
- [ ] 知识库：CRUD + 文档摄取 + 向量查询 + 状态查看
|
||
- [ ] 对话：创建会话 + 发送消息 + 分页历史 + RAG切换
|
||
- [ ] Agent：任务执行 + 结果展示 + 日志自动加载
|
||
|
||
### 用户体验
|
||
- [ ] 页面布局清晰，左侧菜单导航
|
||
- [ ] 表单验证完整，错误提示明确
|
||
- [ ] Loading状态可见（ElLoading）
|
||
- [ ] 操作成功/失败 Toast 提示（ElMessage）
|
||
- [ ] 响应式布局（适配常见屏幕尺寸）
|
||
|
||
### 代码质量
|
||
- [ ] 遵循 Vue3 Composition API 规范
|
||
- [ ] API 调用统一封装在 `src/api/`
|
||
- [ ] 组件拆分合理，单一职责
|
||
- [ ] 环境变量正确配置（.env.development/.env.production）
|
||
- [ ] 无硬编码敏感信息
|
||
|
||
### 部署就绪
|
||
- [ ] `npm install` 成功安装依赖
|
||
- [ ] `npm run dev` 启动开发服务器（默认5173端口）
|
||
- [ ] `npm run build` 成功构建生产包
|
||
- [ ] README 包含启动说明和环境要求
|
||
|
||
## 技术风险及缓解
|
||
|
||
### 风险1: CORS问题
|
||
- **影响**: 前端无法调用后端API
|
||
- **缓解**: 后端已配置 `allow_origins=["*"]`，开发环境无需额外配置
|
||
|
||
### 风险2: API响应格式差异
|
||
- **影响**: 文档与实际接口不一致
|
||
- **缓解**: 先实现核心功能，发现问题后快速调整
|
||
|
||
### 风险3: 异步任务状态
|
||
- **影响**: 文档摄取后无法确认完成状态
|
||
- **缓解**: 提供手动刷新按钮，用户可重新查询状态
|
||
|
||
### 风险4: 分页参数边界
|
||
- **影响**: offset/limit 边界值处理不当
|
||
- **缓解**: 前端做边界检查，防止无效请求
|
||
|
||
## 交付清单
|
||
|
||
### 代码文件
|
||
1. 完整的 Vue3 项目（frontend/ 文件夹）
|
||
2. API 封装模块（5个文件）
|
||
3. 页面组件（5个核心页面）
|
||
4. 路由配置文件
|
||
5. Axios 拦截器配置
|
||
|
||
### 配置文件
|
||
1. `.env.development`（开发环境API地址）
|
||
2. `.env.production`（生产环境API地址，使用占位符）
|
||
3. `vite.config.js`（Vite构建配置）
|
||
4. `package.json`（依赖锁定）
|
||
|
||
### 文档
|
||
1. `frontend/README.md`（项目启动说明）
|
||
2. 环境配置说明
|
||
3. API 调用示例（可选）
|
||
|
||
## 验收检查清单
|
||
|
||
### 启动验证
|
||
- [ ] 后端服务运行在 http://localhost:8000
|
||
- [ ] 前端项目 `npm run dev` 成功启动
|
||
- [ ] 浏览器访问前端无控制台错误
|
||
- [ ] 左侧菜单可正常导航
|
||
|
||
### 功能验证
|
||
- [ ] 创建一个 LLM 模型配置
|
||
- [ ] 创建一个知识库并摄取文档
|
||
- [ ] 查询知识库返回结果
|
||
- [ ] 创建会话并发送消息
|
||
- [ ] 执行 Agent 任务并查看日志
|
||
|
||
### 错误处理验证
|
||
- [ ] 输入无效数据提交表单，显示验证错误
|
||
- [ ] 后端返回 4xx/5xx，显示错误 Toast
|
||
- [ ] 网络断开时，显示连接错误
|
||
|
||
## 后续优化建议（当前不实现）
|
||
1. 添加任务状态轮询（需后端支持）
|
||
2. 实现用户认证和会话管理
|
||
3. 添加数据缓存机制
|
||
4. 优化大列表虚拟滚动
|
||
5. 添加单元测试覆盖
|
||
|
||
---
|
||
|
||
**共识确认完成，进入架构设计阶段。**
|