# 前端项目对齐文档 (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阶段，生成详细的架构设计文档。**