326 lines
6.3 KiB
Markdown
326 lines
6.3 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 DeepAudit 的关注！我们热烈欢迎所有形式的贡献，无论是提交 Issue、创建 PR，还是改进文档。
|
||
|
||
## 目录
|
||
|
||
- [行为准则](#行为准则)
|
||
- [如何贡献](#如何贡献)
|
||
- [开发环境搭建](#开发环境搭建)
|
||
- [代码规范](#代码规范)
|
||
- [提交规范](#提交规范)
|
||
- [Pull Request 流程](#pull-request-流程)
|
||
|
||
---
|
||
|
||
## 行为准则
|
||
|
||
请在参与项目时保持友善和尊重。我们致力于为每个人提供一个开放、包容的环境。
|
||
|
||
---
|
||
|
||
## 如何贡献
|
||
|
||
### 报告 Bug
|
||
|
||
1. 先搜索 [Issues](https://github.com/lintsinghua/DeepAudit/issues) 确认问题未被报告
|
||
2. 创建新 Issue，使用 Bug 报告模板
|
||
3. 提供详细信息：
|
||
- 操作系统和版本
|
||
- 部署方式（Docker/本地）
|
||
- 复现步骤
|
||
- 错误日志或截图
|
||
- 期望行为 vs 实际行为
|
||
|
||
### 提出新功能
|
||
|
||
1. 先搜索 Issues 确认功能未被提出
|
||
2. 创建新 Issue，描述：
|
||
- 功能需求背景
|
||
- 期望的实现方式
|
||
- 可能的替代方案
|
||
|
||
### 改进文档
|
||
|
||
文档改进同样重要！你可以：
|
||
- 修复文档中的错误
|
||
- 补充缺失的说明
|
||
- 改进文档结构
|
||
- 添加使用示例
|
||
|
||
### 贡献代码
|
||
|
||
1. Fork 本项目
|
||
2. 创建功能分支
|
||
3. 编写代码和测试
|
||
4. 提交 Pull Request
|
||
|
||
---
|
||
|
||
## 开发环境搭建
|
||
|
||
### 环境要求
|
||
|
||
| 依赖 | 版本要求 | 说明 |
|
||
|------|---------|------|
|
||
| Node.js | 18+ | 前端运行环境 |
|
||
| Python | 3.13+ | 后端运行环境 |
|
||
| PostgreSQL | 15+ | 数据库 |
|
||
| pnpm | 8+ | 推荐的前端包管理器 |
|
||
| uv | 最新版 | 推荐的 Python 包管理器 |
|
||
|
||
### 数据库准备
|
||
|
||
```bash
|
||
# 使用 Docker 启动 PostgreSQL（推荐）
|
||
docker run -d \
|
||
--name deepaudit-db \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=postgres \
|
||
-e POSTGRES_DB=deepaudit \
|
||
-p 5432:5432 \
|
||
postgres:15-alpine
|
||
```
|
||
|
||
### 后端启动
|
||
|
||
```bash
|
||
# 1. 进入后端目录
|
||
cd backend
|
||
|
||
# 2. 创建虚拟环境
|
||
uv venv
|
||
source .venv/bin/activate # Linux/macOS
|
||
# 或 .venv\Scripts\activate # Windows
|
||
|
||
# 3. 安装依赖
|
||
uv pip install -e .
|
||
|
||
# 4. 配置环境变量
|
||
cp env.example .env
|
||
# 编辑 .env 文件，配置数据库和 LLM 参数
|
||
|
||
# 5. 初始化数据库
|
||
alembic upgrade head
|
||
|
||
# 6. 启动后端服务
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
### 前端启动
|
||
|
||
```bash
|
||
# 1. 进入前端目录
|
||
cd frontend
|
||
|
||
# 2. 安装依赖
|
||
pnpm install
|
||
|
||
# 3. 配置环境变量（可选）
|
||
cp .env.example .env
|
||
|
||
# 4. 启动开发服务器
|
||
pnpm dev
|
||
```
|
||
|
||
---
|
||
|
||
## 代码规范
|
||
|
||
### 后端 (Python)
|
||
|
||
- 使用 Python 3.13+ 类型注解
|
||
- 遵循 PEP 8 代码风格
|
||
- 使用 Ruff 进行代码格式化和检查
|
||
- 使用 mypy 进行类型检查
|
||
|
||
```bash
|
||
# 代码格式化
|
||
ruff format app
|
||
|
||
# 代码检查
|
||
ruff check app
|
||
|
||
# 类型检查
|
||
mypy app
|
||
```
|
||
|
||
### 前端 (TypeScript/React)
|
||
|
||
- 使用 TypeScript 严格模式
|
||
- 遵循 React 最佳实践
|
||
- 使用 Biome 进行代码格式化和检查
|
||
|
||
```bash
|
||
# 代码检查
|
||
pnpm lint
|
||
|
||
# 类型检查
|
||
pnpm type-check
|
||
|
||
# 代码格式化
|
||
pnpm format
|
||
```
|
||
|
||
### 通用规范
|
||
|
||
- 变量和函数使用有意义的命名
|
||
- 添加必要的注释，特别是复杂逻辑
|
||
- 保持函数简短，单一职责
|
||
- 避免硬编码，使用配置或常量
|
||
|
||
---
|
||
|
||
## 提交规范
|
||
|
||
我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
|
||
|
||
### 提交格式
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 类型
|
||
|
||
| Type | 说明 |
|
||
|------|------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | Bug 修复 |
|
||
| `docs` | 文档更新 |
|
||
| `style` | 代码格式（不影响功能） |
|
||
| `refactor` | 代码重构 |
|
||
| `perf` | 性能优化 |
|
||
| `test` | 测试相关 |
|
||
| `chore` | 构建/工具相关 |
|
||
| `ci` | CI/CD 相关 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 新功能
|
||
git commit -m "feat(llm): add support for DeepSeek API"
|
||
|
||
# Bug 修复
|
||
git commit -m "fix(scan): handle empty file content"
|
||
|
||
# 文档更新
|
||
git commit -m "docs: update deployment guide"
|
||
|
||
# 代码重构
|
||
git commit -m "refactor(api): simplify error handling"
|
||
```
|
||
|
||
---
|
||
|
||
## Pull Request 流程
|
||
|
||
### 1. Fork 和克隆
|
||
|
||
```bash
|
||
# Fork 项目到你的 GitHub 账号
|
||
# 然后克隆到本地
|
||
git clone https://github.com/YOUR_USERNAME/DeepAudit.git
|
||
cd DeepAudit
|
||
|
||
# 添加上游仓库
|
||
git remote add upstream https://github.com/lintsinghua/DeepAudit.git
|
||
```
|
||
|
||
### 2. 创建分支
|
||
|
||
```bash
|
||
# 同步上游代码
|
||
git fetch upstream
|
||
git checkout main
|
||
git merge upstream/main
|
||
|
||
# 创建功能分支
|
||
git checkout -b feature/your-feature-name
|
||
```
|
||
|
||
### 3. 开发和测试
|
||
|
||
```bash
|
||
# 编写代码...
|
||
|
||
# 确保代码通过检查
|
||
cd frontend && pnpm lint && pnpm type-check
|
||
cd backend && ruff check app && mypy app
|
||
|
||
# 提交代码
|
||
git add .
|
||
git commit -m "feat: your feature description"
|
||
```
|
||
|
||
### 4. 推送和创建 PR
|
||
|
||
```bash
|
||
# 推送到你的 Fork
|
||
git push origin feature/your-feature-name
|
||
```
|
||
|
||
然后在 GitHub 上创建 Pull Request：
|
||
|
||
1. 填写 PR 标题（遵循提交规范）
|
||
2. 描述改动内容和原因
|
||
3. 关联相关 Issue（如有）
|
||
4. 等待 Review
|
||
|
||
### 5. 代码审查
|
||
|
||
- 回应 Review 意见
|
||
- 根据反馈修改代码
|
||
- 保持 PR 更新（rebase 上游代码）
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
DeepAudit/
|
||
├── backend/ # 后端 (FastAPI)
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ ├── core/ # 核心配置
|
||
│ │ ├── db/ # 数据库
|
||
│ │ ├── models/ # 数据模型
|
||
│ │ ├── schemas/ # Pydantic 模式
|
||
│ │ └── services/ # 业务逻辑
|
||
│ │ └── llm/ # LLM 适配器
|
||
│ ├── alembic/ # 数据库迁移
|
||
│ └── pyproject.toml
|
||
├── frontend/ # 前端 (React + TypeScript)
|
||
│ ├── src/
|
||
│ │ ├── app/ # 应用配置
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ ├── features/ # 功能模块
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ └── shared/ # 共享工具
|
||
│ └── package.json
|
||
├── docs/ # 文档
|
||
├── docker-compose.yml # Docker 编排
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献者
|
||
|
||
感谢所有贡献者的付出！
|
||
|
||
[](https://github.com/lintsinghua/DeepAudit/graphs/contributors)
|
||
|
||
---
|
||
|
||
## 问题反馈
|
||
|
||
如有问题，请通过以下方式联系：
|
||
|
||
- [GitHub Issues](https://github.com/lintsinghua/DeepAudit/issues)
|
||
- 邮箱: lintsinghua@qq.com
|