# ETF轮动策略框架

基于抽象接口的量化交易框架，支持因子计算、信号生成、风控管理和回测执行。

## 架构设计

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              应用层 (Applications)                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐               │
│  │   Rotation      │  │   Screener      │  │   自定义策略     │               │
│  │   Strategy      │  │   Strategy      │  │   (继承框架)     │               │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘               │
└───────────┼────────────────────┼────────────────────┼─────────────────────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            定制组件层 (strategies/shared)                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │  factors/           │  signals/           │  risk/              │ data/│   │
│  │  ├─ MomentumFactor  │  ├─ TopNSelector    │  ├─ StopLossControl │ ...  │   │
│  │  ├─ TrendFactor     │  ├─ TrendFollower   │  ├─ PremiumControl  │      │   │
│  │  ├─ ReversalFactor  │  ├─ ReversalTrader  │  ├─ Callbacks       │      │   │
│  │  └─ VolatilityFactor│                     │                     │      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            框架抽象层 (framework)                            │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  factors/   │  │  signals/   │  │   risk/     │  │ execution/  │         │
│  │  FactorBase │  │SignalGen   │  │ RiskControl │  │ Executor    │         │
│  │  Registry   │  │             │  │ CallbackHook│  │ Portfolio   │         │
│  │  Combiner   │  │             │  │ Position    │  │             │         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                          │
│  │  strategy/  │  │   data/     │  │   config/   │                          │
│  │ StrategyBase│  │ DataSource  │  │ ConfigLoader│                          │
│  │             │  │ DataCache   │  │             │                          │
│  └─────────────┘  └─────────────┘  └─────────────┘                          │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 核心特性

### 1. 框架抽象接口（framework）

只提供抽象基类，不含具体实现：

- **FactorBase**：因子抽象基类 + FactorRegistry注册器 + FactorCombiner组合器
- **SignalGenerator**：信号生成抽象基类
- **RiskControl**：风控抽象基类 + CallbackHook回调机制
- **StrategyBase**：策略抽象基类（含回调自动注册）
- **Executor/Portfolio**：执行器抽象 + 持仓管理

### 2. 定制组件（strategies/shared）

具体实现，可跨策略复用：

- **MomentumFactor**：加权线性回归动量 + 崩盘过滤
- **TrendFactor**：MA交叉/MACD趋势因子
- **ReversalFactor**：RSI反转信号
- **TopNSelector**：分散化选股 + 调仓周期控制
- **StopLossControl**：固定止损/跟踪止损
- **PremiumControl**：溢价过滤回调

### 3. 完整回测执行

```python
from framework.execution import BacktestExecutor

executor = BacktestExecutor(
    initial_capital=100000,
    trade_cost=0.001,
    select_num=3
)

portfolio = executor.execute(signals, data)
# 支持日收益率计算、交易成本扣除、净值归一化、基准对比
```

## 项目结构

```
.
├── framework/                    # 框架抽象接口
│   ├── factors/                  # FactorBase/Registry/Combiner
│   ├── signals/                  # SignalGenerator抽象
│   ├── risk/                     # RiskControl/Position/CallbackHook
│   ├── strategy/                 # StrategyBase抽象
│   ├── execution/                # Executor/Portfolio/BacktestExecutor
│   ├── data/                     # DataSource/DataCache抽象
│   ├── config/                   # ConfigLoader配置加载
│   └── tests/                    # 单元测试
│
├── strategies/                   # 策略实现
│   ├── shared/                   # 定制组件（跨策略复用）
│   │   ├── factors/              # MomentumFactor/TrendFactor等
│   │   ├── signals/              # TopNSelector/TrendFollower等
│   │   ├── risk/                 # StopLossControl/PremiumControl等
│   │   └── data/                 # HybridDataSourceAdapter等
│   ├── rotation/                 # 轮动策略
│   │   └── strategy.py           # RotationStrategy实现
│   └── screener/                 # CCI选股策略
│
├── config/                       # 配置文件
│   └── strategies/
│       └── rotation.yaml         # 轮动策略配置
│
├── visualization/                # 可视化
│   └── report_generator/         # 报告生成
│
├── data/                         # 数据目录
├── docs/                         # 文档目录
├── archive/                      # 归档旧代码
│
├── .env                          # 环境变量
├── .dockerignore                 # Docker忽略
├── build-and-push.sh             # 构建脚本
├── docker-compose.yml            # Docker部署
├── Dockerfile                    # 应用镜像
├── Dockerfile_base               # 基础镜像
├── hk_ecs.pem                      # SSH密钥（港美股数据隧道）
├── README.md                     # 本文件
└── requirements.txt              # 依赖
```

## 快速开始

### 1. 运行回测

```bash
# 使用默认配置
python run_rotation.py

# 指定配置文件
python run_rotation.py --config config/strategies/rotation.yaml

# 指定报告保存路径
python run_rotation.py --save-path results/my_rotation
```

### 2. 代码方式使用框架

```python
from framework import FactorBase, FactorRegistry, SignalGenerator, StrategyBase
from strategies.shared.factors.momentum import MomentumFactor
from strategies.shared.signals.selectors import TopNSelector

# 注册因子
FactorRegistry.register(MomentumFactor)

# 创建因子组合器
factor = FactorRegistry.get('momentum', n_days=25, crash_filter=True)
combiner = FactorCombiner([factor])

# 创建信号生成器（支持分散化选股）
selector = TopNSelector(
    select_num=3,
    group_mapping={'399006.SZ': 'A', 'NDX': 'US'},  # 按大类分组
    min_score=0.0,      # 过滤负分
    rebalance_days=1,   # 调仓周期
    rebalance_threshold=0.05  # 调仓阈值
)

# 生成信号
signals = selector.generate(factor_data)
```

### 3. 运行测试

```bash
# 框架单元测试
python -m pytest framework/tests/ -v

# 对比测试（验证新旧实现一致性）
python tests/full_backtest_comparison.py
```

## 设计原则

| 模块 | 职责 | 位置 |
|------|------|------|
| **抽象接口** | 所有策略共用的基础设施 | framework |
| **定制组件** | 具体实现，可跨策略复用 | strategies/shared |
| **策略实现** | 业务逻辑，使用框架+组件 | strategies/{name} |

## 技术栈

- **Python 3.12**：核心语言
- **Pandas/NumPy**：数据处理
- **PyYAML**：配置加载
- **scikit-learn**：因子计算（加权回归）
- **pytest**：单元测试

## 归档说明

旧代码已移动到 `archive/` 目录，包括：
- 原 `core/` 目录（数据源、因子计算）
- 原 `strategies/rotation/engine.py`（旧引擎）
- 原 `scripts/`（旧脚本入口）
- 原 `tests/`（旧测试文件）

详见 [archive/README.md](archive/README.md)