签入版本
This commit is contained in:
+224
@@ -0,0 +1,224 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢你对 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)
|
||||
- 阅读项目源码中的注释
|
||||
|
||||
|
||||
## 📜 行为准则
|
||||
|
||||
- 尊重每一位参与者
|
||||
- 建设性地提出意见和建议
|
||||
- 聚焦于对社区最有利的事情
|
||||
- 对他人表示同理心
|
||||
|
||||
再次感谢你的贡献！🎉
|
||||
Reference in New Issue
Block a user