# 框架 V2 - 重构版本

## 📋 设计理念

### 三层架构

```
framework_v2/
├── core/          # 纯抽象接口（零实现）
├── shared/        # 通用实现（2+策略复用）
└── tests/         # 框架测试
```

### 设计原则

1. **按需抽象**：不预先设计，只抽象已验证的通用逻辑
2. **职责分离**：数据获取、因子计算、信号生成、回测执行各司其职
3. **向后兼容**：与现有策略并行运行，验证一致后再替换
4. **测试驱动**：每个组件必须有对比验证测试

---

## 📚 文档

- **[数据架构方案](DATA_ARCHITECTURE.md)** - 完整的数据架构设计（Schema、验证、性能优化）
- **[跨市场对齐方案](ALIGNMENT_GUIDE.md)** - CrossMarketAligner 使用指南
- **[数据流完整推演](DATA_FLOW_DEMO.md)** - 从 OHLCV 到最终收益的 7 个阶段推演
- **[Aligner + Schema 整合方案](ALIGNMENT_SCHEMA_INTEGRATION.md)** - Pydantic Schema 与对齐器结合使用
- **[FlaskAPIFetcher 使用指南](FLASK_API_FETCHER_GUIDE.md)** - 通过 HTTP API 获取线上数据

---

## 🏗️ 目录结构

```
framework_v2/
├── __init__.py
├── README.md
│
├── core/                          # 核心抽象接口
│   ├── __init__.py
│   ├── strategy.py                # StrategyBase (ABC)
│   ├── factor.py                  # FactorBase (ABC)
│   ├── signal.py                  # SignalGenerator (ABC)
│   ├── executor.py                # Executor (ABC)
│   └── data.py                    # DataFetcher (ABC)
│
├── shared/                        # 通用实现
│   ├── __init__.py
│   ├── factors/
│   │   ├── __init__.py
│   │   ├── talib_base.py          # TALibFactorBase (需要 talib)
│   │   └── momentum.py            # 动量因子（已验证✓）
│   ├── data/
│   │   ├── __init__.py
│   │   └── alignment.py           # 跨市场对齐器（已验证✓）
│   └── signals/                   # 待实现
│       └── ...
│
└── tests/                         # 测试
    ├── __init__.py
    └── test_momentum_parity.py    # 因子对比测试（通过✓）
```

---

## ✅ 已完成

### 阶段1: 核心接口层 ✓

- [x] StrategyBase - 策略抽象基类
- [x] FactorBase - 因子抽象基类
- [x] SignalGenerator - 信号生成器抽象基类
- [x] Executor - 执行器抽象基类
- [x] DataFetcher - 数据获取器抽象基类

### 阶段2: 通用因子层 ✓

- [x] MomentumFactor - 动量因子（完全复制现有逻辑）
- [x] 对比验证测试（通过✓，差异 = 0）

### 阶段2.5: 数据对齐层 ✓

- [x] CrossMarketAligner - 跨市场数据对齐器
- [x] 解决 ffill 陷阱（价格 vs 收益率）
- [x] 解决跨市场日历不对齐
- [x] 解决 NaN 传播问题
- [x] 完整测试套件（5/5 通过✓）

---

## 🎯 验证结果

### MomentumFactor 对比测试

```
============================================================
  MomentumFactor 对比测试
============================================================

1. 加载测试数据...
   ⚠ 未找到测试数据，使用模拟数据

2. 计算旧因子（strategies/shared/factors/momentum.py）...
   ✓ 旧因子计算完成
   结果范围: -0.8515 ~ 8.5805
   NaN 数量: 22

3. 计算新因子（framework_v2/shared/factors/momentum.py）...
   ✓ 新因子计算完成
   结果范围: -0.8515 ~ 8.5805
   NaN 数量: 22

4. 对比结果...
   ✓ 索引一致
   最大差异: 0.000000e+00
   平均差异: 0.000000e+00
   ✓ 差异在容差范围内 (< 1e-10)

============================================================
  ✓ 测试通过：新旧因子输出完全一致！
============================================================
```

---

## 📝 下一步计划

### 阶段3: 信号层迁移

- [ ] TopNSelector - Top N 选股器
- [ ] DynamicThreshold - 动态阈值（V3逻辑）
- [ ] RebalanceController - 调仓控制器
- [ ] 信号对比验证测试

### 阶段4: 执行层迁移

- [ ] BacktestRunner - 回测执行器
- [ ] 收益计算对比测试

### 阶段5: 数据层迁移

- [ ] RotationDataFetcher - 轮动策略数据获取器
- [ ] CrossMarketAligner - 跨市场对齐器

### 阶段6: 策略组装

- [ ] RotationStrategyV2 - 新框架轮动策略
- [ ] 完整策略对比测试

---

## 🔧 使用方法

### 运行测试

```bash
# 运行因子对比测试
python framework_v2/tests/test_momentum_parity.py

# 运行所有测试
python -m pytest framework_v2/tests/
```

### 使用新因子

```python
from framework_v2.shared.factors import MomentumFactor

# 创建因子
factor = MomentumFactor(n_days=25, weighted=True, crash_filter=True)

# 计算因子值
import pandas as pd
data = pd.DataFrame({'close': [...]}, index=[...])
factor_values = factor.compute(data)
```

---

## 📊 与旧框架对比

| 维度 | 旧框架 (framework/) | 新框架 (framework_v2/) |
|------|---------------------|------------------------|
| **架构** | 抽象+实现混杂 | 三层分离（core/shared/tests） |
| **因子** | 独立实现 | TALibFactorBase + 定制继承 |
| **信号** | 包含所有逻辑 | 拆分为 Signal + Threshold + Rebalance |
| **数据** | 耦合在策略中 | DataFetcher 抽象 |
| **测试** | 部分覆盖 | 每个组件必须有对比测试 |
| **状态** | 生产环境 ✓ | 开发中 🚧 |

---

## ⚠️ 注意事项

1. **talib 依赖**：TALibFactorBase 需要安装 `ta-lib`，但未安装不影响 MomentumFactor 使用
2. **并行开发**：新框架与旧框架并行，不修改现有代码
3. **验证优先**：每个模块迁移后立即验证，确保结果一致

---

*创建日期: 2026-05-06*
*版本: 2.0.0*