012-kaopeilian/docs/规划/关于部署/本地开发.md

# 考培练系统本地开发环境配置指南

## 🎯 概述

本文档为开发者提供本地开发环境的配置说明，确保开发者能够在本地连接远程数据库进行开发，而不与生产环境配置产生冲突。

## 📋 环境要求

### 系统要求
- Node.js 18+
- Python 3.11+
- Git
- 网络访问远程MySQL服务器

### 开发工具推荐
- VS Code / WebStorm
- Postman / Insomnia（API测试）
- MySQL Workbench（数据库管理）

## 🚀 快速开始

### 1. 克隆项目
```bash
git clone https://github.com/nongjun/ai-development-workspace.git
cd ai-development-workspace
```

### 2. 后端配置

#### 2.1 创建环境配置
```bash
cd kaopeilian-backend

# 复制环境配置模板
cp .env.example .env

# 编辑配置文件（保持远程数据库配置）
# .env 文件内容应该是：
# DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4
# REDIS_URL=redis://localhost:6379/0
# DEBUG=true
```

#### 2.2 安装依赖
```bash
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

#### 2.3 启动后端服务
```bash
# 方式1：直接运行（推荐，支持热重载）
python app/main.py

# 方式2：使用uvicorn
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 验证启动
curl http://localhost:8000/health
```

### 3. 前端配置

#### 3.1 安装依赖
```bash
cd kaopeilian-frontend

# 使用npm
npm install

# 或使用pnpm（推荐）
pnpm install
```

#### 3.2 配置环境变量
```bash
# 检查env.example文件
cat env.example

# 如果需要，可以创建.env.local文件覆盖配置
echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local
echo "VITE_USE_MOCK_DATA=false" >> .env.local
```

#### 3.3 启动前端服务
```bash
# 开发模式启动（支持HMR热重载）
npm run dev

# 或使用pnpm
pnpm dev

# 访问地址：http://localhost:3001
```

## 🔧 配置说明

### 数据库连接配置

#### 远程MySQL连接信息
- **主机**: `120.79.247.16` 或 `aiedu.ireborn.com.cn`
- **端口**: `3306`
- **数据库**: `kaopeilian`
- **用户**: `root`
- **密码**: `Kaopeilian2025!@#`

#### 连接字符串格式
```env
# 注意：密码中的特殊字符需要URL编码
DATABASE_URL=mysql+aiomysql://root:Kaopeilian2025%21%40%23@120.79.247.16:3306/kaopeilian?charset=utf8mb4

# 特殊字符编码对照：
# ! → %21
# @ → %40  
# # → %23
```

### 前端API配置

#### 开发环境
- **API地址**: `http://localhost:8000`
- **代理配置**: Vite自动代理`/api`请求到后端
- **Mock数据**: 默认关闭（`VITE_USE_MOCK_DATA=false`）

#### 调试配置
```typescript
// src/config/env.ts
public readonly API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000'
public readonly USE_MOCK_DATA = import.meta.env.VITE_USE_MOCK_DATA === 'true'
```

## 🛠️ 开发工作流

### 日常开发流程

1. **启动后端服务**：
   ```bash
   cd kaopeilian-backend
   python app/main.py  # 自动热重载
   ```

2. **启动前端服务**：
   ```bash
   cd kaopeilian-frontend  
   npm run dev  # HMR热重载
   ```

3. **访问应用**：
   - 前端：http://localhost:3001
   - 后端API：http://localhost:8000
   - API文档：http://localhost:8000/docs

### 代码提交流程

1. **本地测试**：
   ```bash
   # 后端测试
   cd kaopeilian-backend
   pytest tests/

   # 前端测试
   cd kaopeilian-frontend
   npm run test
   npm run lint
   ```

2. **提交代码**：
   ```bash
   git add .
   git commit -m "feat: 添加新功能"
   git push origin main
   ```

3. **自动部署**：
   - 推送到main分支后，生产服务器会自动更新
   - 通过GitHub Webhook机制触发
   - 自动重新构建和部署

## 🔍 故障排查

### 常见问题

#### 1. 数据库连接失败
```bash
# 检查网络连接
ping 120.79.247.16

# 测试MySQL连接
mysql -h 120.79.247.16 -P 3306 -u root -p

# 检查环境变量
cat .env | grep DATABASE_URL
```

#### 2. 前端API请求失败
```bash
# 检查后端是否启动
curl http://localhost:8000/health

# 检查前端代理配置
cat vite.config.ts | grep proxy -A 10

# 检查浏览器Network面板
# 确认请求是否正确转发到 http://localhost:8000
```

#### 3. 热重载不工作
```bash
# 后端：确认使用--reload参数
ps aux | grep uvicorn

# 前端：确认开发模式启动
ps aux | grep vite
```

### 调试技巧

1. **后端调试**：
   ```bash
   # 查看详细日志
   python app/main.py --log-level debug
   
   # 使用调试器
   python -m pdb app/main.py
   ```

2. **前端调试**：
   ```bash
   # 查看构建信息
   npm run dev -- --debug
   
   # 检查环境变量
   npm run dev -- --mode development
   ```

3. **数据库调试**：
   ```bash
   # 连接数据库
   mysql -h 120.79.247.16 -P 3306 -u root -p kaopeilian
   
   # 查看表结构
   DESCRIBE users;
   DESCRIBE courses;
   ```

## 📚 开发规范

### 代码规范
- **后端**：使用black格式化，flake8检查
- **前端**：使用ESLint和Prettier
- **提交信息**：使用约定式提交格式

### API开发规范
- **路径**：`/api/v1/{module}/{action}`
- **响应格式**：统一使用`{code, message, data}`
- **错误处理**：统一异常处理和日志记录

### 数据库规范
- **字符集**：utf8mb4
- **命名**：下划线命名法
- **迁移**：使用Alembic管理数据库版本

## 🔄 与生产环境的区别

| 配置项 | 本地开发 | 生产环境 |
|--------|----------|----------|
| 数据库 | 远程MySQL (120.79.247.16) | 本地MySQL容器 |
| Redis | 本地Redis | Redis容器 |
| 前端 | 开发服务器 (HMR) | 静态文件 (Nginx) |
| 后端 | 直接运行 | Docker容器 |
| HTTPS | 不需要 | SSL证书 |
| 域名 | localhost | aiedu.ireborn.com.cn |

## 💡 最佳实践

### 1. 环境隔离
- 使用不同的配置文件
- 不要在开发环境修改生产数据
- 定期同步测试数据

### 2. 代码管理
- 频繁提交小的更改
- 使用有意义的提交信息
- 提交前进行本地测试

### 3. 调试技巧
- 使用浏览器开发者工具
- 查看Network面板确认API调用
- 使用Console查看前端日志
- 查看后端日志文件

### 4. 性能优化
- 使用代码分割
- 启用缓存机制
- 优化数据库查询
- 监控API响应时间

## 🆘 获取帮助

### 联系方式
- **技术支持**：查看项目README
- **问题反馈**：GitHub Issues
- **文档更新**：提交PR

### 相关文档
- [API接口文档](../全链路联调/前后端接口约定.md)
- [数据库架构](../../kaopeilian-backend/数据库架构-统一版.md)
- [联调经验](../全链路联调/联调经验汇总.md)
- [服务器部署](./服务器部署经验.md)