ggx/tests/test_dividend_fiscal_year.py

"""TTM 每股分红的**财年语义**测试（修复：中期分红导致的断档虚低）。

背景（真实数据，600690.SH 海尔智家）：

| 分红 | 除权日 | 金额 |
|---|---|---:|
| FY2024 年度 | 2025-07-25 | 0.96504 |
| FY2025 中期 | 2025-11-07 | 0.26920 |
| FY2025 年度 | 2026-08-21 | 0.89151 |

旧实现的「按后继接管」只看**相邻两次除权的间隔**：FY2024 与 FY2025 中期只隔
105 天（< 320），于是把中期分红当成「年内多次分红」，两者互不取代；
而 FY2024 与 FY2025 年度相隔 392 天（> 365），旧的又撑不到新的入场。
结果是 **2026-07-25 ~ 2026-08-21 出现 28 天空窗**：TTM 每股分红从 1.23424
掉到 0.26920（−78%），期间公司没有任何真实现金事件。

后果是真实的错误成交：该 run 在 2026-07-30 用这个虚低的股息率（2.31%，
历史分位 1.57% ≤ P25）产生卖出信号，次日开盘清仓 —— 实际上不该卖。

修法：把「相邻间隔」换成**财年语义** —— 同一 ``end_date``（财年）内的多次
支付互不取代；跨财年时，只有「同财年更早还有支付」或「跨财年间隔 < 320 天」
才按标准 365 天窗口退出（中期分红不该把上一年度提前挤掉），否则交给后继接管。

本文件锁定这些语义，与 ``test_dividend_smoothing.py``（相邻间隔的两种毛刺）
互补。
"""

from __future__ import annotations

import numpy as np
import pandas as pd
import pytest

from hdiv.factor.dividend_yield import (
    dedupe_dividend_events,
    ttm_dps_series,
)

TTM = 365
GRACE = 45


def _events(rows: list[tuple[str, str, str, float]]) -> pd.DataFrame:
    """构造分红事件表：(财年报告期, 除权日, 公告日, 金额)。"""
    return pd.DataFrame({
        "end_date": pd.to_datetime([r[0] for r in rows]),
        "ex_date": pd.to_datetime([r[1] for r in rows]),
        "imp_ann_date": pd.to_datetime([r[2] for r in rows]),
        "cash_div_tax": [r[3] for r in rows],
    })


def _daily(start: str, end: str) -> pd.DatetimeIndex:
    return pd.date_range(start, end, freq="D")


#: 600690.SH 海尔智家的真实节奏（3 个财年，含两次跨财年间隔）
HAIER = _events([
    ("2023-12-31", "2024-08-16", "2024-08-10", 0.80131),
    ("2024-12-31", "2025-07-25", "2025-07-19", 0.96504),   # 与上一笔相隔 343 天
    ("2025-06-30", "2025-11-07", "2025-11-01", 0.26920),   # 中期，相隔 105 天
    ("2025-12-31", "2026-08-21", "2026-08-15", 0.89151),   # 年度，相隔 287 天
])


def test_interim_does_not_create_gap_before_next_annual() -> None:
    """中期分红结束到次年年度除权之间**不得**出现断档虚低。

    这是本 bug 的核心：2026-07-25 之后 FY2024 年度已过 365 天，
    而 FY2025 年度要到 2026-08-21 才除权；旧实现在这段里只剩中期分红 0.2692。
    正确结果应是「FY2024 年度 + FY2025 中期」仍同时在窗口内 = 1.23424。
    """
    d = _daily("2024-01-01", "2027-12-31")
    sm = pd.Series(
        ttm_dps_series(d, HAIER, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True),
        index=d,
    )

    # 出问题的那一天（真实回测里触发误卖的信号日）
    assert sm.loc[pd.Timestamp("2026-07-27")] == pytest.approx(1.23424, abs=1e-5)

    # 2026-07-25（FY2024 到期日）到 2026-08-21（FY2025 年度除权）之间：
    # 不得低于「最近一笔真实分红」（0.96504），实际上应保持 1.23424
    win = sm.loc[pd.Timestamp("2026-07-25"):pd.Timestamp("2026-08-20")]
    assert win.min() > 1.0, f"中期分红后出现断档虚低，实际 min={win.min():.5f}"
    assert win.max() - win.min() < 1e-9, "该区间内不应有任何跳变（无真实现金事件）"


def test_no_collapse_between_interim_and_next_annual() -> None:
    """区间内允许「窗口到期」造成的台阶，但**不允许塌到只剩中期分红**。

    修复前：2026-07-25 ~ 2026-08-21 只有 0.26920（−78% 的假低点）。
    修复后：TTM 全程不低于 1.23（上一年度 + 本年度中期同时在窗口内）。
    """
    d = _daily("2025-06-01", "2026-12-31")
    sm = pd.Series(
        ttm_dps_series(d, HAIER, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True),
        index=d,
    )
    window = sm.loc[pd.Timestamp("2025-11-07"):pd.Timestamp("2026-08-20")]
    assert window.min() >= 1.23, f"出现假低点，实际 min={window.min():.5f}"


def test_annual_successor_still_takes_over_within_grace() -> None:
    """跨财年但间隔落在宽限期内（370 天）时，仍应由后继接管、不留空窗。"""
    ev = _events([
        ("2023-12-31", "2024-06-01", "2024-05-25", 1.0),
        ("2024-12-31", "2025-06-06", "2025-05-30", 1.2),   # 相隔 370 天
        ("2025-12-31", "2026-06-11", "2026-06-04", 1.2),
    ])
    d = _daily("2024-01-01", "2026-06-11")
    sm = pd.Series(
        ttm_dps_series(d, ev, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True),
        index=d,
    )
    win = sm.loc[pd.Timestamp("2024-06-01"):pd.Timestamp("2025-06-06")]
    assert win.min() > 0.9, f"宽限期内的跨财年断档未被填补，实际 min={win.min():.5f}"


def test_interim_alone_does_not_extend_into_a_full_year_of_silence() -> None:
    """只有中期分红、随后真停发：必须如实归零，不能靠财年语义永远挂着。"""
    ev = _events([
        ("2024-12-31", "2025-07-25", "2025-07-19", 0.96504),
        ("2025-06-30", "2025-11-07", "2025-11-01", 0.26920),
        # 之后没有任何分红
    ])
    d = _daily("2025-01-01", "2027-06-30")
    sm = pd.Series(
        ttm_dps_series(d, ev, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True),
        index=d,
    )
    # 中期那笔（本序列最后一笔）的宽限期封顶 = 2025-11-07 + 365 天
    assert sm.loc[pd.Timestamp("2027-01-01")] == pytest.approx(0.0)
    # 但在封顶之前仍如实计入（不是提前归零）
    assert sm.loc[pd.Timestamp("2026-11-01")] == pytest.approx(0.26920, abs=1e-5)


def test_smooth_off_is_unaffected_by_fiscal_year_logic() -> None:
    """``smooth_spikes=False`` 必须精确保留「硬窗口」语义（回归对照）。"""
    d = _daily("2025-01-01", "2026-12-31")
    off = pd.Series(
        ttm_dps_series(d, HAIER, ttm_days=TTM, grace_days=GRACE, smooth_spikes=False),
        index=d,
    )
    # 硬窗口：2026-07-27 时 FY2024 年度（2025-07-25）已过 365 天 → 只剩中期
    assert off.loc[pd.Timestamp("2026-07-27")] == pytest.approx(0.26920, abs=1e-5)
    # 而 2025-12-01 时 FY2024 + 中期都在窗口内
    assert off.loc[pd.Timestamp("2025-12-01")] == pytest.approx(1.23424, abs=1e-5)


def test_fiscal_year_is_inferred_when_end_date_missing() -> None:
    """事件表没有 ``end_date`` 列时必须退化到「按相邻间隔接管」，不得报错。

    退化路径**不做**跨财年补位：退化的财年是「除权日所在年」，会把年报除权年
    与紧随其后的中期除权年混在一起，据此补位反而可能造出错误窗口。宁可保守 ——
    业务路径的分红记录都带 ``end_date``（见 ``repo.dividend_records``）。
    """
    ev = HAIER.drop(columns=["end_date"])
    d = _daily("2026-07-01", "2026-08-31")
    out = ttm_dps_series(d, ev, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True)
    s = pd.Series(out, index=d)
    assert np.isfinite(out).all()
    # 退化路径仍保留旧接管：2026-07-01 是 FY2023 年度 + FY2025 中期 = 1.23424
    assert s.loc[pd.Timestamp("2026-07-01")] == pytest.approx(1.23424, abs=1e-5)
    # 但没有跨财年补位，2026-07-25 起只剩中期分红（记录该已知局限）
    assert s.loc[pd.Timestamp("2026-07-27")] == pytest.approx(0.26920, abs=1e-5)


def test_dedupe_then_fiscal_year_end_to_end() -> None:
    """重复记录 + 真实节奏同时存在：聚合与财年语义必须叠加生效。

    真实库里 600690.SH 的每一笔都有**两条** ``实施`` 记录（ann_date 不同），
    逐行累加会把 2.46848 当成 TTM —— 那是虚高一倍的值，随后的「回落」也
    必然是假象。
    """
    dup = pd.concat([HAIER, HAIER], ignore_index=True)
    deduped = dedupe_dividend_events(dup)
    assert len(deduped) == len(HAIER), "同一除权日的重复记录未被聚合"

    d = _daily("2025-08-01", "2026-08-20")
    sm = pd.Series(
        ttm_dps_series(d, dup, ttm_days=TTM, grace_days=GRACE, smooth_spikes=True),
        index=d,
    )
    # 聚合 + 财年接管后：
    #   - 出问题的那一天稳定在 1.23424（FY2024 年度 + FY2025 中期）
    #   - 关键区间（2026-07-25 ~ 2026-08-20）不再塌到 0.26920
    #   - 全程下限是 0.96504（合理的窗口到期台阶），不是 0.2692 的假低点
    assert sm.loc[pd.Timestamp("2026-07-27")] == pytest.approx(1.23424, abs=1e-5)
    gap = sm.loc[pd.Timestamp("2026-07-25"):pd.Timestamp("2026-08-20")]
    assert gap.min() == pytest.approx(1.23424, abs=1e-5), "该区间不得出现假低点"
    assert sm.min() >= 0.96, f"区间内出现假低点，实际 min={sm.min():.5f}"
    assert sm.max() <= 1.77, f"出现重叠虚高，实际 max={sm.max():.5f}"