# 前端项目共识文档 (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. 添加单元测试覆盖

---

**共识确认完成，进入架构设计阶段。**