# 贡献指南

欢迎参与 DjangoAdmin Flask+EleVue 的开发。请遵循以下规范。

## 开发环境

```bash
# 1. 安装开发依赖（含生产依赖）
python -m venv .venv
.venv/Scripts/activate        # Windows
# source .venv/bin/activate   # Linux/macOS
pip install -r requirements-dev.txt

# 2. 复制并配置环境变量
cp .env.example .env

# 3. 安装 pre-commit 钩子
pre-commit install
```

## 代码规范

项目强制 `flake8` 零告警（与 black/isort 配置协同）。

```bash
make lint        # flake8 + black --check + isort --check
make format      # black + isort 自动格式化
make type-check  # mypy
```

## 新增业务模块

遵循 **View(router) → Service → Repository → Model** 四层：

1. `src/modules/<domain>/<name>/models.py` — 继承 `BaseModel` + `BaseDB`
2. `src/modules/<domain>/<name>/repository.py` — 继承 `BaseRepository`
3. `src/modules/<domain>/<name>/service.py` — 业务逻辑（**入参数据/出参数据**，失败 `raise BizError`，不读 `request`）
4. `src/modules/<domain>/<name>/schema.py` — WTForms 验证表单（继承 `BaseForm`）
5. `src/modules/<domain>/<name>/router.py` — 路由（取参 + 包 R + `@check_permission`）
6. `src/routes/v1.py` — 将蓝图加入 `BLUEPRINTS` 列表（挂载 `/api/v1`）

## 测试

```bash
make test        # pytest
make test-cov    # 覆盖率
```

单元测试放置于 `tests/unit/`，集成测试放置于 `tests/integration/`。

## 提交规范

- 提交信息使用 `type: 描述` 前缀（feat/fix/refactor/chore/docs）
- 每阶段独立提交，便于回滚
- pre-commit 钩子会自动执行格式检查

## 文档

- 架构与规范见 `CLAUDE.md` 与 `重构方案-v2.md`
- API 变更需同步 `USAGE.md` 与 `CHANGELOG.md`