docs: 添加框架功能完善性分析与通用能力边界设计文档

- 框架功能完善性分析：评估现有轮动策略与新框架对比
- 通用能力与定制开发边界设计：明确框架只放抽象接口
- 总体完善度约45%，数据层和执行层缺失

docs/框架功能完善性分析.md

@@ -0,0 +1,201 @@
+# 框架功能完善性分析报告
+
+## 一、现有轮动策略核心功能清单
+
+### 1.1 数据获取层（HybridDataSource）
+
+| 功能 | 实现位置 | 说明 |
+|------|----------|------|
+| **混合数据源** | `core/datasource/hybrid_source.py` | Tushare(A股) + YFinance(港美股) |
+| **SSH隧道** | `hybrid_source.py` | SOCKS5代理访问境外数据 |
+| **双轨数据架构** | `engine.py:48` | index_data(因子) + etf_data(收益) |
+| **ETF净值数据** | `engine.py:58` | 溢价率计算 |
+| **缓存机制** | `datasource/cache.py` | 本地缓存管理 |
+| **交易日历对齐** | `compute_factors()` | 对齐到A股交易日历 |
+
+### 1.2 因子计算层（compute_factors）
+
+| 功能 | 实现位置 | 说明 |
+|------|----------|------|
+| **加权动量因子** | `calculate_weighted_momentum_score()` | 年化收益率 × R² |
+| **崩盘过滤** | `apply_crash_filter()` | 3天跌>5%清零 |
+| **动态ATR周期** | `auto_day`参数 | 根据波动率调整窗口 |
+| **多因子类型** | `factor_type` | momentum/slope_r2/weighted_momentum |
+
+### 1.3 选股逻辑层（generate_signals）
+
+| 功能 | 实现位置 | 说明 |
+|------|----------|------|
+| **Top N选股** | `engine.py:108-114` | 按得分排序 |
+| **分散化选股** | `engine.py:117-135` | 每大类Top1→全局Top3 |
+| **调仓周期控制** | `rebalance_days` | 持仓至少N天 |
+| **调仓阈值检查** | `_check_rebalance()` | 得分改善阈值 |
+| **负分过滤** | `scores > 0` | 过滤负分标的 |
+
+### 1.4 溢价控制层（premium_control）
+
+| 功能 | 配置位置 | 说明 |
+|------|----------|------|
+| **溢价阈值** | `rotation.yaml:97-114` | 10%阈值 |
+| **按市场配置** | `market_overrides` | 港股/美股启用 |
+| **控制模式** | `mode: filter/penalize` | 完全排除或降权 |
+
+### 1.5 回测执行层（run_backtest）
+
+| 功能 | 实现位置 | 说明 |
+|------|----------|------|
+| **日收益率计算** | `engine.py:246-267` | 多品种等权 |
+| **交易成本扣除** | `engine.py:270-287` | 换手率比例扣除 |
+| **净值计算** | `engine.py:289-292` | 起点归一化 |
+| **基准对比** | `engine.py:305-323` | 沪深300基准 |
+| **持仓跟踪** | `portfolio.py` | 交易记录生成 |
+
+### 1.6 报告生成层（generate_performance_report）
+
+| 功能 | 实现位置 | 说明 |
+|------|----------|------|
+| **KPI指标** | `report.py` | CAGR/Sharpe/MaxDD |
+| **可视化图表** | `report.py` | 净值曲线/月度收益 |
+| **HTML报告** | `visualization/` | Bootstrap样式 |
+
+---
+
+## 二、新框架功能对比
+
+### 2.1 已实现功能 ✓
+
+| 功能 | 新框架实现 | 对应现有功能 |
+|------|------------|--------------|
+| **因子抽象** | `FactorBase` + `FactorRegistry` | `compute_factors()` ✓ |
+| **动量因子** | `MomentumFactor` | `calculate_weighted_momentum_score()` ✓ |
+| **崩盘过滤** | `MomentumFactor.crash_filter` | `apply_crash_filter()` ✓ |
+| **ATR计算** | `VolatilityFactor(method='atr')` | `calculate_atr()` ✓ |
+| **Top N选股** | `TopNSelector` | `top_n_codes()` ✓ |
+| **分散化选股** | `TopNSelector(group_by)` | `top_n_diversified()` ✓ |
+| **溢价控制** | `PremiumControl` | `premium_control`配置 ✓ |
+| **回调钩子** | `CallbackHook` | 新增功能 ✓ |
+
+### 2.2 未实现功能 ❌
+
+| 功能 | 现有实现 | 新框架缺失 | 影响 |
+|------|----------|------------|------|
+| **数据源抽象** | `HybridDataSource` | ❌ 无DataSource接口 | 🔴 高：无法获取数据 |
+| **SSH隧道管理** | `hybrid_source.py` | ❌ 无 | 🔴 高：无法访问境外数据 |
+| **双轨数据架构** | index_data + etf_data | ❌ 无 | 🔴 高：因子/收益数据分离 |
+| **交易日历对齐** | `compute_factors()` | ❌ 无 | 🟡 中：跨市场对齐 |
+| **完整回测逻辑** | `run_backtest()` | ❌ BacktestExecutor简化 | 🔴 高：无法执行完整回测 |
+| **交易成本扣除** | 换手率比例扣除 | ❌ 无 | 🟡 中：回测准确性 |
+| **净值计算** | 起点归一化 | ❌ 无 | 🔴 高：净值曲线 |
+| **基准对比** | benchmark_data | ❌ 无 | 🟡 中：策略评估 |
+| **持仓跟踪** | `portfolio.py` | ❌ 无完整实现 | 🟡 中：交易记录 |
+| **报告生成** | `report.py` | ❌ 无 | 🟡 中：结果可视化 |
+
+---
+
+## 三、功能完善性评估
+
+### 3.1 完善度评分
+
+| 模块 | 完善度 | 说明 |
+|------|--------|------|
+| **因子层** | **90%** ✓ | 核心功能完善，动态周期待实现 |
+| **信号层** | **85%** ✓ | TopN和分散化已实现，调仓阈值缺失 |
+| **风控层** | **80%** ✓ | 溢价控制和回调钩子完善 |
+| **数据层** | **0%** ❌ | 完全缺失，需完整迁移 |
+| **执行层** | **20%** ❌ | 仅框架骨架，无完整逻辑 |
+| **报告层** | **0%** ❌ | 完全缺失 |
+
+**总体完善度**：**约45%**
+
+### 3.2 关键缺失分析
+
+**数据层缺失（影响最大）**：
+```
+现有策略流程：
+HybridDataSource.fetch_all() → index_data, etf_data, etf_nav_data
+
+新框架现状：
+无数据获取接口 → 无法运行策略
+```
+
+**执行层缺失（影响大）**：
+```
+现有策略流程：
+generate_signals() → run_backtest() → 净值曲线 + 交易记录
+
+新框架现状：
+BacktestExecutor.execute() → 仅返回空Portfolio → 无法产出结果
+```
+
+---
+
+## 四、迁移路径建议
+
+### 4.1 立即需要补充（P0）
+
+| 功能 | 预估工作量 | 说明 |
+|------|------------|------|
+| **DataSource抽象接口** | 1天 | 定义数据获取标准接口 |
+| **混合数据源集成** | 2天 | 迁移HybridDataSource到新框架 |
+| **完整回测执行器** | 2天 | 迁移run_backtest()逻辑 |
+
+### 4.2 短期补充（P1）
+
+| 功能 | 预估工作量 | 说明 |
+|------|------------|------|
+| **交易日历对齐** | 0.5天 | 迁移compute_factors对齐逻辑 |
+| **持仓跟踪完善** | 1天 | 迁移portfolio.py逻辑 |
+| **基准对比** | 0.5天 | 添加基准数据支持 |
+
+### 4.3 中期补充（P2）
+
+| 功能 | 预估工作量 | 说明 |
+|------|------------|------|
+| **报告生成集成** | 1天 | 迁移report.py到新框架 |
+| **调仓阈值检查** | 0.5天 | 添加_check_rebalance逻辑 |
+
+---
+
+## 五、结论与建议
+
+### 5.1 总体结论
+
+**框架核心抽象设计完善（因子层、信号层、风控层）**，但：
+
+- **数据层缺失**：无法获取数据，策略无法运行
+- **执行层不完整**：无法产出回测结果
+- **报告层缺失**：无法可视化结果
+
+**当前状态**：框架骨架搭建完成，但无法直接替代现有轮动策略运行。
+
+### 5.2 两种路径选择
+
+**路径A：快速验证路径**
+- 在现有`engine.py`中使用新框架的因子层和信号层
+- 保持现有数据获取和回测逻辑不变
+- 目标：验证因子抽象和选股逻辑正确性
+- 时间：1天
+
+**路径B：完整迁移路径**
+- 补充数据层抽象
+- 补充完整回测执行器
+- 补充报告生成
+- 目标：完整替代现有策略
+- 时间：5-6天
+
+### 5.3 建议
+
+**优先级建议**：
+1. **先走路径A**：快速验证因子层和信号层正确性
+2. **逐步补充**：按P0→P1→P2顺序补充缺失功能
+3. **保持兼容**：新框架与现有策略并行运行一段时间
+
+**下一步行动**：
+- 是否先走路径A（快速验证）？
+- 还是直接走路径B（完整迁移）？
+
+---
+
+*文档版本：V1.0*
+*分析时间：2026-05-08*
+*目标：评估框架功能完善性*