claude_dev
8dd1cf326d
- 基于 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>
342 lines
6.3 KiB
Markdown
342 lines
6.3 KiB
Markdown
# 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/)
|