fix(data): 修复财务因子计算非确定性问题

重构 financial_loader 的去重逻辑，确保截面排名计算的股票集合一致：
- 引入"高水位线"算法剔除陈旧历史财报（解决2026年发布2021年财报的问题）
- 改变去重策略：按报告期(end_date)而非更新标识(update_flag)保留最新数据
- 扩展回看期从1年到2年，防止ST/停牌公司财报缺失
- 确保相同交易日在不同查询范围下返回一致的财务数据

src/data/financial_loader.py

@@ -49,7 +49,13 @@ class FinancialLoader:
             清洗后的 Polars DataFrame，已排序，f_ann_date 为 pl.Date 类型
         """
         # 确保包含必要字段
-        required_cols = {"ts_code", "f_ann_date", "report_type", "update_flag"}
+        required_cols = {
+            "ts_code",
+            "f_ann_date",
+            "report_type",
+            "update_flag",
+            "end_date",
+        }
         query_cols = list(set(columns) | required_cols)
 
         # 从数据库加载原始数据
@@ -61,32 +67,51 @@ class FinancialLoader:
         # 步骤1: 仅保留合并报表 (report_type 可能是字符串或整数)
         df = df.filter(pl.col("report_type") == 1)
 
-        # 步骤2: 按 update_flag 降序排列后去重
+        # 步骤2: 添加辅助列用于排序和过滤
         df = df.with_columns(
-            [pl.col("update_flag").cast(pl.Int32).alias("update_flag_int")]
+            [
+                # 将报告期 20231231 转为整数
+                pl.col("end_date").cast(pl.Int32).alias("end_date_int"),
+                # 将更新标识转为整数，容错处理 null 和空字符串
+                pl.col("update_flag")
+                .fill_null("0")
+                .cast(pl.Int32, strict=False)
+                .fill_null(0)
+                .alias("update_flag_int"),
+            ]
         )
 
-        # 排序：ts_code, f_ann_date 升序；update_flag 降序
-        df = df.sort(
-            ["ts_code", "f_ann_date", "update_flag_int"],
-            descending=[False, False, True],
+        # 步骤3: 绝对确定性排序
+        # 按照: 股票代码(升序) -> 公告日(升序) -> 报告期(升序) -> 更新标识(升序)
+        # 这样排序后，同一天发布的多份报表中，end_date最大、update_flag最新的，
+        # 必然排在这一天的最后面
+        df = df.sort(["ts_code", "f_ann_date", "end_date_int", "update_flag_int"])
+
+        # 步骤4: 核心算法 - 计算截至每一个公告日，市场"见过的"最新报告期（最高水位线）
+        df = df.with_columns(
+            pl.col("end_date_int").cum_max().over("ts_code").alias("max_end_date_seen")
         )
 
-        # 去重：保留每个 (ts_code, f_ann_date) 的第一条（update_flag 最高的）
-        df = df.unique(subset=["ts_code", "f_ann_date"], keep="first")
+        # 步骤5: 剔除"历史包袱"（解决2026年发2021年财报的问题）
+        # 如果今天发布的财报，它的 end_date 小于我们之前已经见过的最大值，
+        # 说明它是陈旧的追溯调整，直接抛弃！
+        df = df.filter(pl.col("end_date_int") == pl.col("max_end_date_seen"))
 
-        # 移除临时列
-        df = df.drop("update_flag_int")
+        # 步骤6: 唯一化处理：满足 join_asof 的前置要求
+        # 经过上述处理后，同一个 f_ann_date 的最后一行，必定是 end_date 最大的那一份
+        # 我们只保留这最后一行，确保每个 f_ann_date 只有唯一的一条记录暴露给行情去 join
+        df = df.unique(subset=["ts_code", "f_ann_date"], keep="last")
 
-        # 步骤3: 确保 f_ann_date 是 Date 类型并排序
-        # 数据库返回的必须是 Date 类型，如果不是则报错
+        # 步骤7: 清理临时辅助列
+        df = df.drop(["end_date_int", "update_flag_int", "max_end_date_seen"])
+
+        # 步骤8: 确保 f_ann_date 是 Date 类型并排序（join_asof 要求）
         if df["f_ann_date"].dtype != pl.Date:
             raise TypeError(
                 f"f_ann_date 必须是 Date 类型，实际类型为 {df['f_ann_date'].dtype}. "
                 f"请检查数据库表结构，确保日期字段为 DATE 类型。"
             )
 
-        # 最终排序（join_asof 要求）
         df = df.sort(["ts_code", "f_ann_date"])
 
         return df
@@ -168,14 +193,14 @@ class FinancialLoader:
         self,
         start_date: str,
         end_date: str,
-        lookback_years: int = 1,
+        lookback_years: int = 2,
     ) -> tuple[str, str]:
         """计算包含回看期的日期范围。
 
         Args:
             start_date: 原始开始日期（YYYYMMDD）
             end_date: 原始结束日期（YYYYMMDD）
-            lookback_years: 回看年数（默认1年）
+            lookback_years: 回看年数（默认2年，防止ST/停牌公司财报缺失）
 
         Returns:
             (扩展后的开始日期, 结束日期)

tests/test_financial_price_merge.py

@@ -16,7 +16,7 @@ def create_mock_price_data() -> pl.DataFrame:
     """创建模拟行情数据。"""
     return pl.DataFrame(
         {
-            "ts_code": ["000001.SZ"] * 10,
+            "ts_code": ["000001.SZ"] * 12,
             "trade_date": [
                 "20240101",
                 "20240102",
@@ -28,8 +28,24 @@ def create_mock_price_data() -> pl.DataFrame:
                 "20240110",
                 "20240111",
                 "20240112",
+                # 添加2024-04-30之后的日期，用于测试同日不同报告期场景
+                "20240501",
+                "20240502",
+            ],
+            "close": [
+                10.0,
+                10.2,
+                10.3,
+                10.1,
+                10.5,
+                10.6,
+                10.4,
+                10.7,
+                10.8,
+                10.9,
+                11.0,
+                11.1,
             ],
-            "close": [10.0, 10.2, 10.3, 10.1, 10.5, 10.6, 10.4, 10.7, 10.8, 10.9],
         }
     )
 
@@ -37,31 +53,63 @@ def create_mock_price_data() -> pl.DataFrame:
 def create_mock_financial_data() -> pl.DataFrame:
     """创建模拟财务数据（覆盖多种场景）。
 
+    场景说明：
+    1. 2024-01-02 发布 2023Q3 报告（end_date=20230930）
+    2. 2024-01-02 发布 2023Q3 更正版（update_flag=1）
+    3. 2024-04-30 同时发布 2023年报（end_date=20231231）和 2024Q1季报（end_date=20240331）
+    4. 2024-04-30 发布 2023年报更正版
+
+    预期结果：
+    - 2024-01-02 保留 2023Q3 更正版
+    - 2024-04-30 保留 2024Q1 季报（end_date 最新）
+
     注意：f_ann_date 必须是 Date 类型（与数据库保持一致）。
     """
     return pl.DataFrame(
         {
-            "ts_code": ["000001.SZ", "000001.SZ", "000001.SZ", "000001.SZ"],
-            # 场景1: 2023Q3 报告，正常公告
-            # 场景2: 同日多版（update_flag 区分）
-            # 场景3: 隔日修改
+            "ts_code": [
+                "000001.SZ",
+                "000001.SZ",
+                "000001.SZ",
+                "000001.SZ",
+                "000001.SZ",
+            ],
             "f_ann_date": [
                 date(2024, 1, 2),
-                date(2024, 1, 2),
-                date(2024, 1, 5),
-                date(2024, 1, 10),
+                date(2024, 1, 2),  # 同日多版
+                date(2024, 4, 30),
+                date(2024, 4, 30),
+                date(2024, 4, 30),  # 同日不同报告期
+            ],
+            "end_date": [
+                "20230930",
+                "20230930",  # 2023Q3
+                "20231231",
+                "20240331",
+                "20231231",  # 年报和季报同一天发布
+            ],
+            "report_type": [1, 1, 1, 1, 1],  # 整数类型（与数据库一致）
+            "update_flag": [0, 1, 0, 0, 1],  # 年报也有更正版
+            "net_profit": [
+                1000000.0,
+                1100000.0,  # 2023Q3
+                5000000.0,
+                1500000.0,
+                5500000.0,  # 年报更正后550万，季报150万
+            ],
+            "revenue": [
+                5000000.0,
+                5200000.0,  # 2023Q3
+                20000000.0,
+                8000000.0,
+                22000000.0,
             ],
-            "end_date": ["20230930", "20230930", "20230930", "20231231"],
-            "report_type": [1, 1, 1, 1],  # 整数类型（与数据库一致）
-            "update_flag": [0, 1, 1, 1],  # 整数类型（与数据库一致）
-            "net_profit": [1000000.0, 1100000.0, 1100000.0, 1200000.0],
-            "revenue": [5000000.0, 5200000.0, 5200000.0, 6000000.0],
         }
     )
 
 
 def test_financial_data_cleaning():
-    """测试财务数据清洗逻辑。"""
+    """测试财务数据清洗逻辑 - 确保同日多报告期时选 end_date 最新的。"""
     print("=== 测试 1: 财务数据清洗 ===")
 
     df_finance = create_mock_financial_data()
@@ -70,36 +118,61 @@ def test_financial_data_cleaning():
 
     loader = FinancialLoader()
 
-    # 手动执行清洗（模拟 load_financial_data 的逻辑）
-    # 步骤1: 仅保留合并报表
+    # 手动执行新的清洗逻辑
     df = df_finance.filter(pl.col("report_type") == 1)
 
-    # 步骤2: 按 update_flag 降序排列后去重
+    # 添加辅助列
     df = df.with_columns(
-        [pl.col("update_flag").cast(pl.Int32).alias("update_flag_int")]
+        [
+            pl.col("end_date").cast(pl.Int32).alias("end_date_int"),
+            pl.col("update_flag")
+            .fill_null("0")
+            .cast(pl.Int32, strict=False)
+            .fill_null(0)
+            .alias("update_flag_int"),
+        ]
     )
 
-    df = df.sort(
-        ["ts_code", "f_ann_date", "update_flag_int"], descending=[False, False, True]
+    # 确定性排序
+    df = df.sort(["ts_code", "f_ann_date", "end_date_int", "update_flag_int"])
+
+    # 累积最大报告期
+    df = df.with_columns(
+        pl.col("end_date_int").cum_max().over("ts_code").alias("max_end_date_seen")
     )
 
-    df = df.unique(subset=["ts_code", "f_ann_date"], keep="first")
-    df = df.drop("update_flag_int")
+    # 过滤历史包袱
+    df = df.filter(pl.col("end_date_int") == pl.col("max_end_date_seen"))
 
-    # 步骤3: 排序（f_ann_date 已经是 Date 类型）
+    # 去重保留最后一条（end_date 最大的）
+    df = df.unique(subset=["ts_code", "f_ann_date"], keep="last")
+
+    # 清理辅助列
+    df = df.drop(["end_date_int", "update_flag_int", "max_end_date_seen"])
     df = df.sort(["ts_code", "f_ann_date"])
 
     print("\n清洗后的财务数据：")
     print(df)
 
-    # 验证：应该有3条记录（第1-2行去重为1条，第3行，第4行）
-    assert len(df) == 3, f"清洗后应该有3条记录，实际有 {len(df)} 条"
+    # 验证：应该有2条记录（2024-01-02 和 2024-04-30）
+    assert len(df) == 2, f"清洗后应该有2条记录，实际有 {len(df)} 条"
 
-    # 验证：2024-01-02 的 update_flag 应该是 1
+    # 验证：2024-01-02 的 end_date 应该是 20230930
     row_jan02 = df.filter(pl.col("f_ann_date") == date(2024, 1, 2))
-    assert len(row_jan02) == 1, "应该有1条 2024-01-02 的记录"
-    assert row_jan02["update_flag"][0] == 1, "update_flag 应该为 1"
-    assert row_jan02["net_profit"][0] == 1100000.0, "net_profit 应该为 1100000"
+    assert len(row_jan02) == 1
+    assert row_jan02["end_date"][0] == "20230930"
+    assert row_jan02["update_flag"][0] == 1
+    print("[验证 1] 2024-01-02 正确保留了 2023Q3 更正版")
+
+    # 验证：2024-04-30 应该保留 2024Q1（end_date=20240331），而不是年报
+    row_apr30 = df.filter(pl.col("f_ann_date") == date(2024, 4, 30))
+    assert len(row_apr30) == 1
+    assert row_apr30["end_date"][0] == "20240331", (
+        f"2024-04-30 应该保留 end_date 最新的 20240331，"
+        f"实际为 {row_apr30['end_date'][0]}"
+    )
+    assert row_apr30["net_profit"][0] == 1500000.0
+    print("[验证 2] 2024-04-30 正确保留了 2024Q1 季报（end_date 最新）")
 
     print("\n[通过] 财务数据清洗测试通过！")
     return df
@@ -114,17 +187,44 @@ def test_financial_price_merge():
 
     loader = FinancialLoader()
 
-    # 步骤1: 清洗财务数据（手动执行）
+    # 步骤1: 清洗财务数据（手动执行新的清洗逻辑）
     # 注意：f_ann_date 已经是 Date 类型，不需要转换
     df_finance = df_finance_raw.filter(pl.col("report_type") == 1)
+
+    # 添加辅助列
     df_finance = df_finance.with_columns(
-        [pl.col("update_flag").cast(pl.Int32).alias("update_flag_int")]
+        [
+            pl.col("end_date").cast(pl.Int32).alias("end_date_int"),
+            pl.col("update_flag")
+            .fill_null("0")
+            .cast(pl.Int32, strict=False)
+            .fill_null(0)
+            .alias("update_flag_int"),
+        ]
     )
+
+    # 确定性排序
     df_finance = df_finance.sort(
-        ["ts_code", "f_ann_date", "update_flag_int"], descending=[False, False, True]
+        ["ts_code", "f_ann_date", "end_date_int", "update_flag_int"]
+    )
+
+    # 累积最大报告期
+    df_finance = df_finance.with_columns(
+        pl.col("end_date_int").cum_max().over("ts_code").alias("max_end_date_seen")
+    )
+
+    # 过滤历史包袱
+    df_finance = df_finance.filter(
+        pl.col("end_date_int") == pl.col("max_end_date_seen")
+    )
+
+    # 去重保留最后一条（end_date 最大的）
+    df_finance = df_finance.unique(subset=["ts_code", "f_ann_date"], keep="last")
+
+    # 清理辅助列
+    df_finance = df_finance.drop(
+        ["end_date_int", "update_flag_int", "max_end_date_seen"]
     )
-    df_finance = df_finance.unique(subset=["ts_code", "f_ann_date"], keep="first")
-    df_finance = df_finance.drop("update_flag_int")
     df_finance = df_finance.sort(["ts_code", "f_ann_date"])
 
     print("清洗后的财务数据：")
@@ -166,15 +266,22 @@ def test_financial_price_merge():
     assert jan04["net_profit"][0] == 1100000.0, "2024-01-04 应延续使用 2023Q3 数据"
     print("[验证 3] 2024-01-04 net_profit=1100000 - 正确（延续使用）")
 
-    # 20240110 应切换到 2023Q4 数据（新公告）
+    # 20240110 应延续使用 2023Q3 数据（2024-04-30 还未公告）
     jan10 = merged.filter(pl.col("trade_date") == "20240110")
-    assert jan10["net_profit"][0] == 1200000.0, "2024-01-10 应切换到 2023Q4 数据"
-    print("[验证 4] 2024-01-10 net_profit=1200000 - 正确（新财报公告）")
+    assert jan10["net_profit"][0] == 1100000.0, "2024-01-10 应延续使用 2023Q3 数据"
+    print("[验证 4] 2024-01-10 net_profit=1100000 - 正确（延续使用 2023Q3）")
 
-    # 20240112 应继续延续使用 2023Q4 数据
+    # 20240112 应继续延续使用 2023Q3 数据
     jan12 = merged.filter(pl.col("trade_date") == "20240112")
-    assert jan12["net_profit"][0] == 1200000.0, "2024-01-12 应继续使用 2023Q4 数据"
-    print("[验证 5] 2024-01-12 net_profit=1200000 - 正确（延续使用）")
+    assert jan12["net_profit"][0] == 1100000.0, "2024-01-12 应继续使用 2023Q3 数据"
+    print("[验证 5] 2024-01-12 net_profit=1100000 - 正确（延续使用 2023Q3）")
+
+    # 20240501 应切换到 2024Q1 数据（2024-04-30 已公告，且选择 end_date 最新的）
+    may01 = merged.filter(pl.col("trade_date") == "20240501")
+    assert may01["net_profit"][0] == 1500000.0, "2024-05-01 应切换到 2024Q1 数据"
+    print(
+        "[验证 6] 2024-05-01 net_profit=1500000 - 正确（切换到 2024Q1，end_date 最新）"
+    )
 
     print("\n[通过] 所有验证通过，无未来函数！")
     return merged