# 贡献指南

感谢你对 DjangoAdmin 企业数字化开发平台的关注！我们欢迎任何形式的贡献，包括但不限于：报告 Bug、提出新功能建议、提交代码改进、完善文档等。


## 🐛 报告 Bug

如果你在使用过程中发现了 Bug，请通过 [Issue](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue/issues) 提交，并尽量包含以下信息：

1. **问题描述**：清晰简洁地描述遇到的问题
2. **复现步骤**：详细的操作步骤，以便我们能够复现问题
3. **期望行为**：你期望的正确行为是什么
4. **实际行为**：实际发生了什么
5. **环境信息**：
   - 操作系统（Windows / macOS / Linux）
   - Python 版本
   - Node.js 版本
   - 数据库类型及版本
   - 浏览器及版本
6. **截图或日志**：如有报错信息，请附上截图或控制台日志


## 💡 功能建议

如果你有好的功能建议，也欢迎通过 [Issue](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue/issues) 提出。请描述：

1. **使用场景**：这个功能解决什么问题？
2. **期望方案**：你希望如何实现？
3. **替代方案**：是否考虑过其他实现方式？


## 🔧 提交代码

### 开发环境搭建

```bash
# 1. Fork 并克隆项目
git clone https://gitee.com/你的用户名/DjangoAdmin_Fastapi_EleVue.git
cd DjangoAdmin_Fastapi_EleVue

# 2. 添加上游仓库
git remote add upstream https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue.git

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

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 配置数据库和 Redis 连接

# 5. 初始化数据库
python scripts/init_db.py

# 6. 启动开发服务
python src/main.py
```

### 分支管理

- `main` — 主分支，保持稳定可发布状态
- `dev` — 开发分支，日常开发基于此分支
- `feature/xxx` — 新功能分支，从 `dev` 创建
- `fix/xxx` — Bug 修复分支，从 `dev` 创建
- `docs/xxx` — 文档更新分支

### 提交规范

我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型：**

| 类型 | 说明 |
|---|---|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 文档更新 |
| `style` | 代码格式调整（不影响逻辑） |
| `refactor` | 代码重构（既不修复 Bug 也不添加功能） |
| `perf` | 性能优化 |
| `test` | 测试相关 |
| `chore` | 构建/工具/辅助相关 |

**示例：**

```
feat(user): 新增用户批量导入功能

- 支持 Excel 文件上传导入
- 自动校验用户名唯一性
- 导入结果反馈成功/失败条数

Closes #123
```

```
fix(auth): 修复 Token 过期后刷新失败的问题

Token 刷新接口在 Token 已过期时返回 401，应返回新 Token。
```

### 代码规范

#### Python 后端

- 遵循 [PEP 8](https://peps.python.org/pep-0008/) 代码风格
- 使用类型注解（Type Hints）
- 函数和类必须有文档字符串（中文注释）
- 新增模块遵循四层架构：`models.py` → `schemas.py` → `repository.py` → `service.py`
- API 端点必须添加 `@permission_required` 权限装饰器
- 写操作端点必须添加 `@check_demo` 装饰器

```python
# 示例：新增模块的端点
@router.post('/add')
@permission_required("sys:your_module:add")
@check_demo
async def add(request: Request, data: YourModuleForm):
    """新增记录"""
    return await your_module_service.add(request, data)
```

#### TypeScript 前端

- 遵循 ESLint + Prettier 配置
- 使用 TypeScript 严格模式
- 组件使用 Composition API + `<script setup>` 语法
- API 请求统一封装在 `api/` 目录下

### 测试要求

提交代码前请确保：

```bash
# 运行单元测试，确保全部通过
pytest tests/unit

# 运行契约测试，确保路由/权限未意外变更
pytest tests/contract -m contract

# 如有条件，运行集成测试
pytest tests/integration -m integration
```

- 新增功能需附带对应的单元测试
- Bug 修复需附带回归测试，确保问题不再复现
- 测试文件放在 `tests/` 对应目录下


## 📝 提交 Pull Request

### PR 流程

1. **同步上游代码**：
   ```bash
   git fetch upstream
   git rebase upstream/dev
   ```

2. **创建特性分支**：
   ```bash
   git checkout -b feature/your-feature
   ```

3. **开发并提交**：
   ```bash
   git add .
   git commit -m "feat(scope): your feature description"
   ```

4. **推送到你的 Fork**：
   ```bash
   git push origin feature/your-feature
   ```

5. **创建 Pull Request**：
   - 目标分支选择 `dev`
   - 填写 PR 模板，描述改动内容
   - 关联相关 Issue

### PR 要求

- ✅ 代码符合项目规范
- ✅ 所有测试通过
- ✅ 提交信息符合 Conventional Commits 规范
- ✅ 新增功能有对应测试覆盖
- ✅ 如有 API 变更，同步更新文档
- ✅ 一个 PR 只做一件事，保持 PR 聚焦


## 📖 完善文档

文档改进同样重要！你可以：

- 修正文档中的错误或过时内容
- 补充使用示例和最佳实践
- 翻译文档到其他语言
- 改善文档结构和可读性


## ❓ 获取帮助

如果你在贡献过程中遇到问题，可以通过以下方式获取帮助：

- 提交 Issue 描述你的问题
- 查阅[开发文档](http://docs.fastapi.elevue.djangoadmin.cn)
- 阅读项目源码中的注释


## 📜 行为准则

- 尊重每一位参与者
- 建设性地提出意见和建议
- 聚焦于对社区最有利的事情
- 对他人表示同理心

再次感谢你的贡献！🎉