djangoadmin/DjangoAdmin_FastAPI_EleVue

Fork 0

Files

T

gitadmin 3233d221b0 签入版本

2026-09-12 17:39:13 +08:00

5.5 KiB

Raw Permalink Blame History

贡献指南

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

🐛 报告 Bug

如果你在使用过程中发现了 Bug，请通过 Issue 提交，并尽量包含以下信息：

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

💡 功能建议

如果你有好的功能建议，也欢迎通过 Issue 提出。请描述：

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

🔧 提交代码

开发环境搭建

# 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 规范：

<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 代码风格
使用类型注解（Type Hints）
函数和类必须有文档字符串（中文注释）
新增模块遵循四层架构：models.py → schemas.py → repository.py → service.py
API 端点必须添加 @permission_required 权限装饰器
写操作端点必须添加 @check_demo 装饰器

# 示例：新增模块的端点
@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/ 目录下

测试要求

提交代码前请确保：

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

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

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

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

📝 提交 Pull Request

PR 流程

同步上游代码：

git fetch upstream
git rebase upstream/dev

创建特性分支：
```
git checkout -b feature/your-feature
```

开发并提交：

git add .
git commit -m "feat(scope): your feature description"

推送到你的 Fork：
```
git push origin feature/your-feature
```
创建 Pull Request：
- 目标分支选择 dev
- 填写 PR 模板，描述改动内容
- 关联相关 Issue

PR 要求

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

📖 完善文档

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

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

❓ 获取帮助

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

提交 Issue 描述你的问题
查阅开发文档
阅读项目源码中的注释

📜 行为准则

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

再次感谢你的贡献！🎉

5.5 KiB Raw Permalink Blame History Unescape Escape