# 贡献指南

感谢你对小虾 SaaS 项目的兴趣！

## 🚀 快速开始

### 1. Fork 和克隆

```bash
# Fork 项目到你的账号
# 然后克隆
git clone https://github.com/your-username/xiaoxia-saas.git
cd xiaoxia-saas
```

### 2. 设置开发环境

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

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

# 使用内存数据库（无需 PostgreSQL）
echo "USE_IN_MEMORY_DB=true" > .env

# 启动开发服务器
uvicorn apps.api.main:app --reload
```

### 3. 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行单元测试
pytest tests/unit -v

# 生成覆盖率报告
pytest --cov=packages --cov-report=html
```

---

## 📝 提交规范

### Commit Message 格式

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

<body>

<footer>
```

**Type:**
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `style`: 代码格式（不影响功能）
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建/工具相关

**示例:**
```
feat(auth): add password reset functionality

- Add RequestPasswordResetUseCase
- Send reset email with token
- Implement ResetPasswordUseCase
- Add unit tests

Closes #123
```

---

## 🏗️ 代码规范

### Python 代码风格

- 遵循 PEP 8
- 使用类型注解
- 函数和类添加 docstring
- 每个文件顶部添加模块说明

### 代码格式化

```bash
# 安装工具
pip install black isort

# 格式化代码
black packages/ apps/ tests/
isort packages/ apps/ tests/
```

### 架构原则

- 遵循 Clean Architecture
- 业务逻辑在 Application 层
- 基础设施在 Adapters 层
- 保持层次间依赖方向正确

---

## 🧪 测试要求

### 单元测试

- 所有新功能必须有单元测试
- 测试覆盖率不低于 80%
- 使用 pytest fixtures
- Mock 外部依赖

### 测试示例

```python
def test_create_workspace_success(use_case, mock_repo):
    \"\"\"测试创建工作空间成功\"\"\"
    request = CreateWorkspaceRequest(
        name="Test",
        owner_user_id="user-123",
    )
    
    response, error = use_case.execute(request)
    
    assert error is None
    assert response.name == "Test"
```

---

## 🔄 Pull Request 流程

### 1. 创建分支

```bash
# 从 main 创建功能分支
git checkout -b feat/your-feature-name
```

### 2. 开发和测试

```bash
# 编写代码
# 运行测试
pytest tests/ -v

# 提交
git add .
git commit -m "feat: your feature description"
```

### 3. 推送和创建 PR

```bash
# 推送到你的 fork
git push origin feat/your-feature-name

# 在 GitHub 上创建 Pull Request
```

### 4. PR 描述模板

```markdown
## 变更说明
简要描述此 PR 的目的

## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他

## 测试
- [ ] 添加了单元测试
- [ ] 所有测试通过
- [ ] 手动测试通过

## 截图（如适用）
添加相关截图

## 相关 Issue
Closes #issue_number
```

---

## 🐛 报告 Bug

### Bug 报告模板

```markdown
**描述**
清晰描述 bug

**复现步骤**
1. 进入 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 看到错误

**期望行为**
描述期望发生什么

**实际行为**
描述实际发生了什么

**环境**
- OS: [e.g. Ubuntu 22.04]
- Python: [e.g. 3.12]
- 浏览器: [e.g. Chrome 120]

**额外信息**
添加任何其他相关信息
```

---

## 💡 功能建议

### 功能请求模板

```markdown
**功能描述**
简要描述建议的功能

**问题**
此功能解决什么问题？

**建议方案**
描述你期望的解决方案

**替代方案**
考虑过哪些替代方案？

**额外信息**
其他相关信息
```

---

## 📚 文档贡献

### 文档类型

- README 和快速开始
- API 使用指南
- 部署文档
- 故障排查
- 架构说明

### 文档规范

- 使用 Markdown 格式
- 代码示例使用代码块
- 添加适当的标题层级
- 包含实际可运行的示例

---

## 🎯 优先级

### 高优先级
- Bug 修复
- 安全漏洞修复
- 性能优化
- 核心功能增强

### 中优先级
- 新功能
- 代码重构
- 测试增强
- 文档改进

### 低优先级
- 代码风格调整
- 次要功能
- 实验性功能

---

## 📞 联系方式

- **GitHub Issues**: 报告 bug 和功能请求
- **Pull Requests**: 贡献代码
- **Email**: support@xiaoxia-saas.com

---

## 📄 许可证

贡献的代码将使用与项目相同的许可证。

---

感谢你的贡献！🎉
