sanguo_vnpy_v2/docs/development.md

Sanguo VeighNa 开发指南

一、开发工作流

1.1 功能开发流程

# 1. 从 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 2. 开发并提交
git add .
git commit -m "feat: 添加CTP接口网关"

# 3. 推送到远程
git push origin feature/your-feature-name

# 4. 在 Gitea 创建 Pull Request 到 develop
# 5. 代码审查通过后合并

1.2 热修复流程

# 1. 从 master 创建修复分支
git checkout master
git pull origin master
git checkout -b hotfix/critical-bug-fix

# 2. 修复并提交
git add .
git commit -m "fix: 修复订单撤单bug"

# 3. 推送并创建 PR 到 master
git push origin hotfix/critical-bug-fix

# 4. 合并后同步到 develop

1.3 发布流程

# 1. 从 develop 创建发布分支
git checkout develop
git pull origin develop
git checkout -b release/v1.0.0

# 2. 更新版本号和 CHANGELOG
# 3. 合并到 master
git checkout master
git merge release/v1.0.0

# 4. 打标签
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

# 5. 同步回 develop
git checkout develop
git merge release/v1.0.0

---

二、提交信息规范

使用 Conventional Commits 规范：

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

类型说明

类型	说明	示例
feat	新功能	feat: 添加沪深300行情接口
fix	修复bug	fix: 修复K线数据时间戳错误
docs	文档更新	docs: 更新API文档
style	代码格式	style: 统一代码缩进
refactor	重构	refactor: 重构事件引擎
perf	性能优化	perf: 优化历史数据查询
test	测试	test: 添加订单模块测试
chore	构建/工具	chore: 更新依赖版本

范围说明

范围	说明
gateway	交易接口
strategy	策略模块
data	数据模块
ui	用户界面
alpha	AI量化模块
common	公共模块

示例

# 简单提交
git commit -m "feat: 添加CTP接口网关"

# 带范围的提交
git commit -m "fix(gateway): 修复订单撤单超时问题"

# 带说明的提交
git commit -m "feat(strategy): 添加网格交易策略

- 支持多合约网格
- 支持动态网格调整
- 添加风险控制功能

Closes #123"

---

三、代码审查流程

3.1 Pull Request 模板

在 Gitea 设置 PR 模板（.github/pull_request_template.md）：

## 变更说明
<!-- 简要描述此 PR 的内容 -->

## 变更类型
- [ ] feat: 新功能
- [ ] fix: 修复bug
- [ ] docs: 文档更新
- [ ] refactor: 重构
- [ ] 其他: _____

## 相关 Issue
Closes #

## 测试说明
<!-- 说明如何测试此次变更 -->

## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的测试
- [ ] 文档已更新
- [ ] 通过所有测试

3.2 审查要点

1. 代码质量

   • 遵循 PEP 8 规范
   • 类型注解完整
   • 文档字符串完整

2. 功能正确性

   • 逻辑正确
   • 边界条件处理
   • 异常处理完善

3. 性能考虑

   • 避免不必要的计算
   • 合理使用缓存
   • 注意内存使用

4. 安全性

   • 输入验证
   • 权限检查
   • 敏感信息保护

---

四、测试策略

4.1 测试目录结构

tests/
├── unit/              # 单元测试
│   ├── test_gateway/
│   ├── test_strategy/
│   └── test_data/
├── integration/       # 集成测试
│   ├── test_trading_flow/
│   └── test_data_pipeline/
└── fixtures/          # 测试数据

4.2 测试运行

# 运行所有测试
pytest

# 运行特定测试
pytest tests/unit/test_gateway/

# 带覆盖率报告
pytest --cov=sanguo_trader --cov-report=html

---

五、版本管理

5.1 版本号格式

遵循 Semantic Versioning：

MAJOR.MINOR.PATCH

例：1.2.3
- MAJOR: 不兼容的API变更
- MINOR: 向后兼容的功能新增
- PATCH: 向后兼容的问题修复

5.2 版本发布检查清单

• 更新版本号（__init__.py）
• 更新 CHANGELOG.md
• 运行完整测试套件
• 更新文档
• 创建 Git 标签
• 推送到 Gitea
• 通知团队成员

---

六、持续集成（可选）

6.1 Gitea Actions 配置

创建 .gitea/workflows/test.yml：

name: Tests

on:
  push:
    branches: [ master, develop ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements/base.txt
          pip install pytest pytest-cov
      - name: Run tests
        run: pytest --cov=sanguo_trader

---

七、成果物管理

7.1 发布管理

在 Gitea 中创建 Release：

1. 进入项目的 "Releases" 页面
2. 点击 "New Release"
3. 填写版本号和发布说明
4. 上传附件（可选）

7.2 文档管理

• API 文档: 使用 Sphinx 生成
• 用户手册: 存放在 docs/user/
• 开发文档: 存放在 docs/development/
• 更新日志: CHANGELOG.md

---

八、协作规范

8.1 任务分配

使用 Gitea Issues 跟踪任务：

• 标签：feature、bug、enhancement、documentation
• 里程碑：按版本规划
• 负责人：明确任务负责人

8.2 日常协作

1. 每日从 develop 拉取最新代码
2. 保持功能分支小而专注
3. 及时提交和推送代码
4. 及时响应 PR 审查意见
5. 合并后删除已完成的分支

---

九、故障排查

9.1 常见问题

问题：合并冲突

# 获取最新代码
git fetch origin

# 重新基于 develop
git rebase origin/develop

# 解决冲突后
git add .
git rebase --continue

问题：提交错误

# 修改最后一次提交
git commit --amend

# 撤销提交（保留改动）
git reset --soft HEAD~1

---

十、相关资源

• VeighNa 官方文档
• VeighNa GitHub
• Conventional Commits
• Semantic Versioning