langchain-learning-kit/docs/frontend-vue3/TODO_frontend-vue3.md

# 前端项目待办事项 (TODO)

## 项目名称
frontend-vue3

## 当前状态
✅ **项目已交付，功能完整可用**

---

## 必需配置事项

### 1. 后端服务启动 ⚠️
**优先级**: 🔴 **高** (阻塞项)

**问题**: 前端依赖后端 API，后端服务必须运行

**操作步骤**:
```bash
# 1. 确保后端服务运行在 localhost:8000
cd langchain-learning-kit
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 2. 验证后端可访问
curl http://localhost:8000/health
# 预期输出: {"status":"healthy","environment":"development"}
```

**验证方式**:
- 浏览器访问: http://localhost:8000/docs
- 应该看到 Swagger UI 文档

---

### 2. 前端环境变量配置 ⚠️
**优先级**: 🔴 **高** (阻塞项)

**问题**: 需要确认 API 地址配置正确

**操作步骤**:
```bash
cd frontend

# 1. 检查 .env.development 是否存在
cat .env.development
# 内容应为: VITE_API_BASE_URL=http://localhost:8000/api/v1

# 2. 如果文件不存在，复制示例
cp .env.example .env.development
```

**验证方式**:
- 文件存在: `frontend/.env.development`
- 内容正确: `VITE_API_BASE_URL=http://localhost:8000/api/v1`

---

### 3. 安装前端依赖 ⚠️
**优先级**: 🔴 **高** (阻塞项)

**问题**: 需要安装 npm 依赖包

**操作步骤**:
```bash
cd frontend

# 安装依赖
npm install

# 验证安装成功
npm list --depth=0
# 应该看到 vue, vue-router, axios, element-plus 等包
```

**验证方式**:
- `node_modules/` 目录存在
- `package-lock.json` 文件存在

---

## 可选配置事项

### 4. 创建初始模型配置 🟡
**优先级**: 🟡 **中** (功能依赖)

**问题**: 前端下拉框需要至少一个 LLM 和 Embedding 模型

**操作步骤**:
1. 启动前端: `cd frontend && npm run dev`
2. 访问: http://localhost:5173/models
3. 点击"创建模型"，创建以下配置:

**LLM 模型示例**:
```json
{
  "name": "gpt-4",
  "type": "llm",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "api_key": "${OPENAI_API_KEY}"
  },
  "is_default": true
}
```

**Embedding 模型示例**:
```json
{
  "name": "text-embedding-ada-002",
  "type": "embedding",
  "config": {
    "model": "text-embedding-ada-002",
    "api_key": "${OPENAI_API_KEY}"
  },
  "is_default": true
}
```

**验证方式**:
- 模型管理页面显示 2 个模型
- 其他页面的模型下拉框有可选项

---

### 5. 后端对话列表 API 补充 🟡
**优先级**: 🟡 **中** (功能缺失)

**问题**: 对话列表页面当前无法加载数据（后端未提供 `GET /conversations` 接口）

**解决方式1: 等待后端补充**
联系后端开发者补充接口:
```python
# 在 app/api/conv.py 添加
@router.get("/conversations")
def list_conversations():
    # 返回对话列表
    pass
```

**解决方式2: 临时使用创建对话**
- 对话列表页面点击"创建对话"
- 创建后会自动跳转到聊天页

**当前状态**: 前端已预留接口，使用空数组兜底

---

### 6. 生产环境部署配置 🟢
**优先级**: 🟢 **低** (生产部署)

**问题**: 生产环境需要修改 API 地址

**操作步骤**:
```bash
cd frontend

# 1. 修改生产环境配置
echo "VITE_API_BASE_URL=https://your-production-api.com/api/v1" > .env.production

# 2. 构建生产包
npm run build

# 3. 预览构建结果
npm run preview
```

**验证方式**:
- `dist/` 目录生成
- 访问 http://localhost:4173 预览

---

## 常见问题排查

### Q1: 前端启动失败
**现象**: `npm run dev` 报错

**排查步骤**:
```bash
# 1. 检查 Node.js 版本
node --version
# 需要 >= 18

# 2. 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install

# 3. 检查端口占用
lsof -i :5173  # Mac/Linux
netstat -ano | findstr :5173  # Windows
```

---

### Q2: 无法连接后端
**现象**: 页面显示"网络连接失败"

**排查步骤**:
```bash
# 1. 检查后端服务状态
curl http://localhost:8000/health

# 2. 检查环境变量
cat frontend/.env.development

# 3. 浏览器控制台查看网络请求
# 打开开发者工具 -> Network 标签
```

---

### Q3: 模型下拉框为空
**现象**: 知识库、对话页面模型选择框无内容

**排查步骤**:
```bash
# 1. 检查是否已创建模型
curl http://localhost:8000/api/v1/models

# 2. 如果为空，访问前端创建模型
# http://localhost:5173/models
```

---

### Q4: 知识库查询无结果
**现象**: 查询返回 0 条结果

**排查步骤**:
1. 确认已摄取文档 (查看状态: 文档数 > 0)
2. 确认 Embedding 模型与摄取时一致
3. 检查后端日志确认 FAISS 索引存在
4. 尝试重新摄取文档

---

## 快速启动指南

### 一键启动脚本（推荐）

**Windows (PowerShell)**:
```powershell
# 1. 启动后端 (新窗口)
Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd ..; python -m uvicorn app.main:app --reload --port 8000"

# 2. 启动前端
cd frontend
npm install
npm run dev
```

**Mac/Linux (Bash)**:
```bash
# 1. 启动后端 (后台运行)
cd ..
python -m uvicorn app.main:app --reload --port 8000 &

# 2. 启动前端
cd frontend
npm install
npm run dev
```

**访问地址**:
- 前端: http://localhost:5173
- 后端 API 文档: http://localhost:8000/docs

---

## 操作指引

### 完整使用流程

**步骤1: 创建模型配置**
1. 访问 http://localhost:5173/models
2. 创建 LLM 模型 (例如: gpt-4)
3. 创建 Embedding 模型 (例如: text-embedding-ada-002)

**步骤2: 创建知识库**
1. 访问 http://localhost:5173/knowledge-base
2. 点击"创建知识库"
3. 输入名称和描述

**步骤3: 摄取文档**
1. 在知识库列表点击"摄取文档"
2. 选择 Embedding 模型
3. 添加文档内容（支持多个）
4. 提交摄取

**步骤4: 查询知识库**
1. 点击"查询"按钮
2. 输入查询文本
3. 选择返回数量 (k 值)
4. 查看结果和相关度评分

**步骤5: 创建对话**
1. 访问 http://localhost:5173/conversations
2. 点击"创建对话"
3. 输入用户ID和标题
4. 自动跳转到聊天页

**步骤6: 聊天交互**
1. 启用/禁用 RAG 开关
2. 选择知识库和 LLM 模型
3. 输入消息并发送
4. 查看助手回复和来源信息

**步骤7: Agent 执行**
1. 访问 http://localhost:5173/agent
2. 输入任务描述
3. 选择知识库（可选）和 LLM
4. 点击"执行任务"
5. 查看结果和工具调用日志

---

## 联系支持

### 技术支持渠道
- **项目文档**: `frontend/README.md`
- **架构设计**: `docs/frontend-vue3/DESIGN_frontend-vue3.md`
- **后端 API 文档**: http://localhost:8000/docs

### 问题反馈
如遇到其他问题，请检查:
1. Node.js 版本 >= 18
2. 后端服务正常运行
3. 浏览器控制台错误信息
4. Network 面板 API 请求响应

---

**最后更新**: 2025-10-02
**状态**: ✅ 项目完成，待启动使用
**下一步**: 按照上述配置事项启动项目