260 lines
8.6 KiB
Markdown
260 lines
8.6 KiB
Markdown
# 前端项目对齐文档 (ALIGNMENT)
|
||
|
||
## 任务名称
|
||
frontend-vue3
|
||
|
||
## 原始需求
|
||
在本项目下创建前端项目文件夹。并针对本项目生成简易前端页面,使用Vue3架构。界面简单能实现所有接口功能即可。
|
||
|
||
## 项目上下文分析
|
||
|
||
### 后端项目特性
|
||
- **技术栈**: FastAPI + MySQL + LangChain + FAISS
|
||
- **API Base URL**: http://localhost:8000/api/v1
|
||
- **CORS**: 已启用，允许所有来源（开发环境）
|
||
- **认证**: 当前未实现认证
|
||
- **环境变量**: 使用 .env 文件管理敏感信息
|
||
|
||
### 后端API模块分析
|
||
根据 `docs/api.md` 和项目结构，后端提供以下核心功能：
|
||
|
||
#### 1. 模型管理 (/models)
|
||
- POST /models/ - 创建模型配置
|
||
- GET /models/?type={llm|embedding} - 列出模型
|
||
- GET /models/{model_id} - 获取模型详情
|
||
- PATCH /models/{model_id} - 更新模型配置
|
||
- DELETE /models/{model_id} - 删除模型
|
||
|
||
#### 2. 知识库管理 (/kb)
|
||
- POST /kb/ - 创建知识库
|
||
- GET /kb/ - 列出知识库
|
||
- GET /kb/{kb_id} - 获取知识库详情
|
||
- DELETE /kb/{kb_id} - 删除知识库
|
||
- POST /kb/{kb_id}/ingest - 摄取文档（支持后台任务）
|
||
- POST /kb/{kb_id}/query - 查询知识库（向量检索）
|
||
- GET /kb/{kb_id}/status - 获取知识库状态
|
||
|
||
#### 3. 对话管理 (/conversations)
|
||
- POST /conversations/ - 创建会话
|
||
- GET /conversations/{conversation_id} - 获取会话详情
|
||
- DELETE /conversations/{conversation_id} - 删除会话
|
||
- GET /conversations/{conversation_id}/messages - 获取消息列表（分页）
|
||
- POST /conversations/{conversation_id}/chat - 发送消息并获取回复
|
||
|
||
#### 4. Agent执行 (/agent)
|
||
- POST /agent/execute - 执行Agent任务
|
||
- GET /agent/logs/{agent_id} - 获取Agent执行日志（工具调用记录）
|
||
|
||
### 现有项目约束
|
||
- **项目根目录**: C:\work\workspace\PycharmProjects\study-work\langchain-learning-kit
|
||
- **后端端口**: 8000
|
||
- **数据存储**: data/faiss 目录用于FAISS索引
|
||
- **环境配置**: .env 文件（需要确保前端不提交敏感信息）
|
||
|
||
## 需求理解
|
||
|
||
### 核心目标
|
||
创建一个Vue3前端项目，提供简洁的UI界面，完整覆盖后端所有API功能。
|
||
|
||
### 功能范围
|
||
1. **模型管理页面**: CRUD操作，支持LLM和Embedding模型配置
|
||
2. **知识库管理页面**: 创建知识库、文档摄取、向量检索
|
||
3. **对话页面**: 多轮对话，支持RAG上下文注入
|
||
4. **Agent页面**: 执行任务，查看工具调用日志
|
||
|
||
### 技术要求
|
||
- **框架**: Vue 3 (Composition API)
|
||
- **构建工具**: Vite（推荐，轻量快速）
|
||
- **UI库**: 简洁为主（建议使用Element Plus或Naive UI）
|
||
- **HTTP客户端**: Axios
|
||
- **状态管理**: Pinia（如需要）
|
||
- **路由**: Vue Router
|
||
|
||
### 非功能要求
|
||
- **界面简洁**: 不需要复杂设计，功能优先
|
||
- **代码规范**: 遵循Vue3最佳实践
|
||
- **环境隔离**: API_BASE_URL通过环境变量配置
|
||
- **错误处理**: 统一处理HTTP错误和业务错误
|
||
|
||
## 边界确认
|
||
|
||
### 包含范围 ✅
|
||
- 创建独立的前端项目文件夹（建议命名：frontend-vue3）
|
||
- 实现所有后端API的前端调用
|
||
- 提供基本的页面布局和导航
|
||
- 实现核心交互逻辑（表单提交、数据展示、分页等）
|
||
- 基本的错误提示和加载状态
|
||
|
||
### 不包含范围 ❌
|
||
- 复杂的UI动画和视觉效果
|
||
- 用户认证和权限管理（后端未实现）
|
||
- 数据持久化到localStorage（除非必要）
|
||
- 多语言国际化
|
||
- 单元测试和E2E测试（除非明确要求）
|
||
- 生产环境优化（如CDN、懒加载优化等）
|
||
|
||
## 技术决策
|
||
|
||
### 1. 项目结构决策
|
||
**问题**: 前端项目应该放在哪里？
|
||
**决策**: 在项目根目录下创建 `frontend-vue3/` 文件夹，与后端项目平行
|
||
**理由**:
|
||
- 保持前后端分离
|
||
- 便于独立开发和部署
|
||
- 符合常见项目组织方式
|
||
|
||
### 2. UI框架选择
|
||
**问题**: 使用哪个UI组件库？
|
||
**决策**: 使用 **Element Plus**
|
||
**理由**:
|
||
- Vue3官方推荐
|
||
- 组件丰富，文档完善
|
||
- 适合快速开发管理后台
|
||
- 中文文档友好
|
||
|
||
### 3. 状态管理
|
||
**问题**: 是否需要Pinia？
|
||
**决策**: **初期不使用Pinia，使用组件级状态管理**
|
||
**理由**:
|
||
- 应用规模较小
|
||
- API调用为主，状态简单
|
||
- 可后续按需引入
|
||
|
||
### 4. 路由设计
|
||
**问题**: 如何组织页面路由？
|
||
**决策**: 使用Vue Router，采用嵌套路由
|
||
**建议路由结构**:
|
||
```
|
||
/models - 模型管理
|
||
/knowledge-base - 知识库管理
|
||
/conversations - 对话列表
|
||
/conversations/:id/chat - 具体会话
|
||
/agent - Agent执行
|
||
```
|
||
|
||
### 5. API调用封装
|
||
**问题**: 如何组织API调用代码？
|
||
**决策**: 创建 `src/api/` 目录，按模块封装
|
||
**结构**:
|
||
```
|
||
src/api/
|
||
├── client.js # Axios实例配置
|
||
├── models.js # 模型API
|
||
├── kb.js # 知识库API
|
||
├── conversations.js # 对话API
|
||
└── agent.js # Agent API
|
||
```
|
||
|
||
### 6. 环境配置
|
||
**问题**: API_BASE_URL如何配置？
|
||
**决策**: 使用Vite环境变量
|
||
```
|
||
.env.development: VITE_API_BASE_URL=http://localhost:8000/api/v1
|
||
.env.production: VITE_API_BASE_URL=<生产环境URL>
|
||
```
|
||
|
||
## 疑问澄清（需人工确认）
|
||
|
||
### 关键决策点 ⚠️
|
||
|
||
#### Q1: 前端项目文件夹命名
|
||
- **选项A**: `frontend-vue3` （明确技术栈）
|
||
- **选项B**: `frontend` （简洁）
|
||
- **选项C**: `web` （通用）
|
||
- **推荐**: **frontend-vue3** （方便未来可能的多前端共存）
|
||
|
||
#### Q2: 知识库文档摄取功能
|
||
后端支持 `background: true` 异步摄取，前端需要：
|
||
- **选项A**: 只显示提交成功，不跟踪任务状态
|
||
- **选项B**: 实现任务状态轮询（需要后端job状态API）
|
||
- **推荐**: **选项A**（简化实现，后端当前未提供job查询API）
|
||
|
||
#### Q3: 对话历史加载
|
||
后端支持分页 `limit` 和 `offset`，前端需要：
|
||
- **选项A**: 一次性加载所有消息
|
||
- **选项B**: 实现滚动加载/分页加载
|
||
- **推荐**: **选项B**（遵循最佳实践，限制初始加载量）
|
||
|
||
#### Q4: Agent日志展示
|
||
Agent执行返回 `agent_id`，日志需要单独查询：
|
||
- **选项A**: 执行后自动展示日志
|
||
- **选项B**: 提供"查看详情"按钮
|
||
- **推荐**: **选项A**（用户体验更流畅）
|
||
|
||
#### Q5: 错误处理粒度
|
||
- **选项A**: 简单的全局Toast提示
|
||
- **选项B**: 详细的错误信息展示（如表单验证错误）
|
||
- **推荐**: **选项B**（便于调试和用户理解）
|
||
|
||
## 技术实现方案
|
||
|
||
### 技术栈确定
|
||
- **核心框架**: Vue 3.3+ (Composition API)
|
||
- **构建工具**: Vite 5.x
|
||
- **UI库**: Element Plus 2.x
|
||
- **HTTP客户端**: Axios 1.x
|
||
- **路由**: Vue Router 4.x
|
||
- **CSS方案**: Element Plus内置 + 少量自定义CSS
|
||
|
||
### 开发环境要求
|
||
- Node.js 18+
|
||
- npm 9+ 或 pnpm 8+
|
||
|
||
### 集成约束
|
||
- 确保CORS配置正确（后端已配置allow_origins=["*"]）
|
||
- API调用需处理异步状态（loading, error）
|
||
- 表单验证遵循后端API契约
|
||
|
||
## 验收标准
|
||
|
||
### 功能完整性
|
||
- [ ] 所有后端API都有对应的前端调用
|
||
- [ ] 模型管理：创建、列表、详情、更新、删除
|
||
- [ ] 知识库管理：创建、列表、删除、摄取、查询、状态查看
|
||
- [ ] 对话管理：创建会话、发送消息、查看历史
|
||
- [ ] Agent执行：提交任务、查看结果和日志
|
||
|
||
### 用户体验
|
||
- [ ] 页面布局清晰，导航便捷
|
||
- [ ] 表单验证友好，错误提示明确
|
||
- [ ] 加载状态可见（Loading指示器）
|
||
- [ ] 操作反馈及时（成功/失败提示）
|
||
|
||
### 代码质量
|
||
- [ ] 遵循Vue3 Composition API规范
|
||
- [ ] API调用统一封装
|
||
- [ ] 组件结构清晰，复用性良好
|
||
- [ ] 环境配置分离（.env）
|
||
|
||
### 部署就绪
|
||
- [ ] 项目可独立构建（npm run build）
|
||
- [ ] 开发服务器可正常启动（npm run dev）
|
||
- [ ] 无硬编码的敏感信息
|
||
- [ ] README包含启动和构建说明
|
||
|
||
## 风险识别
|
||
|
||
### 技术风险
|
||
1. **后端API可能的变更**: 当前基于文档理解，实际调用可能发现不一致
|
||
- **缓解措施**: 先实现基础功能，迭代调整
|
||
|
||
2. **异步任务状态跟踪**: 文档摄取后台任务无法追踪状态
|
||
- **缓解措施**: 提供手动刷新按钮
|
||
|
||
### 依赖风险
|
||
1. **Node.js版本兼容性**: 需要Node 18+
|
||
- **缓解措施**: 在文档中明确说明
|
||
|
||
2. **UI库版本**: Element Plus可能有breaking changes
|
||
- **缓解措施**: 锁定具体版本号
|
||
|
||
## 下一步行动
|
||
等待人工确认以下关键决策：
|
||
1. 前端文件夹命名（推荐：frontend-vue3）
|
||
2. 文档摄取任务是否需要状态跟踪（推荐：否）
|
||
3. 对话历史加载方式（推荐：分页加载）
|
||
4. Agent日志展示方式（推荐：自动展示）
|
||
5. 错误处理粒度（推荐：详细展示）
|
||
|
||
**确认后将进入Architect阶段，生成详细的架构设计文档。**
|