"""Qlib 后端引擎（桥接占位）。

本模块是 Qlib 引擎的桥接边界（AGENT.md §14 / §15：Qlib 只允许在
quant/qlib_adapter/ 内被引用）。Qlib（pyqlib）已通过「源码 git 安装」成功
部署到本机（Linux aarch64 + CPython 3.12，backend/.venv，uv 管理；
backend/pyproject.toml 固定 commit，细节见 docs/ROADMAP.md §2 备注）。

基于 Qlib 的因子 / 回测工作流（Parquet/本地行情 → QlibDataset → Alpha158 →
LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出）属
Phase 2 后续实现；当前默认研究引擎仍为 LocalEngine（纯 pandas，见
app/quant/engine.py），业务层经 QuantEngine Protocol 注入，切换无需改业务代码。
"""

from __future__ import annotations

import pandas as pd

from app.domain.entities.research import BacktestResult, FactorTestReport, ResearchSpec
from app.quant.engine import QuantEngine

_MSG = (
    "Qlib 引擎工作流尚未实现：pyqlib 现已可在本机安装使用（见 docs/ROADMAP.md §2），"
    "但 QlibDataset → LightGBM 的实现待 Phase 2 补齐。当前请使用默认 LocalEngine。"
)


class QlibEngine(QuantEngine):
    """pyqlib 后端占位：抛 NotImplementedError 并给出启用指引。"""

    name = "qlib"

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

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