"""时间序列（MCM C 必备）。

原建议列了 `moving_average` `weighted_moving_average` `holt_trend`
`seasonal_decompose` `lag_features` `forecast_interval` 等一堆函数，
但 statsmodels 已经全部提供，按它自己的原则（"做薄封装，不要重写框架"）
只保留三个真正有封装价值的入口。
"""

from __future__ import annotations

from typing import Any

__all__ = ["exponential_smoothing", "fit_arima", "forecast"]


def exponential_smoothing(series: Any, alpha: float | None = None, trend: str | None = None, seasonal: str | None = None, periods: int | None = None) -> Any:
    """指数平滑（底层 `statsmodels.tsa.holtwinters`）。

    `alpha=None` 时自动用极大似然估计平滑系数——比自己拍脑袋定 `alpha` 靠谱。

    Examples
    --------
    >>> r = exponential_smoothing(y, trend="add")   # doctest: +SKIP
    """
    # TODO(L1)
    raise NotImplementedError


def fit_arima(series: Any, order: tuple[int, int, int] = (1, 1, 1), seasonal_order: tuple[int, int, int, int] | None = None, auto: bool = False) -> Any:
    """ARIMA 拟合。

    Parameters
    ----------
    auto:
        `True` 时按 AIC 网格搜索 (p, d, q)，省去手动定阶；
        数据量大时较慢，比赛里建议先手动看一眼 ACF/PACF。
    order:
        `(p, d, q)`——自回归阶数、差分阶数、移动平均阶数。

    Returns
    -------
    `Result`：`metrics={"aic", "bic"}`，`extras["model"]` 是 statsmodels 结果对象
    （需要 `summary()`、残差诊断时直接拿）。

    Notes
    -----
    ARIMA 要求序列**平稳**。`d` 是差分阶数，但差分会丢信息，
    非平稳序列更推荐先看是不是有结构突变或季节成分。
    """
    # TODO(L1)
    raise NotImplementedError


def forecast(model: Any, steps: int, alpha: float = 0.05) -> Any:
    """向后预测 `steps` 步，并给出预测区间。

    Returns
    -------
    `Result`：`data` 是含 `forecast / lower / upper` 三列的 DataFrame。

    Notes
    -----
    **预测区间随步长急剧变宽是正常的**，不要只画中心线——
    论文里只画一条线而不给区间，是很常见的扣分点。
    """
    # TODO(L1)
    raise NotImplementedError