# Python 虚拟环境使用指南

## 快速开始

### Windows
```bash
# 运行设置脚本
setup.bat

# 激活虚拟环境
activate_venv.bat

# 初始化数据库
python init_db.py

# 启动应用
python run.py
```

### Unix/Linux/macOS
```bash
# 设置执行权限
chmod +x setup.sh

# 运行设置脚本
./setup.sh

# 激活虚拟环境
source activate_venv.sh

# 初始化数据库
python init_db.py

# 启动应用
python run.py
```

## 详细说明

### 1. 创建虚拟环境

#### 自动设置 (推荐)
```bash
# Windows
setup.bat

# Unix/Linux/macOS
./setup.sh
```

#### 手动设置
```bash
# 创建虚拟环境
python setup_venv.py

# 升级依赖
python setup_venv.py --upgrade

# 重新创建虚拟环境
python setup_venv.py --clean
```

### 2. 激活虚拟环境

#### Windows
```bash
# 方式1: 使用生成的脚本
activate_venv.bat

# 方式2: 直接激活
venv\Scripts\activate.bat
```

#### Unix/Linux/macOS
```bash
# 方式1: 使用生成的脚本
source activate_venv.sh

# 方式2: 直接激活
source venv/bin/activate
```

### 3. 停用虚拟环境
```bash
deactivate
```

### 4. 验证环境
```bash
# 检查Python路径
which python    # Unix/Linux/macOS
where python    # Windows

# 检查已安装的包
pip list

# 检查Flask是否正确安装
python -c "import flask; print(flask.__version__)"
```

## 常用命令

### 开发命令
```bash
# 启动Flask应用 (开发模式)
python run.py

# 初始化数据库
python init_db.py

# 初始化数据库并创建示例数据
python init_db.py --with-demo

# 重置数据库
python init_db.py --reset
```

### Celery任务队列
```bash
# 启动Celery worker
celery -A celery_worker worker --loglevel=info

# Windows上启动Celery (需要额外配置)
celery -A celery_worker worker --loglevel=info --pool=solo
```

### 测试
```bash
# 运行所有测试
pytest

# 运行测试并显示覆盖率
pytest --cov=app

# 运行特定测试文件
pytest tests/test_auth.py
```

### 数据库迁移
```bash
# 初始化迁移
flask db init

# 创建迁移
flask db migrate -m "描述信息"

# 应用迁移
flask db upgrade
```

## 环境变量

创建 `.env` 文件 (基于 `.env.example`):
```bash
cp .env.example .env
```

编辑 `.env` 文件设置必要的环境变量:
```env
FLASK_ENV=development
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret-key
DATABASE_URL=sqlite:///dev.db
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
ENCRYPTION_KEY=your-encryption-key
```

## 依赖管理

### 安装新依赖
```bash
# 激活虚拟环境后
pip install package-name

# 更新requirements.txt
pip freeze > requirements.txt
```

### 升级依赖
```bash
# 升级所有依赖
python setup_venv.py --upgrade

# 升级特定包
pip install --upgrade package-name
```

## 故障排除

### 常见问题

1. **Python版本不兼容**
   - 确保使用Python 3.8或更高版本
   - 检查: `python --version`

2. **虚拟环境激活失败**
   - Windows: 确保执行策略允许运行脚本
   - Unix/Linux: 确保脚本有执行权限 `chmod +x activate_venv.sh`

3. **依赖安装失败**
   - 升级pip: `pip install --upgrade pip`
   - 清理缓存: `pip cache purge`
   - 重新创建环境: `python setup_venv.py --clean`

4. **数据库连接问题**
   - 检查数据库文件路径
   - 确保有写入权限
   - 检查环境变量设置

### 重置环境
```bash
# 完全重置虚拟环境
python setup_venv.py --clean

# 重置数据库
python init_db.py --reset
```

## 项目结构
```
backend/
├── venv/                   # 虚拟环境目录
├── app/                    # 应用代码
├── config/                 # 配置文件
├── migrations/             # 数据库迁移
├── tests/                  # 测试文件
├── requirements.txt        # 依赖列表
├── setup_venv.py          # 虚拟环境设置脚本
├── setup.bat              # Windows快速设置
├── setup.sh               # Unix/Linux快速设置
├── activate_venv.bat      # Windows激活脚本
├── activate_venv.sh       # Unix/Linux激活脚本
├── init_db.py             # 数据库初始化脚本
└── run.py                 # 应用入口
```