# 开发环境安装指南

## 快速开始

### 1. 使用 uv（推荐）

```bash
# 创建虚拟环境并安装依赖
uv venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# 安装项目（生产模式）
uv pip install -e .

# 安装项目（开发模式，包含所有开发工具）
uv pip install -e ".[dev]"
```

### 2. 使用 requirements 文件

```bash
# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# 安装生产依赖
uv pip install -r requirements.txt

# 安装开发依赖（包含生产依赖）
uv pip install -r requirements-dev.txt
```

## 清华源配置（国内用户推荐）

### uv 全局配置

**Windows:**
```batch
mkdir %APPDATA%\uv
echo [pip] > %APPDATA%\uv\uv.toml
echo index-url = "https://pypi.tuna.tsinghua.edu.cn/simple" >> %APPDATA%\uv\uv.toml
```

**Linux/macOS:**
```bash
mkdir -p ~/.config/uv
cat > ~/.config/uv/uv.toml << 'EOF'
[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
EOF
```

### 环境变量配置

```bash
# Windows (PowerShell)
$env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

# Linux/macOS
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
```

## 依赖文件说明

- **pyproject.toml**: 项目元数据和依赖声明（PEP 518标准）
- **requirements.txt**: 生产环境依赖，精确到版本号
- **requirements-dev.txt**: 开发环境依赖（包含 requirements.txt）
- **.env.example**: 环境变量配置示例

## 常用命令

### 安装与更新

```bash
# 安装项目及其依赖
uv pip install -e .

# 安装开发依赖
uv pip install -e ".[dev]"

# 冻结当前环境依赖
uv pip freeze > requirements.txt
```

### 代码质量检查

```bash
# 代码格式化
uv run black src/ tests/

# 代码检查和自动修复
uv run ruff check src/ tests/ --fix

# 类型检查
uv run mypy src/

# 运行测试
uv run pytest tests/

# 生成测试覆盖率报告
uv run pytest --cov=src/autoreport --cov-report=html tests/
```

### 安全检查

```bash
# 安装检查工具
uv pip install bandit pip-audit

# 运行安全扫描
uv run bandit -r src/

# 检查依赖漏洞
uv run pip-audit
```

## 环境变量配置

1. 复制 `.env.example` 为 `.env`
2. 根据需要修改环境变量
3. 确保 `.env` 已添加到 `.gitignore`（已包含）

## 故障排除

### 虚拟环境损坏

```bash
# 删除虚拟环境并重建
rm -rf .venv
uv venv
uv pip install -r requirements-dev.txt
```

### 清华源访问问题

```bash
# 临时使用官方源
uv pip install -i https://pypi.org/simple/ package_name

# 或重新配置源
# 参考上面的"清华源配置"部分
```

### 测试覆盖率过低

```bash
# 查看详细的覆盖率报告
open htmlcov/index.html  # macOS
start htmlcov/index.html  # Windows
xdg-open htmlcov/index.html  # Linux
```

## 发布流程

```bash
# 1. 确保所有测试通过
uv run pytest tests/

# 2. 更新版本（自动从git tag读取）
git tag -a v1.0.0 -m "Release v1.0.0"

# 3. 推送tag（触发CI/CD发布）
git push origin v1.0.0
```

## 相关文档

- [pyproject.toml 配置](./pyproject.toml)
- [Python 项目开发规范](./Python项目开发规范.md)
- [CLAUDE.md 开发指南](./CLAUDE.md)
