"""研究引擎抽象与默认实现（业务层依赖本接口，可替换引擎）。

切换引擎（如未来在支持平台启用 Qlib）只需注入不同实现 —— 业务代码不变。
"""

from __future__ import annotations

from typing import Protocol

import pandas as pd

from app.domain.entities.research import BacktestResult, FactorTestReport, ResearchSpec
from app.quant.factors import FactorError, get_factor
from app.quant.local_engine import (
    TopKBacktestRunner,
    build_factor_panels,
    composite_score,
    run_spec_factor_test,
)

# LocalEngine 路径恒需 close（TopK 收盘撮合 / 前瞻收益）
_CLOSE = {"close"}


def factor_required_columns(spec: ResearchSpec) -> set[str]:
    """spec 因子计算 + 回测撮合所需的行情数值列（含 close）。"""
    needed = set(_CLOSE)
    for fs in spec.factors:
        try:
            defn, _fn = get_factor(fs.name)
        except FactorError:
            continue  # 未知因子由执行期统一报错
        needed.update(defn.requires)
    return needed


class QuantEngine(Protocol):
    """研究引擎端口：因子面板构建 / 因子测试 / 回测。"""

    name: str

    def required_columns(self, spec: ResearchSpec) -> set[str]:
        """执行该 spec 所需的行情数值列（数据装配按此裁剪，控制内存）。"""

    def run_factor_test(
        self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
    ) -> FactorTestReport: ...

    def run_backtest(self, daily: pd.DataFrame, spec: ResearchSpec) -> BacktestResult: ...


class LocalEngine:
    """默认引擎：纯 pandas 实现（无 Qlib 依赖），见 local_engine.py 的纪律说明。"""

    name = "local"

    def required_columns(self, spec: ResearchSpec) -> set[str]:
        return factor_required_columns(spec)

    def run_factor_test(
        self, daily: pd.DataFrame, spec: ResearchSpec, horizon_days: int = 21
    ) -> FactorTestReport:
        report, _panels = run_spec_factor_test(daily, spec, horizon_days)
        return report

    def run_backtest(self, daily: pd.DataFrame, spec: ResearchSpec) -> BacktestResult:
        panels = build_factor_panels(daily, spec.factors)
        score = composite_score(panels)
        close = daily.pivot(index="trade_date", columns="symbol", values="close").sort_index()
        return TopKBacktestRunner(spec, score, close).run()