feat: 初始化 Sanguo VeighNa 量化交易平台项目
- 基于 VeighNa 4.4.0 的二次开发基础 - 建立项目目录结构（sanguo_trader/sanguo_research/sanguo_data/sanguo_common） - 配置开发工作流文档和 Git 模板 - 设置 GitHub Flow 分支策略 - 添加依赖管理文件 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,341 @@
|
||||
# Sanguo VeighNa 开发指南
|
||||
|
||||
## 一、开发工作流
|
||||
|
||||
### 1.1 功能开发流程
|
||||
|
||||
```bash
|
||||
# 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 热修复流程
|
||||
|
||||
```bash
|
||||
# 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 发布流程
|
||||
|
||||
```bash
|
||||
# 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](https://www.conventionalcommits.org/) 规范：
|
||||
|
||||
```
|
||||
<类型>[可选 范围]: <描述>
|
||||
|
||||
[可选 正文]
|
||||
|
||||
[可选 脚注]
|
||||
```
|
||||
|
||||
### 类型说明
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|-----|------|------|
|
||||
| `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` | 公共模块 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 简单提交
|
||||
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`）：
|
||||
|
||||
```markdown
|
||||
## 变更说明
|
||||
<!-- 简要描述此 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 测试运行
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
pytest
|
||||
|
||||
# 运行特定测试
|
||||
pytest tests/unit/test_gateway/
|
||||
|
||||
# 带覆盖率报告
|
||||
pytest --cov=sanguo_trader --cov-report=html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、版本管理
|
||||
|
||||
### 5.1 版本号格式
|
||||
|
||||
遵循 [Semantic Versioning](https://semver.org/)：
|
||||
|
||||
```
|
||||
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`：
|
||||
|
||||
```yaml
|
||||
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 常见问题
|
||||
|
||||
**问题：合并冲突**
|
||||
```bash
|
||||
# 获取最新代码
|
||||
git fetch origin
|
||||
|
||||
# 重新基于 develop
|
||||
git rebase origin/develop
|
||||
|
||||
# 解决冲突后
|
||||
git add .
|
||||
git rebase --continue
|
||||
```
|
||||
|
||||
**问题：提交错误**
|
||||
```bash
|
||||
# 修改最后一次提交
|
||||
git commit --amend
|
||||
|
||||
# 撤销提交（保留改动）
|
||||
git reset --soft HEAD~1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、相关资源
|
||||
|
||||
- [VeighNa 官方文档](https://www.vnpy.com/docs)
|
||||
- [VeighNa GitHub](https://github.com/vnpy/vnpy)
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
- [Semantic Versioning](https://semver.org/)
|
||||
Reference in New Issue
Block a user