# dragonquant

**Repository Path**: xfzhou95/dragonquant

## Basic Information

- **Project Name**: dragonquant
- **Description**: DragonQuant，中文名“龙宽”。“龙”是中国的象征，代表着项目的本土化基因，专为国情复杂的A股市场设计；“宽”（Quant）则点明了其“量化”的内核。我们希望它能像一条游龙，在中国独特的金融市场中，赋予使用者宽广的视野和强大的分析能力。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-19
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DragonQuant (龙宽) 

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-Alpha-orange.svg)]()
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

`DragonQuant` 是一个为中国A股市场量化交易而生的、纯Python实现的、轻量级但功能强大的回测框架。它专为策略研究者和量化爱好者设计，让您可以将精力完全集中在策略逻辑的开发与验证上，而无需为繁杂的底层实现分心。

## 🎯 设计理念

我们的设计哲学是 **"回测即研究"**。每一次回测都不仅仅是得到一个净值，而是生成一份包含**深度分析、丰富指标和高度可视化图表**的完整研究报告，为您的策略优化提供最强大的数据支持。

## ✨ 特色优势

- 🚀 **纯Python实现**：简洁的API设计，易于上手
- 📊 **专业级回测分析**：完整的性能指标和可视化报告
- 🛡️ **A股特性深度集成**：考虑实际交易规则和成本
- 🔌 **高度可扩展**：模块化设计，易于定制和扩展

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Status](https://img.shields.io/badge/status-Alpha-orange.svg)]()

`DragonQuant` 是一个为中国A股市场量化交易而生的、纯Python实现的、轻量级但功能强大的回测框架。它专为策略研究者和量化爱好者设计，让您可以将精力完全集中在策略逻辑的开发与验证上，而无需为繁杂的底层实现分心。

我们的设计哲学是 **“回测即研究”**。每一次回测都不仅仅是得到一个净值，而是生成一份包含**深度分析、丰富指标和高度可视化图表**的完整研究报告，为您的策略优化提供最强大的数据支持。

---

## 🎯 核心功能

### 1. 📈 专业级回测报告

- 自动生成独立的、带时间戳的回测报告文件夹
- 详尽的性能指标分析（Sharpe比率、最大回撤、胜率等）
- 清晰的交易记录和持仓分析
- 多维度图表展示（净值曲线、回撤分析等）

### 2. 📊 策略分析仪表盘

- 为每只交易股票生成多维度K线分析图
- 集成关键技术指标（MA、RSI、ATR等）
- 清晰标记买卖点位和持仓区间
- 支持自定义指标和图表配置

### 3. ⚙️ 事件驱动引擎

- 基于日期的精确事件循环
- 完整支持A股交易规则
- 灵活的数据订阅机制
- 高效的历史数据缓存

### 4. 💹 真实交易模拟

- 精确的交易成本计算（佣金、印花税、最低佣金等）
- 支持T+1交易规则
- 涨跌停板限制
- 实时的仓位和资金管理

### 5. 🛠️ 模块化设计

- 简洁的策略开发接口
- 可扩展的数据源支持
- 灵活的指标计算系统
- 完整的风险管理工具集

---

## 🚀 快速开始

### 安装

1. 克隆项目代码：

```bash
git clone https://github.com/your_username/DragonQuant.git
cd DragonQuant
```

2. 安装依赖：

```bash
# 使用pip安装
pip install -r requirements.txt

# 或者使用poetry（推荐）
poetry install
```

### 准备数据

1. 创建数据目录：

```bash
mkdir -p data
```

2. 准备数据文件：
   - 格式：CSV文件，按股票代码命名
   - 数据类型：日线数据（建议使用后复权价格）
   - 文件命名：`股票代码.csv`（如：`600036.SH.csv`）

示例数据格式：

```csv
date,open,high,low,close,volume
2020-01-02,37.60,38.00,37.50,37.90,12345600
2020-01-03,37.80,38.50,37.70,38.40,23456700
```

> 💡 提示：可以使用内置的 `generate_sample_data.py` 脚本生成示例数据：
> ```bash
> python generate_sample_data.py
> ```

### 开发策略

DragonQuant 提供了多个示例策略，让您快速上手。以下是一个风险平价策略的示例：

```python
# examples/systematic_risk_parity_strategy.py

from dragonquant import Strategy
import dragonquant as dq

class SystematicRiskParityStrategy(Strategy):
    """风险平价策略
    - 使用ATR动态调整每笔交易的风险敞口
    - 基于趋势和RSI进行交易决策
    - 实现资金的风险均衡配置
    """
    def init(self):
        # 策略参数配置
        self.sma_window = 120    # 趋势判断周期
        self.rsi_window = 14     # RSI计算周期
        self.atr_window = 20     # ATR计算周期
        self.risk_per_trade = 0.02  # 单笔交易风险上限

    def next(self, context):
        # 策略主逻辑...
        pass

# 运行回测
if __name__ == '__main__':
    cerebro = dq.Cerebro()
    cerebro.add_strategy(SystematicRiskParityStrategy)
    
    # 配置回测参数
    cerebro.set_universe(['000001.SH', '600519.SH'])  # 设置股票池
    cerebro.configure(
        start_date='2020-01-01',
        end_date='2024-12-31',
        initial_cash=1000000,
        data_path='./data'
    )

    # 运行回测并生成报告
    results = cerebro.run()
    if results:
        results.generate_report()  # 生成完整分析报告
```

### 分析结果

运行完成后，在 `backtest_results` 目录下会生成完整的回测分析报告：

```
backtest_results/
└── run_20250719_124601/
    ├── report.txt           # 详细的回测报告
    ├── performance.html     # 交互式图表
    ├── trades_summary.csv   # 交易记录
    └── charts/
        ├── equity_curve.png    # 权益曲线
        ├── drawdown.png        # 回撤分析
        └── trade_charts/       # 个股分析图表
            ├── 000001.SH.png
            └── 600519.SH.png
```

## 📊 分析报告展示

### 1. 详细的性能报告

```
=========================================================
           DragonQuant 回测分析报告
=========================================================

运行ID: run_20250719_124601
生成时间: 2025-07-19 12:46:05

--- 策略参数 ---
移动平均周期: 150天
RSI超卖阈值: 35
风险系数: 0.02

--- 整体表现 ---
初始资金: 1,000,000.00
最终净值: 1,972,843.51
总收益率: 97.28%

--- 风险收益指标 ---
夏普比率(年化): 0.981
最大回撤: -18.23%
年化收益: 23.45%

--- 交易统计 ---
总交易次数: 184
胜率: 58.7%
平均持仓天数: 12.5
```

### 2. 图表分析系统

#### 净值曲线
![净值曲线示例](docs/images/equity_curve_example.png)

#### 交易分析仪表盘
![交易分析示例](docs/images/trade_dashboard_example.png)

## 🏗️ 项目结构

```
dragonquant/
├── __init__.py         # 包初始化文件
├── analysis.py         # 分析模块
├── api.py              # API接口
├── cerebro.py          # 回测引擎核心
├── context.py          # 上下文对象
├── data/               # 数据模块
│   ├── __init__.py
│   ├── base.py         # 数据基类
│   └── tushare_adapter.py  # Tushare数据源适配器
├── data_handler.py     # 数据处理器
├── indicators.py       # 技术指标
├── order.py            # 订单模块
├── portfolio.py        # 投资组合管理
├── strategy.py         # 策略基类
└── utils/              # 工具函数
    └── __init__.py
```

## 🤝 参与贡献

我们欢迎所有形式的贡献，包括但不限于：

- 🐛 报告Bug
- 💡 提出新功能建议
- 📝 改进文档
- 🔨 提交代码

请参阅我们的[贡献指南](CONTRIBUTING.md)了解详情。

### 开发环境设置

```bash
# 1. Fork并克隆项目
git clone https://github.com/<your-username>/DragonQuant.git
cd DragonQuant

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\activate   # Windows

# 3. 安装开发依赖
pip install -r requirements-dev.txt

# 4. 安装pre-commit钩子
pre-commit install
```

## 📝 开发路线图

- [x] 基础回测框架
- [x] 技术指标计算
- [x] 策略开发接口
- [x] 示例策略
- [ ] 实时交易接口支持
- [ ] 因子研究模块
- [ ] 机器学习集成
- [ ] 多策略组合管理
- [ ] 实盘模拟器

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🙏 致谢

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

---

<div align="center">

**DragonQuant** ❤️ **Made with love for quant traders**

[使用指南](USAGE.md) · [示例](examples/) · [贡献指南](CONTRIBUTING.md)

</div>