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

当前开发平台为 Linux aarch64 + CPython 3.12：pyqlib 官方仅提供 x86_64 /
macOS / Windows 且最高 Python 3.8 的 wheel（实测 uv 解析不可满足），因此
Qlib 实现在此平台无法安装运行。

受支持平台（如 x86_64 Linux + Python 3.11）启用方式：
    cd backend && uv pip install pyqlib==0.9.7
    将本模块替换为真实实现：Parquet/本地行情 → QlibDataset → Alpha158 →
    LightGBM 训练/预测 → 回测，并归一化为 domain.entities.research 输出。

业务层经 app.quant.engine.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，当前平台（Linux aarch64 + Python 3.12）无可用 wheel。"
    "请改用 LocalEngine 或在受支持平台安装 pyqlib 后实现（见本模块 docstring）。"
)


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)