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

8.6 KiB
Raw Blame History

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