refactor(archive): move unused modules to archive/

Archive legacy framework and utility modules that are no longer referenced by the active core (datasource/ and rotation/): - framework/ -> archive/framework/ - framework_v2/ -> archive/framework_v2/ - strategies/ -> archive/strategies/ - config/ -> archive/config/ - visualization/ -> archive/visualization/ - scripts/ -> archive/scripts/ - tests/ -> archive/tests/ - run_rotation.py, run_us_rotation.py -> archive/single_files/ - compare_*.py, test_api_dates.py -> archive/single_files/
2026-06-03 23:41:46 +08:00
parent d700bc1dfd
commit c905230a40
98 changed files with 0 additions and 714 deletions
--- a/archive/framework_v2/DATA_FLOW_DEMO.md
+++ b/archive/framework_v2/DATA_FLOW_DEMO.md
@@ -0,0 +1,780 @@
+# 跨市场数据流完整推演
+
+## 📋 场景设定
+
+### 标的池
+
+| 标的 | 市场 | 年交易日 | 特点 |
+|------|------|----------|------|
+| ^GSPC（标普500） | 美股 | 252 天 | 美国假日（马丁路德金日、感恩节） |
+| ^HSI（恒生指数） | 港股 | 250 天 | 香港假日（佛诞日、圣诞节） |
+| 000300.SH（沪深300） | A 股 | 244 天 | 中国假日（春节、国庆） |
+
+**目标日历**：A 股交易日（244 天）
+
+### 假日差异示例（2024 年 1 月）
+
+| 日期 | 美股 | 港股 | A 股 | 说明 |
+|------|------|------|------|------|
+| 2024-01-01 | 休市 | 休市 | 休市 | 元旦（共同假日） |
+| 2024-01-02 | 交易 | 交易 | 交易 | - |
+| 2024-01-15 | 休市 | 交易 | 交易 | 马丁路德金日（仅美股休市） |
+| 2024-02-10 | 交易 | 交易 | 休市 | 春节（仅 A 股休市） |
+
+---
+
+## 🎬 完整数据流推演（7 个阶段）
+
+### 阶段 0：原始数据（不同日历）
+
+```python
+# 从数据源获取原始 OHLCV 数据
+index_data = {
+    '^GSPC': DataFrame(252 rows, US calendar),      # 美股
+    '^HSI': DataFrame(250 rows, HK calendar),       # 港股
+    '000300.SH': DataFrame(244 rows, CN calendar)   # A 股
+}
+
+# 示例：2024 年 1 月第一周
+^GSPC (美股):
+日期         close
+2024-01-01   4770.0    ← 元旦（美股休市，无数据或从 yfinance 获取）
+2024-01-02   4780.0
+2024-01-03   4790.0
+2024-01-04   4785.0
+2024-01-05   4800.0
+...
+
+^HSI (港股):
+日期         close
+2024-01-01   17050.0   ← 元旦（港股休市）
+2024-01-02   17100.0
+2024-01-03   17150.0
+2024-01-04   17120.0
+2024-01-05   17200.0
+...
+
+000300.SH (A 股):
+日期         close
+2024-01-01   3500.0    ← 元旦（A 股休市）
+2024-01-02   3510.0
+2024-01-03   3520.0
+2024-01-04   3515.0
+2024-01-05   3530.0
+...
+```
+
+**关键问题**：
+- ❌ 三个市场的交易日历不同
+- ❌ 直接合并会导致大量 NaN
+- ❌ 无法直接计算因子和收益
+
+---
+
+### 阶段 1：因子计算（在原始日历）
+
+```python
+from framework_v2.shared.factors import MomentumFactor
+
+factor = MomentumFactor(n_days=25, weighted=True, crash_filter=True)
+
+# ✅ 关键：在原始交易日历计算因子（不 ffill）
+factor_raw = {}
+for code, df in index_data.items():
+    factor_raw[code] = factor.compute(df)
+
+# 结果：每个标的在各自的交易日历上有因子值
+^GSPC 因子（美股日历 252 天）:
+日期         factor
+2024-01-01   NaN         ← 前 25 天数据不足
+...
+2024-01-26   0.15        ← 第 26 天开始有因子值
+2024-01-29   0.16
+2024-01-30   0.17
+...
+
+^HSI 因子（港股日历 250 天）:
+日期         factor
+2024-01-02   NaN
+...
+2024-01-26   0.14
+2024-01-29   0.15
+2024-01-30   0.16
+...
+
+000300.SH 因子（A 股日历 244 天）:
+日期         factor
+2024-01-02   NaN
+...
+2024-01-29   0.13
+2024-01-30   0.14
+...
+```
+
+**为什么在原始日历计算？**
+
+1. ✅ rolling window 使用**真实交易日**（25 天）
+2. ✅ 线性回归权重基于真实数据分布
+3. ❌ 如果先 ffill，窗口会包含重复值，影响因子精度
+
+---
+
+### 阶段 2：对齐因子到 A 股日历
+
+```python
+from framework_v2.shared.data.alignment import CrossMarketAligner
+
+# 创建对齐器（目标日历 = A 股）
+aligner = CrossMarketAligner(target_calendar=a_share_dates)  # 244 天
+
+# 对齐每个标的的因子值
+factor_aligned = {}
+for code, factor_series in factor_raw.items():
+    aligned = aligner.align_factor(
+        factor_series,
+        source_calendar=index_data[code].index,  # 原始日历
+        code=code
+    )
+    factor_aligned[code] = aligned['value']  # 提取因子值列
+
+# 结果：所有因子值对齐到 A 股日历（244 天）
+^GSPC 因子（A 股日历 244 天）:
+日期         factor   is_filled
+2024-01-01   NaN      False     ← A 股休市（元旦）
+2024-01-02   NaN      False     ← 数据不足（前 25 天）
+...
+2024-01-26   0.15     False     ← 真实值
+2024-01-29   0.16     False     ← 真实值
+2024-01-30   0.16      True     ← ffill（美股休市，填充前一天的因子值）
+2024-01-31   0.17     False     ← 真实值
+...
+
+^HSI 因子（A 股日历 244 天）:
+日期         factor   is_filled
+2024-01-01   NaN      False     ← A 股休市
+2024-01-02   0.14     False     ← 真实值
+...
+2024-01-29   0.15     False     ← 真实值
+2024-01-30   0.15      True     ← ffill（港股休市）
+...
+
+000300.SH 因子（A 股日历 244 天）:
+日期         factor   is_filled
+2024-01-01   NaN      False     ← A 股休市
+2024-01-02   0.13     False     ← 真实值
+...
+2024-01-29   0.14     False     ← 真实值
+2024-01-30   0.14     False     ← 真实值（A 股正常交易）
+...
+```
+
+**CrossMarketAligner 的作用**：
+
+```python
+def align_factor(self, factor_series, source_calendar, code):
+    # 1. reindex + ffill
+    aligned = factor_series.reindex(self.target_calendar, method='ffill')
+    
+    # 2. 标记填充值（不在 source_calendar 中的日期）
+    is_filled = ~aligned.index.isin(source_calendar)
+    
+    # 3. 验证
+    self._validate_factor_alignment(aligned, is_filled, code)
+    
+    return pd.DataFrame({
+        'value': aligned,
+        'is_filled': is_filled
+    })
+```
+
+**验证逻辑**：
+
+```python
+def _validate_factor_alignment(self, aligned, is_filled, code):
+    # 1. 检查 NaN 比例
+    nan_ratio = aligned.isna().sum() / len(aligned)
+    if nan_ratio > 0.1:  # > 10%
+        warnings.warn(f"{code}: 因子 NaN 比例过高 ({nan_ratio:.1%})")
+    
+    # 2. 检查填充比例
+    fill_ratio = is_filled.sum() / len(is_filled)
+    if fill_ratio > 0.3:  # > 30%
+        warnings.warn(f"{code}: 因子填充比例过高 ({fill_ratio:.1%})")
+```
+
+---
+
+### 阶段 3：生成信号
+
+```python
+from framework_v2.shared.signals import TopNSelector
+
+selector = TopNSelector(select_num=3, min_score=0.0)
+
+# 合并所有因子为 DataFrame
+factor_df = pd.DataFrame(factor_aligned)
+# 索引：A 股日历（244 天）
+# 列：['^GSPC', '^HSI', '000300.SH']
+
+# 生成信号
+signals = selector.generate(factor_df)
+
+# 结果：
+signals DataFrame（A 股日历 244 天）:
+日期         signal
+2024-01-01   ''               ← 因子全 NaN，空信号
+2024-01-02   ''               ← 因子全 NaN
+...
+2024-01-29   '^GSPC,^HSI,000300.SH'  ← Top 3
+2024-01-30   '^GSPC,^HSI,000300.SH'  ← 调仓控制（保持上次信号）
+2024-01-31   '^GSPC,000300.SH'       ← ^HSI 动量下降，被替换
+...
+```
+
+---
+
+### 阶段 4：对齐收益率到 A 股日历（⭐ 关键步骤）
+
+```python
+# 对每个标的计算收益率
+returns_aligned = {}
+for code, df in index_data.items():
+    close_series = df['close']
+    
+    # ✅ 使用 aligner 对齐收益率
+    returns = aligner.align_returns(
+        close_series,
+        code=code
+    )
+    returns_aligned[code] = returns
+
+# 结果：
+^GSPC 收益率（A 股日历 244 天）:
+日期         close(ffill)  returns
+2024-01-01   4770.0        0.0000    ← 首日
+2024-01-02   4780.0        0.0021    ← +0.21%
+2024-01-03   4790.0        0.0021    ← +0.21%
+2024-01-04   4785.0       -0.0010    ← -0.10%
+...
+2024-01-30   4810.0  ← ffill（美股休市）  0.0000    ← 0%（价格不变）✓
+2024-01-31   4820.0        0.0021    ← +0.21%
+
+^HSI 收益率（A 股日历 244 天）:
+日期         close(ffill)  returns
+2024-01-01   17050.0       0.0000    ← 首日（ffill）
+2024-01-02   17100.0       0.0029    ← +0.29%
+...
+2024-01-30   17200.0  ← ffill（港股休市）  0.0000    ← 0% ✓
+
+000300.SH 收益率（A 股日历 244 天）:
+日期         close         returns
+2024-01-01   3500.0        0.0000    ← 首日
+2024-01-02   3510.0        0.0029    ← +0.29%
+...
+2024-01-30   3540.0        0.0028    ← +0.28%（A 股正常交易）
+```
+
+**CrossMarketAligner 的核心逻辑**：
+
+```python
+def align_returns(self, close_series, code):
+    # ✅ 步骤 1：价格先对齐到 A 股日历
+    close_aligned = close_series.reindex(
+        self.target_calendar,
+        method='ffill'
+    )
+    # 休市日价格不变（ffill 填充前一天的价格）
+    # 例：2024-01-30 美股休市，close_aligned['2024-01-30'] = 4800（前一日价格）
+    
+    # ✅ 步骤 2：计算收益率
+    returns = close_aligned.pct_change(fill_method=None)
+    # 休市日：(今日价格 - 昨日价格) / 昨日价格
+    #       = (4800 - 4800) / 4800 = 0%
+    # 因为 ffill 后，今日价格 = 昨日价格
+    
+    # ✅ 步骤 3：填充首日 NaN
+    returns.iloc[0] = 0.0  # 首日无前一日，收益率 = 0
+    
+    # ✅ 步骤 4：填充剩余 NaN（如果有）
+    returns = returns.fillna(0.0)  # 用 0 填充（表示"无数据，收益率为 0"）
+    
+    # ✅ 步骤 5：验证
+    self._validate_returns(returns, code)
+    
+    return returns
+```
+
+**为什么这样正确？**
+
+| 日期 | 美股状态 | 价格（ffill） | 收益率计算 | 结果 |
+|------|----------|---------------|------------|------|
+| 2024-01-29 | 正常交易 | 4800 | (4800 - 4790) / 4790 | +0.21% |
+| 2024-01-30 | **休市** | 4800 (ffill) | (4800 - 4800) / 4800 | **0%** ✓ |
+| 2024-01-31 | 正常交易 | 4820 | (4820 - 4800) / 4800 | +0.42% |
+
+**对比错误做法**：
+
+```python
+# ❌ 错误：先计算收益率，再 ffill
+returns_wrong = close.pct_change()  # 美股日历
+returns_aligned = returns_wrong.reindex(a_share_dates, method='ffill')
+
+日期         收益率（美股）  A股日历    对齐后收益率
+2024-01-29   +0.21%       2024-01-29  +0.21%
+2024-01-30   无（休市）   2024-01-30  +0.21% ← 错误！复制了前一天的收益率
+2024-01-31   +0.42%       2024-01-31  +0.42%
+
+# 问题：A 股交易日"继承"了美股休市前一天的收益率
+# 结果：净值被高估（多算了 0.21%）
+```
+
+**验证逻辑**：
+
+```python
+def _validate_returns(self, returns, code):
+    # 1. 检查 NaN 比例
+    nan_ratio = returns.isna().sum() / len(returns)
+    if nan_ratio > 0.1:  # > 10%
+        raise ValueError(f"{code}: 收益率 NaN 比例过高 ({nan_ratio:.1%})")
+    
+    # 2. 检查异常值
+    max_return = returns.abs().max()
+    if max_return > 0.5:  # 单日涨跌 > 50%
+        warnings.warn(f"{code}: 发现异常收益率 ({max_return:.1%})")
+    
+    # 3. 检查索引是否匹配目标日历
+    if not returns.index.equals(self.target_calendar):
+        raise ValueError(f"{code}: 收益率索引与目标日历不匹配")
+```
+
+---
+
+### 阶段 5：合并多标的收益率
+
+```python
+# 合并为 DataFrame
+returns_df = pd.DataFrame(returns_aligned)
+
+# 结果：
+returns_df（A 股日历 244 天 × 3 列）:
+日期         ^GSPC      ^HSI       000300.SH
+2024-01-01   0.0000     0.0000     0.0000
+2024-01-02   0.0021     0.0029     0.0029
+2024-01-03   0.0021     0.0029     0.0028
+2024-01-04  -0.0010    -0.0018    -0.0014
+...
+2024-01-30   0.0000     0.0000     0.0028    ← 美股/港股休市（0%），A 股正常
+2024-01-31   0.0021     0.0025     0.0030
+
+# ✅ 验证：无 NaN
+assert not returns_df.isna().any().any()
+```
+
+**CrossMarketAligner 的作用**：
+
+```python
+def align_multi_asset(self, close_dict):
+    returns_dict = {}
+    
+    for code, close_series in close_dict.items():
+        try:
+            # 对每个标的调用 align_returns
+            returns_dict[code] = self.align_returns(close_series, code)
+        except Exception as e:
+            # 如果失败，填充全 0
+            warnings.warn(f"{code}: 收益率对齐失败 - {e}")
+            returns_dict[code] = pd.Series(0.0, index=self.target_calendar)
+    
+    returns_df = pd.DataFrame(returns_dict)
+    
+    # 最终验证：不能有 NaN
+    if returns_df.isna().any().any():
+        raise ValueError("收益率 DataFrame 包含 NaN，这不应该发生")
+    
+    return returns_df
+```
+
+---
+
+### 阶段 6：验证信号与收益率对齐
+
+```python
+# 验证
+aligned_signals, aligned_returns = aligner.validate_alignment(
+    signals,
+    returns_df
+)
+
+# 内部逻辑：
+def validate_alignment(self, signals, returns_df):
+    # 1. 找共同日期
+    common_dates = signals.index.intersection(returns_df.index)
+    
+    # 2. 检查丢失的日期
+    lost_signals = len(signals) - len(common_dates)
+    lost_returns = len(returns_df) - len(common_dates)
+    
+    if lost_signals > 0 or lost_returns > 0:
+        warnings.warn(
+            f"信号与收益率对齐丢失日期\n"
+            f"信号: {len(signals)} → {len(common_dates)} (丢失 {lost_signals})\n"
+            f"收益: {len(returns_df)} → {len(common_dates)} (丢失 {lost_returns})"
+        )
+    
+    # 3. 检查对齐后日期是否太少
+    if len(common_dates) < 10:
+        raise ValueError(f"对齐后日期太少: {len(common_dates)} 天")
+    
+    # 4. 裁剪到共同日期
+    aligned_signals = signals.loc[common_dates]
+    aligned_returns = returns_df.loc[common_dates]
+    
+    return aligned_signals, aligned_returns
+```
+
+---
+
+### 阶段 7：计算组合收益
+
+```python
+from framework_v2.execution import BacktestExecutor
+
+executor = BacktestExecutor(
+    initial_capital=100000,
+    trade_cost=0.001,  # 0.1% 交易成本
+    select_num=3
+)
+
+# 执行回测
+portfolio = executor.execute(aligned_signals, aligned_returns)
+
+# 内部逻辑：
+def execute(self, signals, returns_df):
+    nav = [self.initial_capital]  # 初始净值
+    
+    for date, row in signals.iterrows():
+        signal = row['signal']  # '^GSPC,^HSI,000300.SH'
+        
+        if not signal or signal == '':
+            # 空信号，持有现金
+            daily_return = 0.0
+        else:
+            # 解析信号
+            codes = signal.split(',')
+            
+            # 获取当日收益率
+            daily_returns = [
+                returns_df.loc[date, code]
+                for code in codes
+            ]
+            
+            # 等权平均
+            daily_return = np.mean(daily_returns)
+            
+            # 扣除交易成本
+            daily_return -= self.trade_cost
+        
+        # 更新净值
+        new_nav = nav[-1] * (1 + daily_return)
+        nav.append(new_nav)
+    
+    return pd.DataFrame({
+        'nav': nav[1:],
+        'daily_return': ...
+    })
+```
+
+**示例计算**：
+
+```
+日期         signal                    收益率计算                  净值
+2024-01-29   ^GSPC,^HSI,000300.SH      (0.16+0.15+0.14)/3-0.001   100,000 → 100,048
+2024-01-30   ^GSPC,^HSI,000300.SH      (0.00+0.00+0.28)/3-0.001   100,048 → 100,047
+                                          ↑ 美股/港股休市（0%）
+2024-01-31   ^GSPC,000300.SH           (0.21+0.30)/2-0.001        100,047 → 100,072
+                                          ↑ 只持有 2 只标的
+```
+
+---
+
+## 📊 完整数据流图
+
+```
+原始 OHLCV（不同日历）
+    │
+    ├─ ^GSPC (252 天，美股日历)
+    ├─ ^HSI (250 天，港股日历)
+    └─ 000300.SH (244 天，A 股日历)
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 1：因子计算（原始日历）                    │
+    │ factor.compute(df)                           │
+    │ → 在各自日历计算 rolling(25)                  │
+    │ → 使用真实交易日（25 天）                     │
+    └──────────────────────────────────────────────┘
+    │
+    ├─ ^GSPC 因子 (252 天，美股日历)
+    ├─ ^HSI 因子 (250 天，港股日历)
+    └─ 000300.SH 因子 (244 天，A 股日历)
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 2：CrossMarketAligner.align_factor()     │
+    │ → reindex(a_share_dates, method='ffill')      │
+    │ → 标记 is_filled（哪些是填充值）              │
+    │ → 验证 NaN 比例（> 10% 警告）                 │
+    │ → 验证填充比例（> 30% 警告）                  │
+    └──────────────────────────────────────────────┘
+    │
+    ├─ ^GSPC 因子 (244 天，A 股日历)
+    ├─ ^HSI 因子 (244 天，A 股日历)
+    └─ 000300.SH 因子 (244 天，A 股日历)
+    │
+    ┌─ 合并为 factor_df (244 天 × 3 列)
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 3：信号生成                               │
+    │ selector.generate(factor_df)                 │
+    │ → Top 3 选股（跳过 NaN）                      │
+    │ → 调仓控制（每 N 天调仓）                     │
+    └──────────────────────────────────────────────┘
+    │
+    └─ signals DataFrame (244 天)
+       列：signal（逗号分隔的标的代码）
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 4：CrossMarketAligner.align_returns()    │
+    │ → close.reindex(a_share_dates, ffill)         │
+    │ → pct_change(fill_method=None)                │
+    │ → 休市日收益率 = 0%（价格不变）               │
+    │ → 验证 NaN 比例（> 10% 报错）                 │
+    │ → 验证异常值（> 50% 警告）                    │
+    │ → 验证索引一致性                              │
+    └──────────────────────────────────────────────┘
+    │
+    ├─ ^GSPC 收益率 (244 天，A 股日历)
+    ├─ ^HSI 收益率 (244 天，A 股日历)
+    └─ 000300.SH 收益率 (244 天，A 股日历)
+    │
+    ┌─ 合并为 returns_df (244 天 × 3 列)
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 5：CrossMarketAligner.validate_alignment()│
+    │ → intersection(共同日期)                      │
+    │ → 裁剪到共同日期                              │
+    │ → 验证日期一致性（丢失 > 0 警告）             │
+    │ → 验证最小日期数（< 10 报错）                 │
+    └──────────────────────────────────────────────┘
+    │
+    ├─ aligned_signals (N 天，N ≤ 244)
+    └─ aligned_returns (N 天)
+    │
+    ├──────────────────────────────────────────────┐
+    │ 阶段 6：执行回测                               │
+    │ executor.execute(signals, returns)           │
+    │ → 解析信号（逗号分隔 → 列表）                 │
+    │ → 等权组合（np.mean）                         │
+    │ → 扣除交易成本                                │
+    │ → 计算净值曲线                                │
+    └──────────────────────────────────────────────┘
+    │
+    └─ 最终结果
+       ├─ 净值曲线（DataFrame）
+       ├─ 日收益率（Series）
+       └─ 绩效指标（年化收益、夏普、最大回撤）
+```
+
+---
+
+## 🎯 CrossMarketAligner 的核心价值
+
+### 解决的问题
+
+| 问题 | 严重度 | 表现 | Aligner 的解决方案 |
+|------|--------|------|-------------------|
+| **跨市场日历不同** | 🔴 严重 | 因子/收益无法直接合并 | align_factor() reindex + ffill |
+| **ffill 收益率陷阱** | 🔴 严重 | 休市日复制非零收益率 | align_returns() 先对齐价格 |
+| **NaN 传播** | 🔴 严重 | 组合收益变 NaN | fillna(0.0) + 严格验证 |
+| **信号与收益不对齐** | 🟡 中等 | 回测丢失日期 | validate_alignment() 裁剪 |
+| **异常值未检测** | 🟡 中等 | 单日涨跌 > 50% | max_return 验证 |
+| **填充值未知** | 🟢 轻微 | 无法评估数据质量 | is_filled 标记 |
+
+### 关键设计决策
+
+#### 1. 为什么因子在原始日历计算？
+
+```python
+# ✅ 正确：在原始日历计算
+factor = close.rolling(25).apply(weighted_momentum)  # 25 个真实交易日
+aligned = factor.reindex(a_share_dates, method='ffill')
+
+# ❌ 错误：先对齐再计算
+close_aligned = close.reindex(a_share_dates, method='ffill')
+factor = close_aligned.rolling(25).apply(...)  # 包含 2-3 个重复值！
+```
+
+**原因**：
+- rolling window 需要**真实交易日**（25 天）
+- ffill 会引入重复值，影响线性回归权重
+- 对齐的是**因子值**，不是价格
+
+#### 2. 为什么收益率要先对齐价格？
+
+```python
+# ✅ 正确：先对齐价格，再计算收益率
+close_aligned = close.reindex(a_share_dates, method='ffill')
+returns = close_aligned.pct_change()  # 休市日 = 0%
+
+# ❌ 错误：先计算收益率，再对齐
+returns = close.pct_change()
+returns_aligned = returns.reindex(a_share_dates, method='ffill')  # 复制非零收益率！
+```
+
+**原因**：
+- 休市日价格不变 → 收益率 = 0%
+- 如果先计算收益率，ffill 会复制前一天的非零收益率
+- 导致净值高估/低估
+
+#### 3. 为什么标记 is_filled？
+
+```python
+aligned = aligner.align_factor(...)
+# aligned['is_filled'] = True/False
+```
+
+**用途**：
+- 分析哪些因子值是"真实计算"的
+- 哪些是"ffill 填充"的
+- 可以统计填充比例，评估数据质量
+- 后续可用于加权（真实值权重更高）
+
+---
+
+## 📈 验证测试
+
+### 测试覆盖
+
+```
+✓ 测试 1: 因子对齐 - 填充值正确标记
+✓ 测试 2: 收益率对齐 - 休市日收益率 = 0%
+✓ 测试 3: 多标的对齐 - 无 NaN，索引一致
+✓ 测试 4: 信号与收益对齐 - 日期裁剪验证
+✓ 测试 5: ffill 陷阱对比 - 错误 vs 正确做法
+
+总计: 5/5 通过
+```
+
+### 关键验证点
+
+```python
+# 1. 休市日收益率 = 0%
+assert returns['2024-01-30'] == 0.0  # 美股休市
+
+# 2. 无 NaN
+assert not returns_df.isna().any().any()
+
+# 3. 索引一致
+assert aligned_signals.index.equals(aligned_returns.index)
+
+# 4. 填充值标记
+assert aligned.loc['2024-01-30', 'is_filled'] == True  # 美股休市
+
+# 5. NaN 比例 < 10%
+nan_ratio = factor_df.isna().sum() / len(factor_df)
+assert (nan_ratio < 0.1).all()
+```
+
+---
+
+## 🔧 使用示例
+
+### 完整代码
+
+```python
+from framework_v2.shared.data.alignment import CrossMarketAligner
+from framework_v2.shared.factors import MomentumFactor
+from framework_v2.shared.signals import TopNSelector
+from framework_v2.execution import BacktestExecutor
+
+# 1. 获取数据
+index_data = {
+    '^GSPC': df_sp500,      # 美股日历
+    '^HSI': df_hsi,         # 港股日历
+    '000300.SH': df_hs300   # A 股日历
+}
+a_share_dates = pd.date_range('2020-01-01', '2024-01-01', freq='B')  # 示例
+
+# 2. 创建对齐器
+aligner = CrossMarketAligner(target_calendar=a_share_dates)
+
+# 3. 计算因子（原始日历）
+factor = MomentumFactor(n_days=25, weighted=True, crash_filter=True)
+factor_raw = {
+    code: factor.compute(df)
+    for code, df in index_data.items()
+}
+
+# 4. 对齐因子到 A 股日历
+factor_aligned = {
+    code: aligner.align_factor(
+        factor_raw[code],
+        source_calendar=index_data[code].index,
+        code=code
+    )['value']
+    for code in index_data.keys()
+}
+
+# 5. 生成信号
+factor_df = pd.DataFrame(factor_aligned)
+selector = TopNSelector(select_num=3, min_score=0.0)
+signals = selector.generate(factor_df)
+
+# 6. 对齐收益率到 A 股日历
+returns_df = aligner.align_multi_asset({
+    code: df['close']
+    for code, df in index_data.items()
+})
+
+# 7. 验证信号与收益率对齐
+aligned_signals, aligned_returns = aligner.validate_alignment(
+    signals,
+    returns_df
+)
+
+# 8. 执行回测
+executor = BacktestExecutor(
+    initial_capital=100000,
+    trade_cost=0.001,
+    select_num=3
+)
+portfolio = executor.execute(aligned_signals, aligned_returns)
+
+# 9. 查看结果
+print(f"最终净值: {portfolio['nav'].iloc[-1]:,.2f}")
+print(f"年化收益: {portfolio['annual_return']:.2%}")
+print(f"夏普比率: {portfolio['sharpe_ratio']:.2f}")
+print(f"最大回撤: {portfolio['max_drawdown']:.2%}")
+```
+
+---
+
+## 📝 注意事项
+
+1. **填充值标记**：`is_filled` 列标记哪些是 ffill 填充的，可用于后续分析
+2. **NaN 处理**：收益率对齐后自动填充为 0（表示"无数据，收益率为 0"）
+3. **异常检测**：单日收益率 > 50% 会发出警告
+4. **索引验证**：对齐后严格验证索引是否匹配目标日历
+5. **统计信息**：通过 `aligner.get_stats()` 获取对齐统计
+6. **性能优化**：避免在循环中多次 reindex，批量处理更高效
+
+---
+
+## 🔗 相关文档
+
+- **[数据架构方案](DATA_ARCHITECTURE.md)** - 完整的数据架构设计（Schema、验证、性能优化）
+- **[跨市场对齐方案](ALIGNMENT_GUIDE.md)** - CrossMarketAligner 使用指南
+- **[框架 V2 README](README.md)** - 框架总览
+
+---
+
+*创建日期: 2026-05-06*
+*版本: 1.0.0*