README.md

# QTrading 量化选股系统

QTrading 是一套完整的量化选股系统，严格按照工程化规范实现，所有模块独立分离、结构清晰、可直接运行。

## 项目架构（模块化）

QTrading 采用模块化架构设计，所有功能分到独立模块：

```
QTrading/
├── config/        # 配置文件
├── data/          # 数据获取与存储
├── strategy/      # 策略基类与具体策略
├── engine/        # 选股核心引擎
├── backtest/      # 回测模块
├── web/           # Web GUI 界面
├── utils/         # 工具函数
├── main.py        # 主入口文件
└── requirements.txt # 依赖包列表
```

## 核心功能

### 数据模块（Tushare + SQLite 缓存）
- 从 Tushare 读取原始不复权日线数据
- 存入 SQLite 做本地缓存，支持增量更新
- 数据库只存原始数据，不预先做复权

### 复权功能（核心灵活设计）
- 支持三种模式：前复权 / 后复权 / 不复权
- 在策略基类中统一实现复权计算函数
- Web 界面可选择复权方式，所有指标自动按选择计算

### 策略模块（高度解耦）
- 抽象基类 BaseStrategy，内置通用指标：MA、EMA、波动率、回撤、突破、量价、涨幅等
- 所有指标基于用户选择的复权方式动态计算
- 策略只做一件事：输入单只股票K线数据 → 输出 0~100 分
- 策略不循环、不读库、插件化设计，新增策略只需加类

### 选股引擎
- 遍历股票池 → 从 SQLite 取数据 → 运行用户选中的单个策略
- 按分数从高到低排序输出结果

### 回测功能
- 支持历史回测，按时间滚动选股
- 计算回测指标：年化收益、最大回撤、胜率、盈亏比
- 回测与策略完全解耦

### Web GUI
- 提供简洁可用的 Web 界面
- 支持：选择策略、选择复权方式、启动选股、查看结果、运行回测

## 快速开始

### 安装依赖

```bash
cd QTrading
pip install -r requirements.txt
```

### 配置 Tushare Token

在 `config/config.py` 中配置你的 Tushare Token：

```python
@dataclass
class TushareConfig:
    """Tushare 配置"""
    token: str = "YOUR_TUSHARE_TOKEN"  # 替换为你的 Token
    retry_count: int = 3
    pause: float = 0.1
```

### 运行系统

#### 1. Web 模式（推荐）

启动 Web 服务器：

```bash
python main.py --mode web --host 0.0.0.0 --port 8050 --debug
```

然后在浏览器中访问：`http://localhost:8050`

#### 2. 命令行模式

**选股：**

```bash
python main.py --mode cli --strategy MA20Strategy --adjust-method qfq --top-n 10 --update-data
```

**回测：**

```bash
python main.py --mode cli --strategy RSIStrategy --adjust-method qfq --backtest --start-date 20200101 --end-date 20241231
```

## 使用说明

### 策略开发

在 `strategy` 目录下创建新的策略文件，继承自 `BaseStrategy`，实现 `score` 方法即可：

```python
from strategy.base_strategy import BaseStrategy

class MyStrategy(BaseStrategy):
    """自定义策略"""

    name: str = "MyStrategy"
    description: str = "我的自定义策略"

    def score(self, data: pd.DataFrame) -> float:
        """计算股票得分（0~100）"""
        # 策略逻辑
        return score
```

### 配置股票池

在 `config/config.py` 中配置股票池：

```python
@dataclass
class StockPoolConfig:
    """股票池配置"""
    stock_list: list = [
        "000001", "000002", "000004", "000005", "000006",
        # ... 更多股票代码
    ]
    start_date: str = "20000101"
    end_date: str = "20241231"
```

## 工程化要求

- **配置与代码分离**：所有配置放在 `config/config.py` 中
- **日志、异常处理、数据校验齐全**：每个模块都有完善的日志和异常处理
- **代码规范、注释完整**：遵循 Python 开发规范，代码注释完整
- **结构清晰、易于长期扩展**：模块化设计，新增功能只需添加新模块

## 技术栈

- **核心语言**：Python 3.8+
- **数据获取**：Tushare 数据接口
- **数据存储**：SQLite 数据库
- **Web 框架**：Dash (基于 Flask)
- **可视化**：Plotly、Dash Bootstrap Components
- **数据分析**：Pandas、Numpy、Scipy
- **项目管理**：Black (代码格式化)、Flake8 (代码检查)

## 贡献者

本项目遵循工程化规范，严格按照模块化设计实现。

## 许可证

MIT License