commit 8dd1cf326df0477e662e4a616e922b7f07a29cf2 Author: claude_dev Date: Thu Jun 25 18:51:39 2026 +0800 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) diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..f32dcae --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,41 @@ +--- +name: Bug 报告 +about: 报告项目中的问题 +title: '[Bug] ' +labels: 'bug' +assignees: '' +--- + +## Bug 描述 + + + +## 复现步骤 + + + +## 期望行为 + + + +## 实际行为 + + + +## 环境信息 +- OS: [e.g. Windows 11, Ubuntu 22.04] +- Python Version: [e.g. 3.11] +- Project Version: [e.g. 0.1.0] + + +## 日志/截图 + + + +## 其他信息 + diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md new file mode 100644 index 0000000..d2e4ffe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -0,0 +1,26 @@ +--- +name: 功能请求 +about: 建议新功能或改进 +title: '[Feature] ' +labels: 'enhancement' +assignees: '' +--- + +## 功能描述 + + + +## 需求背景 + + + +## 期望行为 + + + +## 替代方案 + + + +## 附加信息 + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8132035 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,33 @@ +## 变更说明 + + + +## 变更类型 +- [ ] feat: 新功能 +- [ ] fix: 修复bug +- [ ] docs: 文档更新 +- [ ] refactor: 重构 +- [ ] perf: 性能优化 +- [ ] test: 测试 +- [ ] chore: 构建/工具 +- [ ] 其他: _____ + + +## 相关 Issue +Closes # + + +## 测试说明 + + + +## 检查清单 +- [ ] 代码遵循项目规范 (ruff check 通过) +- [ ] 已添加必要的测试 +- [ ] 文档已更新 +- [ ] 通过所有测试 (pytest 通过) +- [ ] 类型检查通过 (mypy) + + +## 其他说明 + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a8176bb --- /dev/null +++ b/.gitignore @@ -0,0 +1,96 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +*.manifest +*.spec + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ +.pytest_cache/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# IDEs +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Project specific +*.log +data/ +logs/ +*.db +*.sqlite +*.parquet +temp/ +tmp/ + +# VeighNa upstream (don't modify directly) +vnpy_v4.4.0/ + +# Knowledge base repositories +knowledge_base/ + +# Other projects +sanguo_projects/ + +# Generated files +*.mo +*.pyc + +# Settings (may contain sensitive info) +setting/ +*.json +!pyproject.toml +!package.json diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..140a4fe --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Initial project structure setup +- Development workflow documentation + +## [0.1.0] - 2025-06-25 + +### Added +- 项目初始化 +- 基于 VeighNa 4.4.0 的开发基础 +- 完整的开发工作流文档 + +--- + +## 版本说明 + +- **Unreleased**: 正在开发中的功能 +- **[版本号] - 日期**: 已发布版本 diff --git a/README.md b/README.md new file mode 100644 index 0000000..c50b385 --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# Sanguo VeighNa 量化交易平台 + +基于 VeighNa 4.4.0 的二次开发量化交易平台。 + +## 项目结构 + +``` +sanguo_vnpy_v2/ +├── vnpy_v4.4.0/ # VeighNa 上游源码 +├── sanguo_trader/ # 核心交易模块 +├── sanguo_research/ # 量化投研模块 +├── sanguo_data/ # 数据管理模块 +├── sanguo_common/ # 公共模块 +├── tests/ # 测试代码 +├── docs/ # 文档 +└── examples/ # 示例代码 +``` + +## 快速开始 + +### 环境要求 + +- Python 3.10+ +- 推荐使用 Python 3.13 + +### 安装 + +```bash +# 创建虚拟环境 +python -m venv venv +source venv/bin/activate # Linux/Mac +# venv\Scripts\activate # Windows + +# 安装依赖 +pip install -r requirements/base.txt +``` + +## 开发指南 + +请查看 [docs/development.md](docs/development.md) 获取详细开发指南。 + +## 分支策略 + +- `master` - 主分支，保持稳定可部署 +- `develop` - 开发分支，日常开发合并 +- `feature/*` - 功能分支 +- `hotfix/*` - 热修复分支 + +## 版本历史 + +查看 [CHANGELOG.md](CHANGELOG.md) + +## 许可证 + +MIT License + +## 致谢 + +基于 [VeighNa](https://github.com/vnpy/vnpy) 框架开发 diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..6a32b67 --- /dev/null +++ b/docs/development.md @@ -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 +## 变更说明 + + +## 变更类型 +- [ ] 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/) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..ef677f2 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,102 @@ +[project] +name = "sanguo-vnpy" +version = "0.1.0" +description = "Sanguo Quantitative Trading Platform based on VeighNa" +readme = "README.md" +license = {text = "MIT"} +authors = [ + {name = "Sanguo Team", email = "team@sanguo.com"} +] +classifiers = [ + "Development Status :: 3 - Alpha", + "License :: OSI Approved :: MIT License", + "Operating System :: Microsoft :: Windows", + "Operating System :: POSIX :: Linux", + "Operating System :: MacOS", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Office/Business :: Financial :: Investment", +] +requires-python = ">=3.10" +dependencies = [ + "tzlocal>=5.3.1", + "PySide6==6.8.2.1", + "pyqtgraph>=0.13.7", + "qdarkstyle>=3.2.3", + "numpy>=2.2.3", + "pandas>=2.2.3", + "ta-lib>=0.6.4", + "deap>=1.4.2", + "pyzmq>=26.3.0", + "plotly>=6.0.0", + "tqdm>=4.67.1", + "loguru>=0.7.3", + "nbformat>=5.10.4", + "requests>=2.32.0", + "qrcode>=7.4.2", +] + +[project.optional-dependencies] +alpha = [ + "polars>=1.26.0", + "scipy>=1.15.2", + "alphalens-reloaded>=0.4.5", + "scikit-learn>=1.6.1", + "lightgbm>=4.6.0", + "torch>=2.6.0", + "pyarrow>=19.0.1", +] +dev = [ + "pytest>=7.0.0", + "pytest-cov>=4.0.0", + "ruff>=0.1.0", + "mypy>=1.5.0", +] +all = [ + "sanguo-vnpy[alpha,dev]", +] + +[project.urls] +"Homepage" = "http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2" +"Repository" = "http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2" +"Documentation" = "http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2/wiki" +"Bug Tracker" = "http://192.168.2.154:3000/sanguo/sanguo_vnpy_v2/issues" + +[build-system] +requires = ["hatchling>=1.27.0"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["sanguo_trader", "sanguo_research", "sanguo_data", "sanguo_common"] + +[tool.ruff] +target-version = "py310" +line-length = 100 + +[tool.ruff.lint] +select = [ + "B", # flake8-bugbear + "E", # pycodestyle error + "F", # pyflakes + "UP", # pyupgrade + "W", # pycodestyle warning + "I", # isort +] +ignore = ["E501"] + +[tool.mypy] +python_version = "3.10" +warn_return_any = true +warn_unused_configs = true +disallow_untyped_defs = true +strict_optional = true + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = "--cov=sanguo_trader --cov=sanguo_research --cov-report=html" diff --git a/requirements/alpha.txt b/requirements/alpha.txt new file mode 100644 index 0000000..9e0d2e6 --- /dev/null +++ b/requirements/alpha.txt @@ -0,0 +1,16 @@ +# Sanguo VeighNa - Alpha Quant Dependencies + +-r base.txt + +# Alpha / ML Requirements (from VeighNa 4.4.0) +polars>=1.26.0 +scipy>=1.15.2 +alphalens-reloaded>=0.4.5 +scikit-learn>=1.6.1 +lightgbm>=4.6.0 +torch>=2.6.0 +pyarrow>=19.0.1 + +# Additional ML Tools +xgboost>=2.0.0 +catboost>=1.2.0 diff --git a/requirements/base.txt b/requirements/base.txt new file mode 100644 index 0000000..7b75513 --- /dev/null +++ b/requirements/base.txt @@ -0,0 +1,25 @@ +# Sanguo VeighNa - Base Dependencies + +# Core Framework (from VeighNa 4.4.0) +tzlocal>=5.3.1 +PySide6==6.8.2.1 +pyqtgraph>=0.13.7 +qdarkstyle>=3.2.3 +numpy>=2.2.3 +pandas>=2.2.3 +ta-lib>=0.6.4 +deap>=1.4.2 +pyzmq>=26.3.0 +plotly>=6.0.0 +tqdm>=4.67.1 +loguru>=0.7.3 +nbformat>=5.10.4 +requests>=2.32.0 +qrcode>=7.4.2 + +# Database Support +# Choose one based on your needs: +# sqlite - Python built-in +# psycopg2-binary>=2.9.0 # PostgreSQL +# pymysql>=1.1.0 # MySQL +# pymongo>=4.0.0 # MongoDB diff --git a/requirements/dev.txt b/requirements/dev.txt new file mode 100644 index 0000000..34c8597 --- /dev/null +++ b/requirements/dev.txt @@ -0,0 +1,24 @@ +# Sanguo VeighNa - Development Dependencies + +-r base.txt + +# Testing +pytest>=7.0.0 +pytest-cov>=4.0.0 +pytest-mock>=3.10.0 +pytest-qt>=4.2.0 + +# Code Quality +ruff>=0.1.0 +mypy>=1.5.0 +black>=23.0.0 +isort>=5.12.0 + +# Documentation +sphinx>=7.0.0 +sphinx-rtd-theme>=1.3.0 + +# Development Tools +ipython>=8.0.0 +ipdb>=0.13.0 +pre-commit>=3.0.0 diff --git a/sanguo_common/__init__.py b/sanguo_common/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sanguo_data/__init__.py b/sanguo_data/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sanguo_research/__init__.py b/sanguo_research/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sanguo_trader/__init__.py b/sanguo_trader/__init__.py new file mode 100644 index 0000000..e69de29