"""Controller 基类。

参考 hummingbot strategy_v2/controllers：Controller 只读 K 线、产出 executor
配置（信号层），不碰订单细节。引擎每根 K 线调用：

1. prepare_dataframe() —— 计算指标（含 BTC 1d 闸门等跨周期数据）
2. on_candle() —— 依据最新信号与活动 executor 状态，返回待启动的 executor 列表
"""
from __future__ import annotations

import logging
from typing import Optional

import pandas as pd

from ..executors.base import ExecutorBase

logger = logging.getLogger(__name__)


class ControllerBase:
    #: 策略所需的历史 K 线预热根数
    warmup_candles: int = 210

    def __init__(self, pairs: list[str], btc_pair: str = "BTC/USDT:USDT"):
        self.pairs = pairs
        self.btc_pair = btc_pair
        self.dataframes: dict[str, pd.DataFrame] = {}

    def prepare_dataframe(self, pair: str, df: pd.DataFrame,
                          btc_1d: Optional[pd.DataFrame] = None) -> pd.DataFrame:
        """计算指标。btc_1d 为 BTC 日线（含 ts/open/high/low/close），可为 None。"""
        raise NotImplementedError

    def on_candle(self, pair: str, ts: float,
                  active: list[ExecutorBase]) -> list[ExecutorBase]:
        """返回本根 K 线要新启动的 executor（可为空）。"""
        raise NotImplementedError

    def last_row(self, pair: str) -> Optional[pd.Series]:
        df = self.dataframes.get(pair)
        if df is None or df.empty:
            return None
        return df.iloc[-1]