🇨🇳 简体中文
🇺🇸 English
🇯🇵 日本語

贡献指南

本文档说明如何参与项目开发，包括协作流程、文档维护、代码规范和测试要求。

文档维护流程

核心原则

文档与代码必须同步：代码变更必须同步更新相关文档。

何时更新文档

必须更新：

变更类型 文档位置
API 接口变更 docs/api/v1/{模块}/README.md
数据模型变更 docs/domain/*.md
架构模块变更 docs/architecture/*.md
CLI 命令变更 docs/cli.md
环境变量变更 docs/development.md
配置文件变更 对应的配置文档

可选更新：

文档检查清单

提交 PR 前确认：

## 代码变更
- [ ] 识别所有受影响的模块
- [ ] 列出所有 API 变更
- [ ] 列出所有数据模型变更
- [ ] 列出所有配置变更

## 文档更新
- [ ] 更新 API 文档
- [ ] 更新架构文档
- [ ] 更新域模型文档
- [ ] 更新开发指南（如需要）

## 文档验证
- [ ] 示例代码可运行
- [ ] 链接有效
- [ ] Markdown 格式正确
- [ ] 逻辑完整

文档编写规范

Markdown 格式

# 一级标题（文档标题）
## 二级标题（主要章节）
### 三级标题（子章节）

- 无序列表
1. 有序列表

**加粗文本**
`行内代码`

​```python
# 代码块
def example():
    pass
​```

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

代码示例

# ✅ 完整可运行
from backend.core.trading.utils.fee_calculator import FeeCalculator
from backend.core.models.broker import FeeConfig

fee_config = FeeConfig()
calculator = FeeCalculator(fee_config)
fee = calculator.calculate_fee(
    quantity=Decimal("100"),
    price=Decimal("150"),
    side="buy",
    market="US"
)

# ❌ 不完整
calculator = FeeCalculator()
fee = calculator.calculate()  # 参数不明确

架构图

使用 Mermaid 绘制：

​```mermaid
graph TB
    A[模块A] --> B[模块B]
    B --> C[模块C]
​```

贡献流程

1. Fork 和 Clone

# Fork 项目到你的 GitHub 账号

# Clone 到本地
git clone https://github.com/YOUR_USERNAME/fire.git
cd fire

# 添加上游仓库
git remote add upstream https://github.com/ORIGINAL_OWNER/fire.git

2. 创建分支

# 功能分支
git checkout -b feature/your-feature-name

# 修复分支
git checkout -b fix/bug-description

3. 开发和测试

# 运行测试
./scripts/test.sh all

# 或手动测试
cd backend && source venv/bin/activate
pytest tests/ -v

# 代码检查
./scripts/lint-fix.sh
flake8 backend/
mypy backend/

测试说明：

4. 提交变更

# 添加变更
git add .

# 提交（使用清晰的提交信息）
git commit -m "feat: 添加新功能

- 实现 XXX 功能
- 更新相关文档
- 添加测试用例"

# 推送
git push origin feature/your-feature-name

5. 创建 Pull Request

  1. 访问你的 Fork
  2. 点击 “New Pull Request”
  3. 填写 PR 模板
  4. 确保勾选所有文档检查项
  5. 提交 PR

测试要求

CI 自动化测试

所有 PR 会自动触发：

✅ 代码格式检查 (flake8, ESLint)
✅ 类型检查 (mypy, TypeScript)
✅ 单元测试（无外部依赖）
✅ 集成测试（Redis 依赖）
✅ E2E 测试（真实长桥 API）
✅ 测试覆盖率报告

覆盖率要求

测试命令

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

# 运行特定测试
pytest backend/tests/unit/test_fee_calculator.py -v

# 生成覆盖率报告
pytest backend/tests/ --cov=backend/core --cov-report=html
open htmlcov/index.html

代码审查标准

代码质量

文档完整性

测试覆盖

向后兼容

Bug 报告

报告方式

  1. 检查 Issue 列表，确认问题未被报告
  2. 创建新 Issue，使用 “Bug Report” 模板
  3. 提供以下信息：
## 问题描述
简要描述遇到的问题

## 复现步骤
1. 执行操作 A
2. 执行操作 B
3. 观察到问题

## 期望行为
描述期望的正确行为

## 实际行为
描述实际发生的错误行为

## 环境信息
- OS: macOS 14.0
- Python: 3.13
- 相关依赖版本

## 相关日志
​```
粘贴错误日志
​```

功能请求

  1. 检查 Issue 列表和文档，确认功能不存在
  2. 创建新 Issue，使用 “Feature Request” 模板
  3. 详细描述：
    • 功能描述
    • 使用场景
    • 预期收益
    • 可能的实现方案

获取帮助

遇到问题时：

  1. 查看 开发指南
  2. 查看 架构文档
  3. 在 Issue 中提问
  4. 联系维护者

文档部署

GitHub Pages 自动部署

文档通过 GitHub Pages 自动部署，支持：

部署流程

  1. 推送代码到 main 分支
  2. GitHub Pages 自动构建
  3. 约 2-10 分钟后生效

Mermaid 图表

​```mermaid
graph TD
    A[开始] --> B{是否配置?}
    B -->|是| C[显示图表]
    B -->|否| D[显示代码块]
    C --> E[结束]
    D --> E
​```

故障排除

Mermaid 不显示：

主题样式不显示：

文档检查

提交前：

部署后：