225 lines
5.5 KiB
Markdown
225 lines
5.5 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 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)
|
||
- 阅读项目源码中的注释
|
||
|
||
|
||
## 📜 行为准则
|
||
|
||
- 尊重每一位参与者
|
||
- 建设性地提出意见和建议
|
||
- 聚焦于对社区最有利的事情
|
||
- 对他人表示同理心
|
||
|
||
再次感谢你的贡献！🎉
|