ZQuant量化分析平台

ZQuant量化分析平台是一个基于FastAPI的股票量化分析系统，提供数据服务、回测引擎、策略管理等功能。

功能特性 • 快速开始 • 文档 • 常见问题 • 贡献指南 • 许可证

📖 项目简介

ZQuant量化分析平台是一个功能完整的股票量化分析系统，旨在为量化分析者提供从数据采集、策略开发、回测分析到结果管理的一站式解决方案。

✨ 核心亮点

🚀 开箱即用：完整的量化分析系统，无需从零开始搭建
📊 数据驱动：集成Tushare专业数据源，自动采集和清洗股票数据
🔬 回测引擎：事件驱动的回测系统，支持多种策略类型和全面的绩效分析
🎯 策略模板：内置8种常用策略模板，快速上手量化分析
🔐 安全可靠：基于JWT的认证和RBAC权限控制，保障系统安全
⚡ 高性能：基于FastAPI构建，支持异步处理和分布式任务队列

功能特性

🚀 核心功能

📊 数据管理: 支持Tushare数据源，自动采集、清洗和存储股票数据
- 支持分表存储，提高查询性能
- 自动汇总分表同步日志，便于监控和管理
- 支持数据视图，统一查询接口
🔬 回测引擎: 事件驱动的回测系统，支持多种策略类型
📈 策略管理: 完整的策略增删改查功能，支持策略模板库
📉 绩效分析: 全面的回测绩效指标，包括夏普比率、最大回撤等
👥 用户系统: 基于JWT的认证和RBAC权限控制
🔐 API密钥: 灵活的API密钥管理机制
🔔 通知系统: 完整的用户通知功能，支持系统通知、策略通知等
⏰ 定时任务: 强大的任务调度系统，支持Cron表达式和间隔调度
📋 数据日志: 完整的数据操作日志记录，支持分表汇总
⭐ 我的自选: 用户股票自选管理功能，支持添加、查询、更新、删除自选股票，记录关注理由
💼 我的持仓: 用户股票持仓管理功能，支持记录持仓数量、成本价、买入日期等信息，自动计算市值和盈亏

🎯 策略模板

系统内置8种策略模板，涵盖技术分析、基本面分析和量化策略：

技术分析类: 简单均线、双均线、布林带、RSI
基本面类: PE/PB价值策略
量化策略类: 动量策略、均值回归、网格交易

🛠️ 技术栈

后端框架: FastAPI - 现代、快速的Python Web框架
数据库: MySQL - 可靠的关系型数据库
ORM: SQLAlchemy - Python SQL工具包和ORM
缓存: Redis - 高性能内存数据库
异步任务: Celery - 分布式任务队列
定时任务: APScheduler - Python任务调度库
数据源: Tushare - 专业的金融数据服务
认证: JWT - 无状态的认证机制

项目结构

zquant/
├── zquant/              # 主包
│   ├── api/            # API路由
│   │   ├── decorators.py  # API装饰器（统一错误处理）
│   │   └── v1/         # API版本1
│   ├── models/         # 数据库模型
│   ├── schemas/        # Pydantic模型
│   ├── services/       # 业务逻辑层
│   ├── core/           # 核心功能
│   ├── data/           # 数据模块
│   │   ├── storage.py      # 数据存储服务
│   │   ├── storage_base.py # 数据存储基类（公共逻辑）
│   │   └── etl/        # ETL流程
│   ├── scheduler/      # 调度器
│   │   └── job/        # 调度任务
│   │       ├── base.py     # 调度脚本基类
│   │       └── sync_*.py   # 数据同步脚本
│   ├── repositories/   # Repository层（统一数据访问）
│   │   ├── trading_date_repository.py
│   │   ├── stock_repository.py
│   │   ├── price_data_repository.py
│   │   └── factor_repository.py
│   ├── services/       # 业务逻辑层
│   │   └── sync_strategies/  # 数据同步策略（Strategy模式）
│   ├── utils/          # 工具函数
│   │   ├── code_converter.py  # 代码转换工具
│   │   ├── date_helper.py     # 日期处理工具
│   │   ├── query_builder.py   # 查询构建器
│   │   └── cache_decorator.py # 缓存装饰器
│   ├── constants/      # 常量管理
│   │   ├── data_constants.py
│   │   ├── factor_constants.py
│   │   └── api_constants.py
│   ├── api/            # API路由
│   │   └── helpers/    # API辅助类
│   └── backtest/       # 回测引擎
├── web/                # 前端
│   └── src/
│       ├── hooks/          # React Hooks
│       │   ├── useDataQuery.ts      # 数据查询Hook
│       │   ├── useDataValidation.ts # 数据校验Hook
│       │   └── useDataSync.ts       # 数据同步Hook
│       ├── components/     # 组件
│       │   ├── DataTable/      # 数据表格组件
│       │   └── DataTablePage/  # 通用数据表格页面组件
│       └── pages/         # 页面
├── docs/               # 文档
│   ├── refactoring_summary.md      # 历史重构总结
│   └── refactoring_2025_summary.md # 2025重构总结
└── zquant/
    ├── alembic/        # 数据库迁移
    ├── scripts/        # 脚本
    ├── strategy/
    │   └── examples/   # 示例策略
    └── tests/          # 测试

架构设计

代码复用架构

项目采用分层架构，通过基类和工具函数实现代码复用：

工具函数层 (zquant/utils/): 提供通用的工具函数
基类层 (zquant/*/base.py): 提供公共逻辑的基类
业务层: 实现具体的业务逻辑

主要重构成果

✅ 数据存储层：代码重复度降低 > 50%
✅ 调度脚本：统一参数解析和错误处理
✅ API层：统一错误处理和响应转换
✅ 前端：统一数据查询和表格展示逻辑

详细重构说明请参考：

2025重构总结 - 最新重构成果（Repository模式、批量查询优化、Strategy模式等）
历史重构总结 - 早期重构成果

历史优化成果

✅ 统一API响应格式: 创建了统一的响应模型和装饰器
✅ 统一输入验证: 实现了通用验证器，减少重复代码
✅ 优化依赖注入: 优化了数据库连接池和会话管理
✅ 统一日志记录: 添加了请求ID追踪和结构化日志
✅ 安全增强: 实现了XSS防护、速率限制、登录保护、审计日志

详细优化说明请参考优化总结文档

快速开始

🐳 Docker 部署（推荐）

使用 Docker Compose 一键部署，包含应用、MySQL、Redis 等服务：

# 1. 配置环境变量
cp docker/.env.example docker/.env
# 编辑 docker/.env，修改 SECRET_KEY、DB_PASSWORD、TUSHARE_TOKEN 等配置

# 2. 启动所有服务
docker-compose up -d

# 3. 初始化数据库（首次部署）
docker-compose exec zquant-app python3 -m zquant.scripts.init_db
docker-compose exec zquant-app python3 -m zquant.scripts.init_scheduler
docker-compose exec zquant-app python3 -m zquant.scripts.init_view
docker-compose exec zquant-app python3 -m zquant.scripts.init_strategies

# 4. 访问应用
# 前端: http://localhost
# API 文档: http://localhost/docs

Docker 部署特性：

✅ 前后端代码自动混淆打包
✅ 一键启动所有服务（应用、MySQL、Redis）
✅ 生产环境就绪
✅ 健康检查和自动重启
✅ 数据持久化

详细说明请参考 Docker 部署文档

传统部署方式

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

复制 .env.example 为 .env 并修改配置：

cp .env.example .env

关键配置项说明：

配置项	说明	必填
`DATABASE_URL`	MySQL数据库连接地址	✅
`REDIS_URL`	Redis连接地址（用于缓存和任务队列）	✅
`TUSHARE_TOKEN`	Tushare API Token（获取股票数据）	✅
`SECRET_KEY`	JWT密钥（用于生成Token）	✅
`ALGORITHM`	JWT算法（默认HS256）	❌

更多配置说明请参考 .env.example 文件中的注释。

3. 初始化数据库

方式一：使用初始化脚本（推荐）

# 从项目根目录运行
# 1. 初始化数据库和基础表
python zquant/scripts/init_db.py

# 2. 初始化定时任务系统
python zquant/scripts/init_scheduler.py

# 3. 创建数据视图
python zquant/scripts/init_view.py

# 4. 导入策略模板
python zquant/scripts/init_strategies.py

方式二：使用Alembic迁移

# 创建数据库
mysql -u root -p -e "CREATE DATABASE zquant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 运行迁移
alembic upgrade head

注意： 使用初始化脚本会自动创建数据库（如果不存在），并创建所有必要的表、角色、权限和初始数据。详细说明请参考脚本使用说明。

4. 启动服务

uvicorn zquant.main:app --reload --host 0.0.0.0 --port 8000

重要提示：

--host 0.0.0.0 表示监听所有网络接口，允许从任何IP访问
访问时使用 http://localhost:8000 或 http://127.0.0.1:8000
不要使用 http://0.0.0.0:8000 访问（这是服务器绑定地址，不是客户端访问地址）
从其他机器访问时，使用服务器的实际IP地址，例如：http://192.168.1.100:8000

详细说明请参考 API_ACCESS.md

5. 访问API文档

Swagger UI: http://localhost:8000/docs - 交互式API文档，可以直接测试接口
ReDoc: http://localhost:8000/redoc - 美观的API文档展示

6. 验证安装

访问 http://localhost:8000/health 检查服务是否正常运行，应该返回：

{
  "status": "healthy",
  "timestamp": "2025-01-XX XX:XX:XX"
}

7. 启动前端（可选）

如果需要使用Web界面：

cd web
npm install
npm start

前端默认运行在 http://localhost:8001

功能模块

1. 用户管理

用户认证（JWT）
基于角色的访问控制（RBAC）
API密钥管理

2. 数据模块

数据采集（Tushare）
数据存储和清洗
复权处理
数据服务API

3. 回测引擎

策略接口（BaseStrategy基类）
事件驱动回测（按交易日历推进）
交易成本模拟（佣金、印花税、滑点）
绩效分析（夏普比率、最大回撤、Alpha/Beta等）

4. 策略管理

策略增删改查
策略模板库
策略分类和搜索
支持从策略库选择或直接提供代码

📚 文档

核心文档

📖 Docker 部署指南 - 完整的 Docker 容器化部署方案
📖 API访问指南 - API访问配置说明和常见问题
📖 数据库初始化指南 - 数据库初始化流程和表名规范
📖 策略管理文档 - 策略管理系统完整使用指南
📖 调度器指南 - 定时任务调度系统使用指南
📖 前端组件开发指南 - 前端组件使用说明和最佳实践
📖 重构总结 - 项目架构重构说明
📖 脚本使用说明 - 所有初始化和管理脚本的使用说明

快速链接

🔗 项目文档网站 - 完整的项目文档和API参考
🔗 GitHub Issues - 报告问题或提出功能请求
🔗 GitHub Discussions - 参与讨论和交流

❓ 常见问题

安装和部署

Q: 如何配置数据库连接？

A: 在 .env 文件中设置 DATABASE_URL，格式为：

DATABASE_URL=mysql+pymysql://用户名:密码@主机:端口/数据库名

Q: 如何获取Tushare Token？

A: 访问 Tushare官网注册账号并获取Token，然后在 .env 文件中配置 TUSHARE_TOKEN。

Q: 服务启动后无法访问？

A: 请检查：

是否使用了正确的访问地址（http://localhost:8000 而不是 http://0.0.0.0:8000）
防火墙是否允许8000端口
服务是否正常启动（查看日志）

详细说明请参考 API访问指南。

使用问题

Q: 如何创建第一个策略？

A: 参考策略管理文档，系统提供了8种策略模板，可以直接使用或基于模板进行修改。

Q: 如何配置定时任务？

A: 参考调度器指南，系统支持Cron表达式和间隔调度两种方式。

Q: 回测结果如何解读？

A: 系统提供了全面的绩效指标，包括：

收益率（总收益率、年化收益率）
风险指标（最大回撤、波动率）
风险调整收益（夏普比率、Alpha、Beta）

开发问题

Q: 如何贡献代码？

A: 请查看贡献指南，了解代码规范和提交流程。

Q: 如何运行测试？

A: 使用 pytest 命令运行测试，确保所有测试通过后再提交代码。

Q: 代码格式化工具如何使用？

A: 项目使用 ruff 进行代码检查和格式化，详见开发部分。

⚖️ 法律声明

用户协议 - 了解平台使用条款、用户权利和义务
免责申明 - 了解投资风险提示和免责条款

重要提示：本平台展示的股票列表是基于公开市场数据和分析工具得出的结果，仅供参考，不构成任何投资建议。投资有风险，入市需谨慎。

🤝 贡献

我们欢迎所有形式的贡献！ZQuant 是一个开源项目，您的参与对我们非常重要。

如何贡献

Fork 项目：点击右上角的 Fork 按钮
创建分支：git checkout -b feature/your-feature-name
提交更改：git commit -m 'Add some feature'
推送分支：git push origin feature/your-feature-name
提交PR：在GitHub上创建Pull Request

贡献方式

🐛 报告Bug：提交Issue
💡 提出功能请求：提交Feature Request
📝 改进文档：修复文档错误或添加新内容
💻 提交代码：修复Bug或实现新功能
🌟 推广项目：给项目一个Star，分享给更多人

贡献指南

请查看贡献指南了解详细的代码规范、提交流程和开发指南。

💬 社区和支持

我们非常重视社区反馈和支持，欢迎通过以下方式联系我们：

联系方式

📧 邮箱: [email protected]
💬 微信: zquant2025
🐛 问题反馈: GitHub Issues
📚 文档网站: https://github.com/yoyoung/zquant/blob/main/README.md
💬 讨论交流: GitHub Discussions

获取帮助

遇到问题？查看常见问题或提交Issue
有建议？在 Discussions 中分享您的想法
想贡献？查看贡献指南了解如何参与

开发

运行测试

pytest

代码格式化和检查

项目使用 ruff、black 和 isort 进行代码格式化和检查。

安装工具

pip install ruff black isort

或从 requirements.txt 安装：

pip install -r requirements.txt

使用方式

方式一：使用 Ruff（推荐，最快）

Ruff 可以同时进行代码检查和格式化，速度极快：

# 检查代码（不修改文件）
ruff check zquant/

# 自动修复可修复的问题
ruff check --fix zquant/

# 格式化代码（兼容 Black 风格）
ruff format zquant/

# 同时检查和格式化
ruff check --fix zquant/ && ruff format zquant/

方式二：使用 Black + isort（传统方式）

# 格式化代码
black zquant/

# 排序导入
isort zquant/

# 同时执行
black zquant/ && isort zquant/

方式三：使用 Ruff 替代 isort（推荐）

Ruff 内置了 isort 功能，可以替代 isort：

# 使用 Ruff 进行格式化（包含导入排序）
ruff format zquant/

# 使用 Ruff 检查导入顺序
ruff check --select I zquant/

配置文件

项目使用 pyproject.toml 统一管理所有工具的配置：

[tool.ruff] - Ruff 配置（linting 和格式化）
[tool.black] - Black 配置
[tool.isort] - isort 配置

常用命令

# 检查整个项目
ruff check .

# 格式化整个项目
ruff format .

# 只检查特定文件
ruff check zquant/api/v1/config.py

# 只格式化特定文件
ruff format zquant/api/v1/config.py

# 查看所有可修复的问题
ruff check --output-format=concise .

# 自动修复所有可修复的问题
ruff check --fix .

与 IDE 集成

VS Code:

安装扩展：

Ruff (astral-sh.ruff)
Black Formatter (ms-python.black-formatter)

PyCharm:

Settings -> Tools -> External Tools
添加 Ruff 和 Black 作为外部工具
配置快捷键

Pre-commit 集成（可选）

项目包含 .pre-commit-config.yaml 配置文件，可以在 Git 提交时自动运行代码检查：

# 安装 pre-commit
pip install pre-commit

# 安装 Git hooks
pre-commit install

# 手动运行所有检查
pre-commit run --all-files

安装后，每次 git commit 时会自动运行 ruff 检查。如果不想使用，可以运行 pre-commit uninstall 卸载。

注意事项

Ruff 可以替代 isort 和 black（ruff format 兼容 black 风格）
如果同时使用多个工具，建议先运行 ruff format，再运行 black（如果使用）
配置文件中已设置行长度为 120 字符
所有工具配置保持一致，避免冲突
Pre-commit 是可选的，如果不需要可以卸载：pre-commit uninstall

许可证

本项目采用 Apache License 2.0 许可证。

Copyright 2025 ZQuant Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

致谢

感谢所有为这个项目做出贡献的开发者和用户！

⭐ 如果这个项目对你有帮助，请给我们一个Star！

Made with ❤️ by ZQuant Team

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
docker		docker
docs		docs
node_modules		node_modules
web		web
zquant		zquant
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
API_ACCESS.md		API_ACCESS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
IMPLEMENTATION.md		IMPLEMENTATION.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
check_tables.py		check_tables.py
docker-compose.yml		docker-compose.yml
fix_data_file.py		fix_data_file.py
verify_hsl_import.py		verify_hsl_import.py
yarn.lock		yarn.lock

License

thoughtgo/zquant

Folders and files

Latest commit

History

Repository files navigation