llm-chat/.qoder/quests/run-project-fix-errors.md

# 运行项目与错误修复设计方案

## 项目概述

LLM Chat Website 是一个基于 Node.js 后端和 Vue.js 前端的全栈聊天应用，使用 pnpm workspace 进行依赖管理。项目采用现代化技术栈，包含完整的聊天功能和大语言模型集成。

## 技术架构分析

### 后端架构 (Node.js + Express)
- **框架**: Express.js 4.18.2
- **数据库**: SQLite3 5.1.6 
- **缓存**: LRU Cache 10.0.1
- **HTTP客户端**: Axios 1.6.2
- **开发工具**: Nodemon 3.0.2
- **端口**: 3000 (默认)

### 前端架构 (Vue 3)
- **框架**: Vue 3.3.8
- **构建工具**: Vite 5.0.0
- **UI框架**: Element Plus 2.4.4
- **状态管理**: Pinia 2.1.7
- **路由**: Vue Router 4.2.5
- **端口**: 5173 (默认)

### 依赖管理
- **包管理器**: pnpm (workspace 模式)
- **配置文件**: pnpm-workspace.yaml
- **根目录脚本**: concurrently 并发运行前后端

## 项目启动流程设计

### 启动顺序架构

```mermaid
graph TD
    A[检查 pnpm 安装] --> B[验证 workspace 配置]
    B --> C[检查依赖安装状态]
    C --> D[启动后端服务]
    D --> E[初始化数据库]
    E --> F[启动前端服务]
    F --> G[验证服务通信]
    G --> H[功能验证测试]
```

### 环境变量配置架构

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| PORT | 3000 | 后端服务端口 |
| NODE_ENV | development | 运行环境 |
| LLM_API_KEY | - | 大语言模型API密钥 |
| LLM_API_BASE_URL | https://api.openai.com/v1 | API基础地址 |
| LLM_MODEL | gpt-3.5-turbo | 使用的模型 |
| CORS_ORIGIN | http://localhost:5173 | 跨域设置 |

## 潜在错误分析与解决方案

### 数据库初始化错误

**错误场景**: SQLite 数据库文件不存在或权限问题
```mermaid
flowchart LR
    A[数据库连接失败] --> B{检查文件权限}
    B -->|权限正常| C[创建数据库目录]
    B -->|权限异常| D[修复文件权限]
    C --> E[执行 schema.sql]
    D --> E
    E --> F[验证表结构]
```

**解决策略**:
1. 确保 backend/database 目录存在且可写
2. 自动创建数据库文件
3. 执行 schema.sql 初始化表结构
4. 验证示例数据插入

### 端口冲突错误

**错误场景**: 3000 或 5173 端口被占用
```mermaid
graph TD
    A[启动失败] --> B{检查端口占用}
    B -->|端口被占用| C[终止占用进程]
    B -->|端口正常| D[检查其他配置]
    C --> E[重新启动服务]
    D --> F[排查网络配置]
```

**解决策略**:
1. 检测端口占用情况
2. 提供端口配置选项
3. 实现优雅的端口切换

### LLM API 配置错误

**错误模式**:
- API_KEY 未配置或无效
- 网络连接问题
- 请求频率限制

**修复流程**:
```mermaid
sequenceDiagram
    participant App as 应用
    participant Config as 配置验证
    participant LLM as LLM服务
    
    App->>Config: 验证API配置
    Config->>Config: 检查必要环境变量
    alt 配置缺失
        Config->>App: 返回警告信息
        App->>App: 使用默认配置
    else 配置完整
        Config->>LLM: 测试连接
        LLM->>Config: 返回连接状态
    end
```

### 前端构建错误

**常见问题**:
1. 依赖版本冲突
2. 样式预处理器错误
3. TypeScript 类型检查错误

**解决方案架构**:
- 依赖冲突: 使用 pnpm 的严格依赖解析
- 样式错误: 验证 SCSS 变量文件路径
- 类型错误: 配置 unplugin-auto-import

## 服务启动验证策略

### 后端健康检查

```mermaid
graph LR
    A[GET /] --> B{响应状态}
    B -->|200| C[服务正常]
    B -->|非200| D[服务异常]
    
    E[GET /api] --> F{API状态}
    F -->|可访问| G[API正常]
    F -->|不可访问| H[API异常]
```

### 前端资源加载验证

**验证点**:
1. 静态资源加载 (CSS, JS)
2. Vue 应用挂载成功
3. Element Plus 组件正常渲染
4. 路由导航功能

### 前后端通信验证

```mermaid
sequenceDiagram
    participant F as Frontend
    participant P as Proxy
    participant B as Backend
    
    F->>P: 发送 /api 请求
    P->>B: 转发到 localhost:3000
    B->>P: 返回响应
    P->>F: 返回结果
    
    Note over F,B: 验证 CORS 配置
    Note over F,B: 验证代理设置
```

## 功能验证测试方案

### 核心功能测试架构

```mermaid
graph TD
    A[页面加载测试] --> B[创建新对话]
    B --> C[发送消息测试]
    C --> D[接收响应测试]
    D --> E[对话历史测试]
    E --> F[UI交互测试]
```

### 测试用例设计

| 测试项 | 验证内容 | 期望结果 |
|--------|----------|----------|
| 页面访问 | http://localhost:5173 | 页面正常加载 |
| 新建对话 | 点击新建对话按钮 | 创建空白对话界面 |
| 消息发送 | 输入测试消息并发送 | 消息显示在界面 |
| API通信 | 后端接收并处理请求 | 返回预期响应 |
| 历史记录 | 查看对话历史 | 正确显示历史对话 |

## 错误监控与日志策略

### 日志架构设计

```mermaid
graph LR
    A[请求日志] --> D[Morgan中间件]
    B[错误日志] --> E[自定义ErrorHandler]
    C[应用日志] --> F[Console Logger]
    
    D --> G[请求统计]
    E --> H[错误追踪]
    F --> I[调试信息]
```

### 监控指标

- **性能指标**: 响应时间、内存使用、CPU占用
- **错误指标**: 错误率、异常类型、失败请求
- **业务指标**: API调用次数、用户会话数

## 部署前置条件检查

### 环境依赖验证

```mermaid
flowchart TD
    A[Node.js 版本] -->|>=16.0.0| B[pnpm 安装]
    B --> C[workspace 配置]
    C --> D[依赖安装状态]
    D --> E[环境变量配置]
    E --> F[网络连接测试]
    F --> G[启动准备就绪]
```

### 配置文件验证

1. **package.json**: 验证脚本配置和依赖版本
2. **pnpm-workspace.yaml**: 确认 workspace 配置格式
3. **vite.config.js**: 验证构建和代理配置
4. **.env**: 检查必要环境变量

## 故障排除指南

### 常见问题快速诊断

| 问题类型 | 症状 | 诊断步骤 | 解决方案 |
|----------|------|----------|----------|
| 依赖问题 | 模块找不到 | 检查 node_modules | 重新安装依赖 |
| 端口冲突 | EADDRINUSE | 检查端口占用 | 更换端口或终止进程 |
| 数据库错误 | 连接失败 | 检查文件权限 | 重新初始化数据库 |
| API调用失败 | 网络错误 | 检查配置和网络 | 修复配置或网络问题 |
| 前端白屏 | 页面不显示 | 检查控制台错误 | 修复组件或路由错误 |

### 调试工具配置

```mermaid
graph LR
    A[后端调试] --> B[nodemon + console.log]
    C[前端调试] --> D[Vue DevTools]
    E[网络调试] --> F[浏览器 Network 面板]
    G[数据库调试] --> H[SQLite 命令行工具]
```