# UVM 开发指南

本文档提供了 UVM 项目的开发环境设置和开发指南。

## 🚀 快速开始

### 1. 设置开发环境

#### 方式一：使用 Python 脚本（推荐）

```bash
# 设置开发环境
python dev.py setup

# 或者使用 shell 脚本（Linux/macOS）
./dev.sh setup

# 或者使用批处理脚本（Windows）
dev.bat setup
```

#### 方式二：手动设置

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

# 安装 pre-commit hooks
pre-commit install
```

### 2. 运行和测试

#### 使用开发脚本

```bash
# 运行 UVM 命令
python dev.py run list
python dev.py run use tsinghua

# 运行测试
python dev.py test
python dev.py test tests/unit/

# 运行代码检查
python dev.py lint

# 运行所有检查
python dev.py check
```

#### 使用快速测试脚本

```bash
# 运行快速测试套件
python quick-test.py
```

#### 直接运行

```bash
# 运行 UVM
python -m uvm list
python -m uvm use tsinghua

# 运行测试
pytest --cov=uvm --cov-report=term-missing

# 运行代码检查
ruff check --fix .
ruff format .
mypy uvm/
```

## 🛠️ 开发工具

### 代码质量工具

- **Ruff**: 代码检查和格式化
- **MyPy**: 静态类型检查
- **Pre-commit**: Git 提交前检查

### 测试工具

- **Pytest**: 测试框架
- **pytest-cov**: 代码覆盖率
- **pytest-socket**: 禁用网络调用的测试工具

## 📁 项目结构

```
uvm/
├── uvm/                    # 主要源代码
│   ├── cli.py             # 命令行界面
│   ├── constants.py        # 常量定义
│   ├── core/              # 核心功能
│   │   ├── config.py      # 配置管理
│   │   ├── mirror.py      # 镜像源管理
│   │   └── speedtest.py   # 速度测试
│   └── models/            # 数据模型
│       └── mirror.py      # 镜像源模型
├── tests/                 # 测试代码
│   ├── unit/             # 单元测试
│   ├── integration/      # 集成测试
│   └── conftest.py       # 测试配置
├── dev.py                # Python 开发脚本
├── dev.sh                # Shell 开发脚本
├── dev.bat               # Windows 批处理脚本
├── dev.env               # 开发环境配置
├── quick-test.py         # 快速测试脚本
└── DEV.md                # 本文档
```

## 🧪 测试指南

### 运行测试

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

# 运行特定测试文件
pytest tests/unit/test_config.py

# 运行特定测试类型
pytest tests/unit/              # 单元测试
pytest tests/integration/       # 集成测试

# 运行测试并生成覆盖率报告
pytest --cov=uvm --cov-report=term-missing

# 运行测试并确保覆盖率达标
pytest --cov=uvm --cov-fail-under=90
```

### 测试标记

- `slow`: 标记为慢测试（使用 `-m "not slow"` 跳过）
- `integration`: 标记为集成测试
- `e2e`: 标记为端到端测试

### 编写测试

1. **单元测试**：测试单个函数或类的功能
2. **集成测试**：测试多个组件的交互
3. **端到端测试**：测试完整的用户场景

#### 测试示例

```python
# tests/unit/test_example.py
import pytest
from uvm.core.config import Config

def test_config_creation():
    """测试配置创建"""
    config = Config()
    assert config is not None

@pytest.mark.integration
def test_mirror_operations():
    """测试镜像源操作"""
    # 集成测试代码
    pass
```

## 🔧 代码规范

### 代码风格

- 使用 **Ruff** 进行代码检查和格式化
- 行长度限制：88 字符
- 使用 **MyPy** 进行类型检查

### 提交规范

使用 Pre-commit hooks 确保代码质量：

```bash
# 手动运行 pre-commit 检查
pre-commit run --all-files

# 跳过 pre-commit（不推荐）
git commit --no-verify
```

### 代码审查要点

1. **功能正确性**：代码是否实现预期功能
2. **测试覆盖**：是否有足够的测试覆盖
3. **代码质量**：是否符合项目代码规范
4. **文档更新**：是否需要更新相关文档

## 🐛 调试指南

### 启用调试模式

```bash
# 设置环境变量启用调试
export UVM_DEBUG=1

# 或者在代码中启用
import logging
logging.basicConfig(level=logging.DEBUG)
```

### 常见问题

1. **导入错误**：确保已安装开发依赖
2. **权限问题**：检查文件权限和用户权限
3. **网络问题**：使用 `pytest-socket` 禁用网络调用

### 调试技巧

```python
# 使用 pdb 调试
import pdb; pdb.set_trace()

# 使用 logging
import logging
logger = logging.getLogger(__name__)
logger.debug("Debug message")
```

## 📦 发布流程

### 版本管理

1. 更新 `pyproject.toml` 中的版本号
2. 更新 `CHANGELOG.md`
3. 创建 Git 标签

### 构建和发布

```bash
# 构建包
python -m build

# 发布到测试 PyPI
python -m twine upload --repository testpypi dist/*

# 发布到正式 PyPI
python -m twine upload dist/*
```

## 🤝 贡献指南

### 开发流程

1. Fork 项目
2. 创建功能分支
3. 编写代码和测试
4. 运行所有检查
5. 提交 Pull Request

### 分支策略

- `main`: 主分支，稳定版本
- `develop`: 开发分支，最新功能
- `feature/*`: 功能分支
- `hotfix/*`: 热修复分支

### 提交信息格式

```
type(scope): description

[optional body]

[optional footer]
```

类型：
- `feat`: 新功能
- `fix`: 修复
- `docs`: 文档
- `style`: 格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具

## 📚 参考资料

- [UVM 用户指南](USER_GUIDE.md)
- [API 文档](https://github.com/your-org/uvm)
- [Pydantic 文档](https://pydantic-docs.helpmanual.io/)
- [Typer 文档](https://typer.tiangolo.com/)
- [Rich 文档](https://rich.readthedocs.io/)