python-test
/
langchain-learning-kit
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
langchain-learning-kit/docs/frontend-vue3/CONSENSUS_frontend-vue3.md

6.7 KiB
Raw Permalink Blame History

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

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