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

切换引擎（如未来在支持平台启用 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.local_engine import (
    TopKBacktestRunner,
    build_factor_panels,
    composite_score,
    run_spec_factor_test,
)


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

    name: str

    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 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()