"""
Pydantic 模型用於策略配置 (V2 - 自動轉換版本)

自動處理 Polars Expr 的雙向轉換：
- 讀取時：自動將 JSON/dict 轉為 pl.Expr
- 寫入時：可直接使用 pl.col() 等，自動序列化
"""

import json
from enum import Enum
from io import StringIO
from typing import Any, Dict, List, Literal, Optional, Union

import polars as pl
from pydantic import BaseModel, Field, field_serializer, field_validator


class Freq(str, Enum):
    """時間頻率枚舉（與 Rust Freq enum 一致）

    對應 Rust 的 Freq enum
    """

    MIN_1 = "1min"
    MIN_5 = "5min"
    MIN_15 = "15min"
    MIN_30 = "30min"
    HOUR_1 = "1h"
    HOUR_4 = "4h"
    DAY_1 = "1D"
    WEEK_1 = "1W"
    MONTH_1 = "1M"


class OrderStrategy(str, Enum):
    """訂單策略枚舉（與 Rust OrderStrategy enum 一致）

    對應 Rust 的 OrderStrategy enum，使用字符串值以便 JSON 序列化

    Rust 對應關係:
    - Rust: OrderStrategy::ImmediateEntry      → Python: OrderStrategy.IMMEDIATE_ENTRY      (u32: 0)
    - Rust: OrderStrategy::FavorableDelayEntry → Python: OrderStrategy.FAVORABLE_DELAY_ENTRY (u32: 1)
    - Rust: OrderStrategy::AdverseDelayEntry   → Python: OrderStrategy.ADVERSE_DELAY_ENTRY   (u32: 2)
    - Rust: OrderStrategy::ImmediateExit       → Python: OrderStrategy.IMMEDIATE_EXIT        (u32: 3)
    - Rust: OrderStrategy::StopLoss            → Python: OrderStrategy.STOP_LOSS             (u32: 4)
    - Rust: OrderStrategy::TakeProfit          → Python: OrderStrategy.TAKE_PROFIT           (u32: 5)
    - Rust: OrderStrategy::TrailingStop        → Python: OrderStrategy.TRAILING_STOP         (u32: 6)
    - Rust: OrderStrategy::Breakeven           → Python: OrderStrategy.BREAKEVEN             (u32: 7)
    - Rust: OrderStrategy::TimeoutExit         → Python: OrderStrategy.TIMEOUT_EXIT          (u32: 8)
    """

    IMMEDIATE_ENTRY = "ImmediateEntry"
    FAVORABLE_DELAY_ENTRY = "FavorableDelayEntry"
    ADVERSE_DELAY_ENTRY = "AdverseDelayEntry"
    IMMEDIATE_EXIT = "ImmediateExit"
    STOP_LOSS = "StopLoss"
    TAKE_PROFIT = "TakeProfit"
    TRAILING_STOP = "TrailingStop"
    BREAKEVEN = "Breakeven"
    TIMEOUT_EXIT = "TimeoutExit"


class Weekday(str, Enum):
    """星期列舉（與 Rust Weekday enum 一致）

    用於 Market Profile 的 WeeklyTime 配置

    對應關係：
    - 0 (週一) → "Mon"
    - 1 (週二) → "Tue"
    - 2 (週三) → "Wed"
    - 3 (週四) → "Thu"
    - 4 (週五) → "Fri"
    - 5 (週六) → "Sat"
    - 6 (週日) → "Sun"
    """

    MON = "Mon"
    TUE = "Tue"
    WED = "Wed"
    THU = "Thu"
    FRI = "Fri"
    SAT = "Sat"
    SUN = "Sun"


class PolarsExprField:
    """自定義 Polars Expr 字段處理"""

    @staticmethod
    def serialize(expr: pl.Expr) -> dict:
        """序列化 Polars Expr 為 dict（與服務器格式一致）"""
        json_str = expr.meta.serialize(format="json")
        return json.loads(json_str)

    @staticmethod
    def deserialize(data: Union[str, dict, pl.Expr]) -> pl.Expr:
        """反序列化為 Polars Expr"""
        if isinstance(data, pl.Expr):
            # 已經是 Expr 對象
            return data
        elif isinstance(data, dict):
            # API 返回的 dict（優先處理）
            json_str = json.dumps(data)
            return pl.Expr.deserialize(StringIO(json_str), format="json")
        elif isinstance(data, str):
            # JSON 字符串（向後兼容）
            return pl.Expr.deserialize(StringIO(data), format="json")
        else:
            raise ValueError(f"無法反序列化類型: {type(data)}")


# ============================================================================
# Indicator 輔助類（用於指標配置）
# ============================================================================


class AtrQuantileConfig(BaseModel):
    """ATR 分位數配置（用於 ATR 指標）

    對應 Rust: AtrQuantileConfig struct

    用於計算 ATR 的滾動分位數，可用於動態止損等場景

    Example:
        >>> config = AtrQuantileConfig(window=20, quantile=0.5)  # 20 週期中位數
        >>> config = AtrQuantileConfig(window=20, quantile=0.75) # 20 週期 75% 分位數
    """

    window: int = Field(..., gt=0, description="滾動窗口大小（必須 > 0）")
    quantile: float = Field(
        ..., gt=0, lt=1, description="分位數值，範圍 (0, 1)，例如 0.5 表示中位數"
    )


class ProfileShapeConfig(BaseModel):
    """Profile 形狀識別配置（用於 MarketProfile 指標）

    對應 Rust: ProfileShapeConfig struct

    控制 Market Profile 形狀識別算法的閾值參數（進階功能，通常使用預設值即可）

    Profile 形狀類型：
    - "p_shaped": P型（快速上漲 + 高位盤整，看空信號）
    - "b_shaped": b型（快速下跌 + 低位盤整，看多信號）
    - "b_double_distribution": B型雙峰（區間交易）
    - "trend_day": 趨勢日（持續單向移動，順勢交易）
    - "normal": 正態分布（對稱分布，區間交易）
    - "undefined": 無法分類

    Example:
        >>> # 使用預設值（推薦）
        >>> config = ProfileShapeConfig()
        >>>
        >>> # 自訂閾值（進階）
        >>> config = ProfileShapeConfig(
        ...     trend_monotonic_threshold=0.65,
        ...     pshape_concentration_threshold=0.65
        ... )
    """

    early_period_ratio: float = Field(
        0.15, gt=0, le=1, description="早期時段比例（前 15% 視為早期）"
    )
    late_period_ratio: float = Field(
        0.15, gt=0, le=1, description="晚期時段比例（後 15% 視為晚期）"
    )
    trend_ib_max_ratio: float = Field(
        0.20, gt=0, le=1, description="趨勢日 IB 最大占比"
    )
    trend_monotonic_threshold: float = Field(
        0.60, gt=0, le=1, description="趨勢日單向移動閾值"
    )
    trend_imbalance_threshold: float = Field(
        0.70, gt=0, le=1, description="趨勢日早期/晚期 TPO 不平衡度閾值"
    )
    pshape_concentration_threshold: float = Field(
        0.60, gt=0, le=1, description="P型/b型 TPO 集中度閾值"
    )
    bshape_valley_threshold: float = Field(
        0.70, gt=0, le=1, description="B型雙峰之間谷的深度閾值"
    )
    normal_symmetry_threshold: float = Field(
        0.30, gt=0, le=1, description="Normal 型對稱性閾值"
    )


# ============================================================================
# Indicator 工廠類（對應 Rust Indicator enum 的各個變體）
# ============================================================================


class Indicator:
    """指標工廠類（對應 Rust 的 Indicator enum）

    使用靜態方法創建各種指標配置，語法類似 Rust 的關聯函數

    支援的指標類型（15 種）：
    - 移動平均: SMA, EMA, SMMA, WMA
    - 波動率: ATR, AtrQuantile
    - 通道指標: BollingerBands
    - 趨勢指標: SuperTrend, ADX, MACD
    - 動量指標: RSI, CCI, Stochastic
    - 價格分布: MarketProfile
    - 原始數據: RawOhlcv

    Example:
        >>> from strategy_models import Indicator
        >>>
        >>> # 移動平均
        >>> sma = Indicator.sma(period=20)
        >>> sma_on_high = Indicator.sma(period=20, column="high")
        >>> ema = Indicator.ema(period=12)
        >>>
        >>> # 波動率
        >>> atr = Indicator.atr(period=14)
        >>> atr_q = Indicator.atr_quantile("ATR|14", window=20, quantile=0.75)
        >>>
        >>> # 通道指標
        >>> bb = Indicator.bollinger_bands(period=20, num_std=2.0)
        >>>
        >>> # 趨勢指標
        >>> st = Indicator.supertrend(multiplier=3.0, volatility_column="ATR|14")
        >>> macd = Indicator.macd(fast_period=12, slow_period=26, signal_period=9)
        >>> adx = Indicator.adx(period=14)
        >>>
        >>> # 動量指標
        >>> rsi = Indicator.rsi(period=14)
        >>> cci = Indicator.cci(period=20)
        >>> stoch = Indicator.stochastic(k_period=14, d_period=3)
    """

    @staticmethod
    def sma(period: int, column: str = "close") -> Dict[str, Any]:
        """創建 SMA 指標配置

        對應 Rust: Indicator::SMA { period, column }

        Args:
            period: 週期
            column: 計算欄位（預設 "close"）

        Returns:
            SMA 指標配置 dict

        Example:
            >>> Indicator.sma(period=20)
            >>> Indicator.sma(period=20, column="high")
        """
        return {"type": "SMA", "period": period, "column": column}

    @staticmethod
    def ema(period: int, column: str = "close") -> Dict[str, Any]:
        """創建 EMA 指標配置

        對應 Rust: Indicator::EMA { period, column }

        Args:
            period: 週期
            column: 計算欄位（預設 "close"）

        Returns:
            EMA 指標配置 dict

        Example:
            >>> Indicator.ema(period=12)
            >>> Indicator.ema(period=12, column="low")
        """
        return {"type": "EMA", "period": period, "column": column}

    @staticmethod
    def smma(period: int, column: str = "close") -> Dict[str, Any]:
        """創建 SMMA 指標配置

        對應 Rust: Indicator::SMMA { period, column }

        Args:
            period: 週期
            column: 計算欄位（預設 "close"）

        Returns:
            SMMA 指標配置 dict

        Example:
            >>> Indicator.smma(period=14)
        """
        return {"type": "SMMA", "period": period, "column": column}

    @staticmethod
    def wma(period: int, column: str = "close") -> Dict[str, Any]:
        """創建 WMA 指標配置

        對應 Rust: Indicator::WMA { period, column }

        Args:
            period: 週期
            column: 計算欄位（預設 "close"）

        Returns:
            WMA 指標配置 dict

        Example:
            >>> Indicator.wma(period=10)
        """
        return {"type": "WMA", "period": period, "column": column}

    @staticmethod
    def atr(period: int) -> Dict[str, Any]:
        """創建 ATR 指標配置

        對應 Rust: Indicator::ATR { period }

        Args:
            period: 週期（必須 > 0）

        Returns:
            ATR 指標配置 dict

        Note:
            ATR 輸出為**單一數值欄位**，列名格式為 `ATR|{period}`（例如 `ATR|14`）

            如需計算 ATR 的滾動分位數，請使用 `Indicator.atr_quantile()` 獨立指標

        Example:
            >>> # 基礎 ATR（返回單一數值欄位）
            >>> Indicator.atr(period=14)
            >>> # 輸出列名: "ATR|14"
            >>>
            >>> # 在 Python 中訪問
            >>> import polars as pl
            >>> df = pl.read_parquet("enhanced_ohlcv.parquet")
            >>> atr_values = df["ATR|14"]  # 直接訪問數值欄位
            >>>
            >>> # 計算止損
            >>> stop_loss = df.with_columns([
            ...     (pl.col("close") - 2 * pl.col("ATR|14")).alias("stop_loss")
            ... ])
        """
        return {"type": "ATR", "period": period}

    @staticmethod
    def atr_quantile(
        atr_column: str,
        window: int,
        quantile: float,
    ) -> Dict[str, Any]:
        """創建 AtrQuantile 指標配置

        對應 Rust: Indicator::AtrQuantile { atr_column, window, quantile }

        Args:
            atr_column: ATR 欄位名稱（例如 "ATR|14"）
            window: 滾動窗口大小（必須 > 0）
            quantile: 分位數值，範圍 (0, 1)
                - 0.5: 中位數
                - 0.75: 75% 分位數（較高波動率）
                - 0.25: 25% 分位數（較低波動率）

        Returns:
            AtrQuantile 指標配置 dict

        Note:
            - AtrQuantile 輸出為**單一數值欄位**（f64）
            - 列名格式：`ATRQ|{atr_column}_Q{quantile*100}_{window}`
            - **重要**：AtrQuantile 依賴 ATR，必須先定義 ATR 指標

        Example:
            >>> # 基礎用法：計算 ATR|14 的 50% 分位數（20 窗口）
            >>> Indicator.atr_quantile(
            ...     atr_column="ATR|14",
            ...     window=20,
            ...     quantile=0.5
            ... )
            >>> # 輸出列名: "ATRQ|ATR|14_Q50_20"
            >>>
            >>> # 在策略中使用（完整示例）
            >>> from tradepose_client.models import (
            ...     Indicator, create_indicator_spec, Freq
            ... )
            >>>
            >>> # 1. 先定義 ATR
            >>> atr_spec = create_indicator_spec(
            ...     freq=Freq.DAY_1,
            ...     indicator=Indicator.atr(period=14),
            ...     shift=1
            ... )
            >>>
            >>> # 2. 再定義 AtrQuantile（動態引用 ATR 列名）
            >>> atr_q_spec = create_indicator_spec(
            ...     freq=Freq.DAY_1,
            ...     indicator=Indicator.atr_quantile(
            ...         atr_column=atr_spec.short_name(),  # 動態引用，自動與 ATR 同步
            ...         window=20,
            ...         quantile=0.75  # 75% 分位數
            ...     ),
            ...     shift=1
            ... )
            >>>
            >>> # 在 Python 中訪問（直接使用列名，無需 struct.field）
            >>> import polars as pl
            >>> df = pl.read_parquet("enhanced_ohlcv.parquet")
            >>>
            >>> # 動態止損示例：直接引用 AtrQuantile 列
            >>> df = df.with_columns([
            ...     (pl.col("close") - 2 * pl.col("1D_ATRQ|ATR|14_Q75_20")).alias("dynamic_stop_loss")
            ... ])
            >>>
            >>> # 或在策略條件中直接使用
            >>> from tradepose_client.models import create_trigger
            >>> trigger = create_trigger(
            ...     name="low_volatility_entry",
            ...     conditions=[
            ...         pl.col("1D_ATR|14") < pl.col("1D_ATRQ|ATR|14_Q75_20")  # ATR < Q75
            ...     ],
            ...     price_expr=pl.col("open"),
            ...     order_strategy="ImmediateEntry"
            ... )
        """
        return {
            "type": "AtrQuantile",
            "atr_column": atr_column,
            "window": window,
            "quantile": quantile,
        }

    @staticmethod
    def supertrend(
        multiplier: float,
        volatility_column: str,
        high: str = "high",
        low: str = "low",
        close: str = "close",
        fields: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
        """創建 SuperTrend 指標配置

        對應 Rust: Indicator::SuperTrend { multiplier, volatility_column, high, low, close, fields }

        Args:
            multiplier: 波動率倍數
            volatility_column: 波動率欄位名稱（例如 "ATR|14"）
            high: 高點欄位（預設 "high"）
            low: 低點欄位（預設 "low"）
            close: 收盤價欄位（預設 "close"）
            fields: 保留欄位（可選，例如 ["direction", "supertrend", "long", "short"]）
                - 可用欄位: "direction", "supertrend", "long", "short"
                - direction: 趨勢方向（1=多頭，-1=空頭）
                - long: 多頭 SuperTrend 線（僅多頭時有值，空頭時為 null）
                - short: 空頭 SuperTrend 線（僅空頭時有值，多頭時為 null）
                - 省略或 None：返回所有欄位
                - 空數組 []：返回所有欄位（與 None 等效）

        Returns:
            SuperTrend 指標配置 dict

        Example:
            >>> # 先定義 ATR 指標
            >>> atr_spec = create_indicator_spec(
            ...     freq=Freq.DAY_1,
            ...     indicator=Indicator.atr(period=14),
            ...     shift=1
            ... )
            >>>
            >>> # SuperTrend 動態引用 ATR 列名
            >>> Indicator.supertrend(
            ...     multiplier=3.0,
            ...     volatility_column=atr_spec.short_name()  # 動態引用 "ATR|14"
            ... )
            >>>
            >>> # 僅保留核心欄位
            >>> Indicator.supertrend(
            ...     multiplier=3.0,
            ...     volatility_column=atr_spec.short_name(),
            ...     fields=["direction", "supertrend"]
            ... )
        """
        config = {
            "type": "SuperTrend",
            "multiplier": float(multiplier),
            "volatility_column": volatility_column,
            "high": high,
            "low": low,
            "close": close,
        }
        if fields is not None:
            config["fields"] = fields
        return config

    @staticmethod
    def market_profile(
        anchor_config: Dict[str, Any],
        tick_size: float,
        value_area_pct: float = 0.7,
        fields: Optional[List[str]] = None,
        shape_config: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """創建 Market Profile 指標配置

        對應 Rust: Indicator::MarketProfile { anchor_config, tick_size, ... }

        Args:
            anchor_config: Anchor 分段配置（使用 create_daily_anchor() 或 create_weekly_anchor()）
                - end_rule: 結束時間規則
                    - DailyTime: {"type": "DailyTime", "hour": int, "minute": int}
                    - WeeklyTime: {"type": "WeeklyTime", "weekday": str, "hour": int, "minute": int}
                - start_rule: 開始時間規則（可選）
                - lookback_days: 回溯天數
            tick_size: 最小價格單位
            value_area_pct: Value Area 百分比（預設 0.7）
            fields: 保留欄位（可選，例如 ["poc", "vah", "val", "profile_shape"]）
                - 可用欄位: "poc", "vah", "val", "value_area", "tpo_distribution",
                            "segment_id", "profile_shape"
                - 省略或 None：返回所有欄位
                - 空數組 []：返回所有欄位（與 None 等效）
                - segment_id 會自動包含（已 ffill，可用於窗口操作）
            shape_config: Profile 形狀識別配置（可選，進階功能）
                用於控制形狀識別算法的閾值參數，通常使用預設值即可
                可用 ProfileShapeConfig 類創建

        Returns:
            Market Profile 指標配置 dict

        Note:
            - shift 只存在於 IndicatorSpec 層級
            - 系統固定使用 "ts" 和 "segment_id" 欄位名稱
            - Market Profile 輸出為 struct 欄位，包含 TPO 價格分布、POC、VAH、VAL 等資訊
            - segment_id 已 ffill，可直接用於 Polars 窗口函數

        Example:
            >>> # 每日 09:15 結束，回溯 1 天
            >>> Indicator.market_profile(
            ...     anchor_config=create_daily_anchor(9, 15, 1),
            ...     tick_size=0.01
            ... )
            >>>
            >>> # 每週一 09:15 結束，回溯 5 天，僅保留 POC/VAH/VAL/形狀
            >>> Indicator.market_profile(
            ...     anchor_config=create_weekly_anchor("Mon", 9, 15, 5),
            ...     tick_size=0.01,
            ...     fields=["poc", "vah", "val", "profile_shape"]
            ... )
            >>>
            >>> # 自訂形狀識別閾值（進階）
            >>> from tradepose_client.models import ProfileShapeConfig
            >>> shape_cfg = ProfileShapeConfig(
            ...     trend_monotonic_threshold=0.65,
            ...     pshape_concentration_threshold=0.65
            ... )
            >>> Indicator.market_profile(
            ...     anchor_config=create_daily_anchor(9, 15, 1),
            ...     tick_size=0.5,
            ...     shape_config=shape_cfg.model_dump()
            ... )
        """
        config = {
            "type": "MarketProfile",
            "anchor_config": anchor_config,
            "tick_size": tick_size,
            "value_area_pct": value_area_pct,
        }
        if fields is not None:
            config["fields"] = fields
        if shape_config is not None:
            config["shape_config"] = shape_config
        return config

    @staticmethod
    def cci(period: int = 20) -> Dict[str, Any]:
        """創建 CCI 指標配置

        對應 Rust: Indicator::CCI { period }

        CCI (Commodity Channel Index) 由 Donald Lambert 開發，用於衡量價格與統計平均值的偏離程度，
        常用於識別超買/超賣狀態。

        Args:
            period: 週期（必須 > 0，預設 20）

        Returns:
            CCI 指標配置 dict

        Note:
            - CCI 輸出為**單一 f64 欄位**，值域無限制（通常在 -300 到 +300 之間）
            - 列名格式為 `CCI|{period}`（例如 `CCI|20`）
            - 解讀：> +100 為超買，< -100 為超賣，-100~+100 為中性區間

        Example:
            >>> # 使用預設參數（20 週期）
            >>> Indicator.cci(period=20)
            >>> # 輸出列名: "CCI|20"
            >>>
            >>> # 在策略中使用
            >>> cci_spec = create_indicator_spec(
            ...     freq=Freq.HOUR_1,
            ...     indicator=Indicator.cci(period=14),
            ...     shift=1
            ... )
            >>> # 列名: "1h_CCI|14"
            >>>
            >>> # 超買/超賣條件
            >>> overbought = pl.col("1h_CCI|14") > 100
            >>> oversold = pl.col("1h_CCI|14") < -100
        """
        return {"type": "CCI", "period": period}

    @staticmethod
    def rsi(period: int = 14, column: str = "close") -> Dict[str, Any]:
        """創建 RSI 指標配置

        對應 Rust: Indicator::RSI { period, column }

        RSI (Relative Strength Index) 由 J. Welles Wilder Jr. 開發，用於衡量價格變動的速度和幅度，
        是最廣泛使用的動量指標之一。

        Args:
            period: 週期（必須 > 0，預設 14）
            column: 計算欄位（預設 "close"）

        Returns:
            RSI 指標配置 dict

        Note:
            - RSI 輸出為**單一 f64 欄位**，值域 0-100
            - 列名格式為 `RSI|{period}`（例如 `RSI|14`）
            - 使用 Wilder's SMMA（α = 1/period）計算
            - 解讀：> 70 為超買，< 30 為超賣，30~70 為中性

        Example:
            >>> # 使用預設參數（14 週期，close 欄位）
            >>> Indicator.rsi(period=14, column="close")
            >>> # 輸出列名: "RSI|14"
            >>>
            >>> # 計算其他欄位的 RSI
            >>> Indicator.rsi(period=9, column="hl2")
            >>>
            >>> # 在策略中使用
            >>> rsi_spec = create_indicator_spec(
            ...     freq=Freq.MIN_15,
            ...     indicator=Indicator.rsi(period=14),
            ...     shift=1
            ... )
            >>> # 列名: "15min_RSI|14"
            >>>
            >>> # 超買/超賣條件
            >>> entry_long = pl.col("15min_RSI|14") < 30  # RSI < 30 做多
            >>> entry_short = pl.col("15min_RSI|14") > 70  # RSI > 70 做空
        """
        return {"type": "RSI", "period": period, "column": column}

    @staticmethod
    def bollinger_bands(
        period: int = 20,
        num_std: float = 2.0,
        column: str = "close",
        fields: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
        """創建 Bollinger Bands 指標配置

        對應 Rust: Indicator::BollingerBands { period, num_std, column, fields }

        Bollinger Bands 由 John Bollinger 開發，使用標準差來動態調整通道寬度，
        用於衡量價格波動率和識別超買/超賣。

        Args:
            period: 週期（必須 > 0，預設 20）
            num_std: 標準差倍數（必須 > 0，預設 2.0）
            column: 計算欄位（預設 "close"）
            fields: 保留欄位（可選，例如 ["upper", "lower", "middle", "bandwidth"]）
                - 可用欄位: "upper", "middle", "lower", "bandwidth"
                - 省略或 None：返回所有欄位

        Returns:
            Bollinger Bands 指標配置 dict

        Note:
            - Bollinger Bands 輸出為 **Struct 欄位**
            - 列名格式為 `BB|{period}_{num_std}`（例如 `BB|20_2.0`）
            - 子欄位:
                - upper: 上軌（SMA + N×σ）
                - middle: 中軌（SMA）
                - lower: 下軌（SMA - N×σ）
                - bandwidth: 通道寬度（upper - lower）

        Example:
            >>> # 使用預設參數（20 週期，2 倍標準差）
            >>> Indicator.bollinger_bands(period=20, num_std=2.0, column="close")
            >>> # 輸出列名: "BB|20_2.0"
            >>>
            >>> # 僅保留核心欄位
            >>> Indicator.bollinger_bands(
            ...     period=20,
            ...     num_std=2.0,
            ...     column="close",
            ...     fields=["upper", "lower", "middle"]
            ... )
            >>>
            >>> # 在策略中使用
            >>> bb_spec = create_indicator_spec(
            ...     freq=Freq.HOUR_1,
            ...     indicator=Indicator.bollinger_bands(period=20, num_std=2.5),
            ...     shift=1
            ... )
            >>> # 列名: "1h_BB|20_2.5"
            >>>
            >>> # 存取子欄位
            >>> upper = pl.col("1h_BB|20_2.5").struct.field("upper")
            >>> lower = pl.col("1h_BB|20_2.5").struct.field("lower")
            >>> middle = pl.col("1h_BB|20_2.5").struct.field("middle")
            >>>
            >>> # 突破交易條件
            >>> breakout_up = pl.col("close") > upper
            >>> breakout_down = pl.col("close") < lower
        """
        config = {
            "type": "BollingerBands",
            "period": period,
            "num_std": float(num_std),
            "column": column,
        }
        if fields is not None:
            config["fields"] = fields
        return config

    @staticmethod
    def macd(
        fast_period: int = 12,
        slow_period: int = 26,
        signal_period: int = 9,
        column: str = "close",
        fields: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
        """創建 MACD 指標配置

        對應 Rust: Indicator::MACD { fast_period, slow_period, signal_period, column, fields }

        MACD (Moving Average Convergence Divergence) 由 Gerald Appel 開發，
        通過快慢 EMA 的差值來識別趨勢變化和動量。

        Args:
            fast_period: 快線週期（必須 > 0，預設 12）
            slow_period: 慢線週期（必須 > 0，預設 26）
            signal_period: 信號線週期（必須 > 0，預設 9）
            column: 計算欄位（預設 "close"）
            fields: 保留欄位（可選，例如 ["macd", "signal", "histogram"]）
                - 可用欄位: "macd", "signal", "histogram"
                - 省略或 None：返回所有欄位

        Returns:
            MACD 指標配置 dict

        Note:
            - MACD 輸出為 **Struct 欄位**
            - 列名格式為 `MACD|{fast_period}_{slow_period}_{signal_period}`（例如 `MACD|12_26_9`）
            - 子欄位:
                - macd: MACD 線（快線 - 慢線）
                - signal: 信號線（MACD 的 EMA）
                - histogram: 柱狀圖（MACD - Signal）

        Example:
            >>> # 使用預設參數（12, 26, 9）
            >>> Indicator.macd(fast_period=12, slow_period=26, signal_period=9)
            >>> # 輸出列名: "MACD|12_26_9"
            >>>
            >>> # 僅保留 MACD 和 Signal
            >>> Indicator.macd(
            ...     fast_period=12,
            ...     slow_period=26,
            ...     signal_period=9,
            ...     fields=["macd", "signal"]
            ... )
            >>>
            >>> # 在策略中使用
            >>> macd_spec = create_indicator_spec(
            ...     freq=Freq.DAY_1,
            ...     indicator=Indicator.macd(),
            ...     shift=1
            ... )
            >>> # 列名: "1D_MACD|12_26_9"
            >>>
            >>> # 存取子欄位
            >>> macd_line = pl.col("1D_MACD|12_26_9").struct.field("macd")
            >>> signal_line = pl.col("1D_MACD|12_26_9").struct.field("signal")
            >>> histogram = pl.col("1D_MACD|12_26_9").struct.field("histogram")
            >>>
            >>> # 金叉/死叉條件
            >>> golden_cross = macd_line > signal_line  # 金叉（做多）
            >>> death_cross = macd_line < signal_line   # 死叉（做空）
        """
        config = {
            "type": "MACD",
            "fast_period": fast_period,
            "slow_period": slow_period,
            "signal_period": signal_period,
            "column": column,
        }
        if fields is not None:
            config["fields"] = fields
        return config

    @staticmethod
    def stochastic(
        k_period: int = 14,
        d_period: int = 3,
        fields: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
        """創建 Stochastic 指標配置

        對應 Rust: Indicator::Stochastic { k_period, d_period, fields }

        Stochastic (隨機指標) 由 George Lane 開發，通過比較收盤價與價格區間來衡量動量，
        用於識別超買/超賣。

        Args:
            k_period: %K 週期（必須 > 0，預設 14）
            d_period: %D 週期（必須 > 0，預設 3）
            fields: 保留欄位（可選，例如 ["k", "d"]）
                - 可用欄位: "k", "d"
                - 省略或 None：返回所有欄位

        Returns:
            Stochastic 指標配置 dict

        Note:
            - Stochastic 輸出為 **Struct 欄位**
            - 列名格式為 `STOCH|{k_period}_{d_period}`（例如 `STOCH|14_3`）
            - 子欄位:
                - k: %K 線（快線，0-100）
                - d: %D 線（慢線，%K 的 SMA，0-100）
            - 解讀：> 80 為超買，< 20 為超賣，20~80 為中性

        Example:
            >>> # 使用預設參數（14, 3）
            >>> Indicator.stochastic(k_period=14, d_period=3)
            >>> # 輸出列名: "STOCH|14_3"
            >>>
            >>> # 僅保留 %K 線
            >>> Indicator.stochastic(k_period=14, d_period=3, fields=["k"])
            >>>
            >>> # 在策略中使用
            >>> stoch_spec = create_indicator_spec(
            ...     freq=Freq.MIN_15,
            ...     indicator=Indicator.stochastic(),
            ...     shift=1
            ... )
            >>> # 列名: "15min_STOCH|14_3"
            >>>
            >>> # 存取子欄位
            >>> k_line = pl.col("15min_STOCH|14_3").struct.field("k")
            >>> d_line = pl.col("15min_STOCH|14_3").struct.field("d")
            >>>
            >>> # 超買/超賣條件
            >>> oversold = k_line < 20  # %K < 20（做多）
            >>> overbought = k_line > 80  # %K > 80（做空）
            >>>
            >>> # 金叉/死叉條件
            >>> golden_cross = k_line > d_line  # 金叉（做多）
            >>> death_cross = k_line < d_line   # 死叉（做空）
        """
        config = {
            "type": "Stochastic",
            "k_period": k_period,
            "d_period": d_period,
        }
        if fields is not None:
            config["fields"] = fields
        return config

    @staticmethod
    def adx(period: int = 14, fields: Optional[List[str]] = None) -> Dict[str, Any]:
        """創建 ADX 指標配置

        對應 Rust: Indicator::ADX { period, fields }

        ADX (Average Directional Index) 由 J. Welles Wilder Jr. 開發，用於量化趨勢強度（不區分方向），
        同時提供方向性指標（+DI/-DI）和 ADXR。

        Args:
            period: 週期（必須 > 0，預設 14）
            fields: 保留欄位（可選，例如 ["adx", "plus_di", "minus_di", "adxr"]）
                - 可用欄位: "adx", "plus_di", "minus_di", "adxr", "dx"
                - 預設（None 或 []）：返回 ["adx", "plus_di", "minus_di", "adxr"]（不包含 dx）
                - dx 欄位僅在明確指定時才包含

        Returns:
            ADX 指標配置 dict

        Note:
            - ADX 輸出為 **Struct 欄位**
            - 列名格式為 `ADX|{period}`（例如 `ADX|14`）
            - 子欄位:
                - adx: ADX 值（趨勢強度，0-100）
                - plus_di: +DI（上升動量，0-100）
                - minus_di: -DI（下降動量，0-100）
                - adxr: ADXR（ADX 的平滑值）
                - dx: DX（方向性指標，ADX 的原始值，0-100，需明確指定）
            - ADX 解讀：
                - 0-25: 弱趨勢（避免趨勢策略）
                - 25-50: 中等趨勢（適合趨勢跟隨）
                - 50-75: 強趨勢（強勢跟單）
                - 75-100: 極強趨勢（警惕反轉）

        Example:
            >>> # 使用預設參數（14 週期，返回 adx, plus_di, minus_di, adxr）
            >>> Indicator.adx(period=14)
            >>> # 輸出列名: "ADX|14"
            >>>
            >>> # 僅保留 ADX 和方向性指標
            >>> Indicator.adx(period=14, fields=["adx", "plus_di", "minus_di"])
            >>>
            >>> # 包含 DX 原始值
            >>> Indicator.adx(period=14, fields=["adx", "dx"])
            >>>
            >>> # 在策略中使用
            >>> adx_spec = create_indicator_spec(
            ...     freq=Freq.HOUR_1,
            ...     indicator=Indicator.adx(period=14),
            ...     shift=1
            ... )
            >>> # 列名: "1h_ADX|14"
            >>>
            >>> # 存取子欄位
            >>> adx_value = pl.col("1h_ADX|14").struct.field("adx")
            >>> plus_di = pl.col("1h_ADX|14").struct.field("plus_di")
            >>> minus_di = pl.col("1h_ADX|14").struct.field("minus_di")
            >>>
            >>> # 趨勢強度過濾
            >>> strong_trend = adx_value > 25  # 中等以上趨勢
            >>>
            >>> # 方向判斷
            >>> uptrend = (plus_di > minus_di) & (adx_value > 25)  # 上升趨勢 + 強度足夠
            >>> downtrend = (plus_di < minus_di) & (adx_value > 25)  # 下降趨勢 + 強度足夠
        """
        config = {
            "type": "ADX",
            "period": period,
        }
        if fields is not None:
            config["fields"] = fields
        return config

    @staticmethod
    def raw_ohlcv(column: str) -> Dict[str, Any]:
        """創建 RawOhlcv 指標配置

        對應 Rust: Indicator::RawOhlcv { column }

        用於直接訪問已 resample 到指定頻率的原始 OHLCV 列數據，無需任何額外計算。

        Args:
            column: OHLCV 列名，可選值：
                - "open": 開盤價
                - "high": 最高價
                - "low": 最低價
                - "close": 收盤價
                - "volume": 成交量

        Returns:
            RawOhlcv 指標配置 dict

        Note:
            - RawOhlcv 只支持向上採樣（freq > base_freq）
            - 如果 freq = base_freq，應直接使用原始列名而非 RawOhlcv
            - 向下採樣不支持（會報錯）

        Example:
            >>> # 獲取日線開盤價（在分鐘級策略中）
            >>> Indicator.raw_ohlcv(column="open")
            >>>
            >>> # 獲取小時線收盤價
            >>> Indicator.raw_ohlcv(column="close")
            >>>
            >>> # 完整範例：在策略中使用
            >>> daily_open = create_indicator_spec(
            ...     freq=Freq.DAY_1,
            ...     indicator=Indicator.raw_ohlcv("open"),
            ...     instrument_id="TXF_M1_SHIOAJI_FUTURE",
            ...     shift=1
            ... )
            >>> # 輸出列名: "TXF_M1_SHIOAJI_FUTURE_open_1D"
            >>> # 策略條件: if price > daily_open.col(): ...
        """
        return {"type": "RawOhlcv", "column": column}


# ============================================================================
# Anchor Config 輔助函數（用於 Market Profile）
# ============================================================================


def create_daily_anchor(
    hour: int,
    minute: int,
    lookback_days: int = 1,
) -> Dict[str, Any]:
    """創建每日 Anchor 配置（用於 Market Profile）

    Args:
        hour: 小時 (0-23)
        minute: 分鐘 (0-59)
        lookback_days: 回溯天數（預設 1）

    Returns:
        Anchor 配置 dict

    Note:
        系統固定使用 "ts" 和 "segment_id" 欄位名稱

    Example:
        >>> # 每日 09:15 結束，回溯 1 天
        >>> anchor = create_daily_anchor(9, 15, 1)
        >>> mp = Indicator.market_profile(
        ...     anchor_config=anchor,
        ...     tick_size=0.01
        ... )
    """
    return {
        "end_rule": {"type": "DailyTime", "hour": hour, "minute": minute},
        "start_rule": None,
        "lookback_days": lookback_days,
    }


def create_weekly_anchor(
    weekday: Union[int, str, Weekday],
    hour: int,
    minute: int,
    lookback_days: int = 5,
) -> Dict[str, Any]:
    """創建每週 Anchor 配置（用於 Market Profile）

    Args:
        weekday: 星期幾，支持多種格式:
            - int: 0=週一, 1=週二, ..., 6=週日
            - str: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"
            - Weekday enum: Weekday.MON, Weekday.TUE, ...
        hour: 小時 (0-23)
        minute: 分鐘 (0-59)
        lookback_days: 回溯天數（預設 5）

    Returns:
        Anchor 配置 dict

    Note:
        系統固定使用 "ts" 和 "segment_id" 欄位名稱

    Example:
        >>> # 使用整數
        >>> anchor = create_weekly_anchor(0, 9, 15, 5)  # 週一
        >>> # 使用字串
        >>> anchor = create_weekly_anchor("Mon", 9, 15, 5)
        >>> # 使用 Weekday enum
        >>> anchor = create_weekly_anchor(Weekday.MON, 9, 15, 5)
        >>> mp = Indicator.market_profile(
        ...     anchor_config=anchor,
        ...     tick_size=0.01
        ... )
    """
    # 轉換 weekday 為字串格式
    weekday_map = {
        0: "Mon",
        1: "Tue",
        2: "Wed",
        3: "Thu",
        4: "Fri",
        5: "Sat",
        6: "Sun",
    }

    if isinstance(weekday, int):
        weekday_str = weekday_map[weekday]
    elif isinstance(weekday, Weekday):
        weekday_str = weekday.value
    else:
        weekday_str = str(weekday)

    return {
        "end_rule": {
            "type": "WeeklyTime",
            "weekday": weekday_str,
            "hour": hour,
            "minute": minute,
        },
        "start_rule": None,
        "lookback_days": lookback_days,
    }


def create_profile_shape_config(
    early_period_ratio: float = 0.15,
    late_period_ratio: float = 0.15,
    trend_ib_max_ratio: float = 0.20,
    trend_monotonic_threshold: float = 0.60,
    trend_imbalance_threshold: float = 0.70,
    pshape_concentration_threshold: float = 0.60,
    bshape_valley_threshold: float = 0.70,
    normal_symmetry_threshold: float = 0.30,
) -> Dict[str, Any]:
    """創建 Profile 形狀識別配置（用於 MarketProfile 指標）

    Args:
        early_period_ratio: 早期時段比例（前 15% 視為早期），預設 0.15
        late_period_ratio: 晚期時段比例（後 15% 視為晚期），預設 0.15
        trend_ib_max_ratio: 趨勢日 IB 最大占比，預設 0.20
        trend_monotonic_threshold: 趨勢日單向移動閾值，預設 0.60
        trend_imbalance_threshold: 趨勢日早期/晚期 TPO 不平衡度閾值，預設 0.70
        pshape_concentration_threshold: P型/b型 TPO 集中度閾值，預設 0.60
        bshape_valley_threshold: B型雙峰之間谷的深度閾值，預設 0.70
        normal_symmetry_threshold: Normal 型對稱性閾值，預設 0.30

    Returns:
        Profile 形狀識別配置 dict

    Note:
        通常使用預設值即可，僅在需要微調形狀識別邏輯時才自訂參數

    Example:
        >>> # 使用預設值（推薦）
        >>> shape_config = create_profile_shape_config()
        >>> Indicator.market_profile(
        ...     anchor_config=create_daily_anchor(9, 15, 1),
        ...     tick_size=0.5,
        ...     shape_config=shape_config
        ... )
        >>>
        >>> # 自訂閾值（進階）
        >>> shape_config = create_profile_shape_config(
        ...     trend_monotonic_threshold=0.65,
        ...     pshape_concentration_threshold=0.65
        ... )
    """
    return {
        "early_period_ratio": early_period_ratio,
        "late_period_ratio": late_period_ratio,
        "trend_ib_max_ratio": trend_ib_max_ratio,
        "trend_monotonic_threshold": trend_monotonic_threshold,
        "trend_imbalance_threshold": trend_imbalance_threshold,
        "pshape_concentration_threshold": pshape_concentration_threshold,
        "bshape_valley_threshold": bshape_valley_threshold,
        "normal_symmetry_threshold": normal_symmetry_threshold,
    }


class IndicatorSpec(BaseModel):
    """指標規範"""

    instrument_id: Optional[str] = Field(
        None, description="交易標的 ID（可選，用於多商品場景）"
    )
    freq: Union[Freq, str] = Field(..., description="頻率 (使用 Freq enum 或自訂字串)")
    shift: int = Field(1, description="位移（預設 1）")
    indicator: Dict[str, Any] = Field(
        ..., description="指標配置 (使用 indicator 工廠函數建立)"
    )

    def short_name(self) -> str:
        """生成指標簡短名稱（與 Rust 的 short_name 一致）

        格式範例:
        - SMA: "SMA|20.close"
        - EMA: "EMA|12.close"
        - ATR: "ATR|14"
        - SuperTrend: "ST|3.0x_atr"

        Returns:
            指標簡稱字符串

        Raises:
            ValueError: 未知的指標類型
        """
        indicator_type = self.indicator.get("type")

        if indicator_type == "SMA":
            period = self.indicator.get("period")
            column = self.indicator.get("column", "close")
            return f"SMA|{period}.{column}"

        elif indicator_type == "EMA":
            period = self.indicator.get("period")
            column = self.indicator.get("column", "close")
            return f"EMA|{period}.{column}"

        elif indicator_type == "SMMA":
            period = self.indicator.get("period")
            column = self.indicator.get("column", "close")
            return f"SMMA|{period}.{column}"

        elif indicator_type == "WMA":
            period = self.indicator.get("period")
            column = self.indicator.get("column", "close")
            return f"WMA|{period}.{column}"

        elif indicator_type == "ATR":
            period = self.indicator.get("period")
            # ATR 始終返回單一數值欄位，無 quantile
            return f"ATR|{period}"

        elif indicator_type == "AtrQuantile":
            atr_column = self.indicator.get("atr_column")
            window = self.indicator.get("window")
            quantile = self.indicator.get("quantile")
            # 將 quantile 轉為百分比（例如 0.5 -> 50）
            quantile_pct = int(quantile * 100)
            # 格式：ATRQ|{atr_column}_Q{quantile%}_{window}
            return f"ATRQ|{atr_column}_Q{quantile_pct}_{window}"

        elif indicator_type == "SuperTrend":
            multiplier = self.indicator.get("multiplier")
            volatility_column = self.indicator.get("volatility_column")
            return f"ST|{multiplier}x_{volatility_column}"

        elif indicator_type == "MarketProfile":
            # 提取 anchor_config 資訊
            anchor_config = self.indicator.get("anchor_config", {})
            end_rule = anchor_config.get("end_rule", {})
            lookback_days = anchor_config.get("lookback_days", 1)
            tick_size = self.indicator.get("tick_size")

            # 格式化時間字串（支持新舊兩種格式）
            rule_type = end_rule.get("type")

            if rule_type == "DailyTime" or "DailyTime" in end_rule:
                # 新格式: {"type": "DailyTime", "hour": 9, "minute": 15}
                # 舊格式: {"DailyTime": {"hour": 9, "minute": 15}}
                if rule_type == "DailyTime":
                    time_str = f"{end_rule['hour']:02d}{end_rule['minute']:02d}"
                else:
                    daily = end_rule["DailyTime"]
                    time_str = f"{daily['hour']:02d}{daily['minute']:02d}"

            elif rule_type == "WeeklyTime" or "WeeklyTime" in end_rule:
                # 新格式: {"type": "WeeklyTime", "weekday": "Mon", "hour": 9, "minute": 15}
                # 舊格式: {"WeeklyTime": {"weekday": 0, "hour": 9, "minute": 15}}
                if rule_type == "WeeklyTime":
                    weekday = end_rule["weekday"]
                    # weekday 可能是字串 ("Mon") 或整數 (0)
                    if isinstance(weekday, str):
                        # 字串格式: "Mon" -> "Mon"
                        weekday_str = weekday
                    else:
                        # 整數格式: 0 -> "Mon"
                        weekday_map = {
                            0: "Mon",
                            1: "Tue",
                            2: "Wed",
                            3: "Thu",
                            4: "Fri",
                            5: "Sat",
                            6: "Sun",
                        }
                        weekday_str = weekday_map.get(weekday, str(weekday))
                    time_str = (
                        f"W{weekday_str}_{end_rule['hour']:02d}{end_rule['minute']:02d}"
                    )
                else:
                    weekly = end_rule["WeeklyTime"]
                    weekday = weekly["weekday"]
                    if isinstance(weekday, str):
                        weekday_str = weekday
                    else:
                        weekday_map = {
                            0: "Mon",
                            1: "Tue",
                            2: "Wed",
                            3: "Thu",
                            4: "Fri",
                            5: "Sat",
                            6: "Sun",
                        }
                        weekday_str = weekday_map.get(weekday, str(weekday))
                    time_str = (
                        f"W{weekday_str}_{weekly['hour']:02d}{weekly['minute']:02d}"
                    )
            else:
                time_str = "UNKNOWN"

            # 格式: MP|{time}_{lookback_days}_{tick_size}
            # 注意：MarketProfile 不支持 indicator 層級的 shift
            return f"MP|{time_str}_{lookback_days}_{tick_size}"

        elif indicator_type == "CCI":
            period = self.indicator.get("period")
            return f"CCI|{period}"

        elif indicator_type == "RSI":
            period = self.indicator.get("period")
            return f"RSI|{period}"

        elif indicator_type == "BollingerBands":
            period = self.indicator.get("period")
            num_std = self.indicator.get("num_std")
            return f"BB|{period}_{num_std}"

        elif indicator_type == "MACD":
            fast_period = self.indicator.get("fast_period")
            slow_period = self.indicator.get("slow_period")
            signal_period = self.indicator.get("signal_period")
            return f"MACD|{fast_period}_{slow_period}_{signal_period}"

        elif indicator_type == "Stochastic":
            k_period = self.indicator.get("k_period")
            d_period = self.indicator.get("d_period")
            return f"STOCH|{k_period}_{d_period}"

        elif indicator_type == "ADX":
            period = self.indicator.get("period")
            return f"ADX|{period}"

        elif indicator_type == "RawOhlcv":
            # RawOhlcv 只返回 column 名稱
            column = self.indicator.get("column")
            return column

        else:
            raise ValueError(f"未知的指標類型: {indicator_type}")

    def display_name(self) -> str:
        """生成完整的 column 名稱（與 Rust 的 display_name 一致）

        格式:
        - 有 instrument_id: "{instrument_id}_{freq}_{indicator_short_name}[_s{shift}]"
        - 無 instrument_id: "{freq}_{indicator_short_name}[_s{shift}]"

        範例:
        - "ES_1min_SMA|20.close"      (shift=1，不顯示)
        - "1D_ATR|14_s2"               (shift=2)
        - "BTC_5min_EMA|12.close_s2"  (shift=2)
        - "1h_ST|3.0x_atr"            (無 instrument_id)

        Returns:
            完整的 column 名稱字符串
        """
        parts = []

        # 1. instrument_id（如果有）
        if self.instrument_id:
            parts.append(self.instrument_id)

        # 2. freq（處理 Freq enum）
        freq_str = self.freq.value if isinstance(self.freq, Freq) else self.freq
        parts.append(freq_str)

        # 3. indicator short name
        parts.append(self.short_name())

        # 4. shift（只在非預設值時加入）
        if self.shift != 1:
            parts.append(f"s{self.shift}")

        return "_".join(parts)

    def col(self) -> pl.Expr:
        """返回 Polars column expression（最常用的便捷方法）

        Returns:
            pl.col(display_name) 的 Polars 表達式

        Example:
            >>> spec = IndicatorSpec(
            ...     instrument_id="ES",
            ...     freq="1min",
            ...     shift=1,
            ...     indicator={"type": "SMA", "period": 20, "column": "close"}
            ... )
            >>> # 直接在條件中使用
            >>> condition = spec.col() > 100
            >>> # 或在過濾中使用
            >>> df.filter(spec.col() > pl.col("open"))
        """
        return pl.col(self.display_name())


class Trigger(BaseModel):
    """進出場觸發器

    使用方式：
    - 讀取：trigger.conditions 直接得到 List[pl.Expr]
    - 寫入：可直接賦值 pl.col("close") > 100
    """

    name: str = Field(..., description="觸發器名稱")
    order_strategy: Union[OrderStrategy, str] = Field(
        ..., description="訂單策略（OrderStrategy enum 或字串）"
    )
    priority: int = Field(..., description="優先級")
    note: Optional[str] = Field(None, description="備註")

    # 直接使用 pl.Expr 類型
    conditions: List[pl.Expr] = Field(..., description="條件列表（Polars Expr）")
    price_expr: pl.Expr = Field(..., description="價格表達式（Polars Expr）")

    @field_validator("conditions", mode="before")
    @classmethod
    def validate_conditions(cls, v: Any) -> List[pl.Expr]:
        """自動轉換 conditions 為 List[pl.Expr]"""
        if not v:
            return []

        result = []
        for item in v:
            result.append(PolarsExprField.deserialize(item))
        return result

    @field_validator("price_expr", mode="before")
    @classmethod
    def validate_price_expr(cls, v: Any) -> pl.Expr:
        """自動轉換 price_expr 為 pl.Expr"""
        return PolarsExprField.deserialize(v)

    @field_serializer("conditions")
    def serialize_conditions(self, conditions: List[pl.Expr]) -> List[dict]:
        """序列化 conditions 為 dict 列表（與服務器格式一致）"""
        return [PolarsExprField.serialize(expr) for expr in conditions]

    @field_serializer("price_expr")
    def serialize_price_expr(self, price_expr: pl.Expr) -> dict:
        """序列化 price_expr 為 dict（與服務器格式一致）"""
        return PolarsExprField.serialize(price_expr)

    class Config:
        # 允許 pl.Expr 這種自定義類型
        arbitrary_types_allowed = True


class Blueprint(BaseModel):
    """策略藍圖"""

    name: str = Field(..., description="藍圖名稱")
    direction: Literal["Long", "Short", "Both"] = Field(..., description="方向")
    trend_type: Literal["Trend", "Range", "Reversal"] = Field(
        ..., description="趨勢類型"
    )
    entry_first: bool = Field(..., description="是否優先進場")
    note: str = Field(..., description="備註")

    entry_triggers: List[Trigger] = Field(..., description="進場觸發器列表")
    exit_triggers: List[Trigger] = Field(..., description="出場觸發器列表")


class StrategyConfig(BaseModel):
    """完整策略配置"""

    name: str = Field(..., description="策略名稱")
    base_instrument: str = Field(..., description="基礎交易標的")
    base_freq: Freq = Field(..., description="基礎頻率")
    note: str = Field(..., description="備註")

    volatility_indicator: Optional[IndicatorSpec] = Field(
        None, description="波動率指標"
    )
    indicators: List[IndicatorSpec] = Field(
        default_factory=list, description="指標列表"
    )

    base_blueprint: Blueprint = Field(..., description="基礎藍圖")
    advanced_blueprints: List[Blueprint] = Field(
        default_factory=list, description="進階藍圖列表"
    )

    @classmethod
    def from_api(cls, api_response: Union[Dict[str, Any], str]) -> "StrategyConfig":
        """從 API 響應創建策略配置

        Args:
            api_response: API 返回的 JSON 數據（dict 或 JSON 字符串）

        Returns:
            StrategyConfig 實例，conditions 和 price_expr 自動轉為 pl.Expr

        Example:
            >>> # 從 JSON 字符串
            >>> strategy = StrategyConfig.from_api(json_str)
            >>> # 從 dict
            >>> strategy = StrategyConfig.from_api(response.json())
            >>> # 直接使用
            >>> expr = strategy.base_blueprint.entry_triggers[0].conditions[0]
            >>> print(type(expr))  # <class 'polars.expr.expr.Expr'>
        """
        if isinstance(api_response, str):
            return cls.model_validate_json(api_response)
        else:
            return cls.model_validate(api_response)

    def to_json(self, indent: int = 2) -> str:
        """序列化為 JSON 字符串

        自動將 pl.Expr 轉為 JSON 字符串格式

        Returns:
            JSON 字符串，conditions 和 price_expr 已序列化
        """
        return self.model_dump_json(indent=indent, exclude_none=True).replace("\n", "")

    def to_dict(self) -> Dict[str, Any]:
        """轉換為字典（用於發送到 API）

        Returns:
            字典，pl.Expr 已序列化為 JSON 字符串
        """
        return self.model_dump(exclude_none=True)

    def save(self, filepath: str) -> None:
        """保存到 JSON 文件"""
        with open(filepath, "w", encoding="utf-8") as f:
            f.write(self.to_json())
        print(f"✅ 策略已保存到: {filepath}")

    @classmethod
    def load(cls, filepath: str) -> "StrategyConfig":
        """從 JSON 文件加載"""
        with open(filepath, "r", encoding="utf-8") as f:
            return cls.from_api(f.read())


# 便捷函數
def parse_strategy(data: Union[Dict[str, Any], str]) -> StrategyConfig:
    """解析策略配置（最簡單的方式）

    Args:
        data: API JSON 數據（dict 或 JSON 字符串）

    Returns:
        StrategyConfig 實例，可直接訪問 pl.Expr

    Example:
        >>> import requests
        >>> # 從 API
        >>> response = requests.get("http://localhost:8080/api/v1/strategies/txf_1d_sma20_30")
        >>> strategy = parse_strategy(response.json())
        >>>
        >>> # 直接訪問 Polars Expr
        >>> conditions = strategy.base_blueprint.entry_triggers[0].conditions
        >>> print(type(conditions[0]))  # <class 'polars.expr.expr.Expr'>
        >>>
        >>> # 從 JSON 字符串
        >>> strategy = parse_strategy(json_str)
    """
    return StrategyConfig.from_api(data)


def create_indicator_spec(
    freq: Union[Freq, str],
    indicator: Dict[str, Any],
    instrument_id: Optional[str] = None,
    shift: int = 1,
) -> IndicatorSpec:
    """創建指標規範（簡化版工廠函數）

    使用 Indicator 靜態類創建 indicator dict，然後傳入此函數

    Args:
        freq: 頻率（使用 Freq enum 或字串）
        indicator: 指標配置（使用 Indicator 靜態類創建）
        instrument_id: 交易標的 ID（可選）
        shift: 位移（預設 1）

    Returns:
        IndicatorSpec 實例，可直接調用 .col() 獲取 Polars 表達式

    Examples:
        >>> from strategy_models import Freq, Indicator, create_indicator_spec
        >>>
        >>> # 方式 1: 使用 Freq enum + Indicator 靜態類
        >>> sma_20 = create_indicator_spec(
        ...     freq=Freq.MIN_1,
        ...     indicator=Indicator.sma(period=20),
        ...     instrument_id="ES"
        ... )
        >>> print(sma_20.display_name())  # "ES_1min_SMA|20.close"
        >>>
        >>> # 方式 2: 使用字串（向後兼容）
        >>> atr_14 = create_indicator_spec(
        ...     freq="1D",
        ...     indicator=Indicator.atr(period=14),
        ...     shift=2
        ... )
        >>> print(atr_14.display_name())  # "1D_ATR|14_s2"
        >>>
        >>> # 方式 3: SuperTrend
        >>> st = create_indicator_spec(
        ...     freq=Freq.MIN_5,
        ...     indicator=Indicator.supertrend(multiplier=3.0, volatility_column="atr"),
        ...     instrument_id="BTC"
        ... )
        >>> print(st.display_name())  # "BTC_5min_ST|3.0x_atr"
        >>>
        >>> # 在策略中使用（最簡潔的寫法）
        >>> sma_50 = create_indicator_spec(Freq.MIN_1, Indicator.sma(50), "ES")
        >>> conditions = [
        ...     sma_20.col() > sma_50.col(),
        ...     pl.col("volume") > 1000
        ... ]
    """
    return IndicatorSpec(
        instrument_id=instrument_id,
        freq=freq,
        shift=shift,
        indicator=indicator,
    )


def create_trigger(
    name: str,
    conditions: List[pl.Expr],
    price_expr: pl.Expr,
    order_strategy: Union[OrderStrategy, str] = OrderStrategy.IMMEDIATE_ENTRY,
    priority: int = 1,
    note: Optional[str] = None,
) -> Trigger:
    """創建觸發器（用於開發時）

    Args:
        name: 觸發器名稱
        conditions: 條件列表，可直接使用 pl.col() 等
        price_expr: 價格表達式
        order_strategy: 訂單策略（可使用 OrderStrategy enum 或字串，預設 OrderStrategy.IMMEDIATE_ENTRY）
        priority: 優先級
        note: 備註

    Returns:
        Trigger 實例

    Example:
        >>> # 使用 OrderStrategy enum（推薦）
        >>> entry = create_trigger(
        ...     name="my_entry",
        ...     conditions=[
        ...         pl.col("sma_30") > pl.col("sma_50"),
        ...         pl.col("volume") > 1000
        ...     ],
        ...     price_expr=pl.col("open"),
        ...     order_strategy=OrderStrategy.IMMEDIATE_ENTRY
        ... )
        >>>
        >>> # 或使用字串（向後兼容）
        >>> entry = create_trigger(
        ...     name="my_entry",
        ...     conditions=[...],
        ...     price_expr=pl.col("open"),
        ...     order_strategy="ImmediateEntry"
        ... )
        >>>
        >>> # 序列化為 JSON
        >>> print(entry.model_dump_json())
    """
    return Trigger(
        name=name,
        conditions=conditions,
        price_expr=price_expr,
        order_strategy=order_strategy,
        priority=priority,
        note=note,
    )


def create_blueprint(
    name: str,
    direction: Literal["Long", "Short", "Both"],
    entry_triggers: List[Trigger],
    exit_triggers: List[Trigger],
    trend_type: Literal["Trend", "Range", "Reversal"] = "Trend",
    entry_first: bool = True,
    note: str = "",
) -> Blueprint:
    """創建藍圖（用於開發時）

    Example:
        >>> entry_trigger = create_trigger(
        ...     name="entry",
        ...     conditions=[pl.col("sma_30") > pl.col("sma_50")],
        ...     price_expr=pl.col("open")
        ... )
        >>>
        >>> exit_trigger = create_trigger(
        ...     name="exit",
        ...     conditions=[pl.col("sma_30") < pl.col("sma_50")],
        ...     price_expr=pl.col("open"),
        ...     order_strategy="ImmediateExit"
        ... )
        >>>
        >>> blueprint = create_blueprint(
        ...     name="my_strategy",
        ...     direction="Long",
        ...     entry_triggers=[entry_trigger],
        ...     exit_triggers=[exit_trigger]
        ... )
    """
    return Blueprint(
        name=name,
        direction=direction,
        trend_type=trend_type,
        entry_first=entry_first,
        note=note,
        entry_triggers=entry_triggers,
        exit_triggers=exit_triggers,
    )


# ============================================================================
# Export API 數據模型（對應 Rust 的 Export API 響應）
# ============================================================================


class TaskStatus(str, Enum):
    """任務狀態枚舉（與 Rust TaskStatus enum 一致）

    對應 Rust 的 TaskStatus enum，用於追蹤 export 任務的執行狀態

    Rust 對應關係:
    - Rust: TaskStatus::Pending   → Python: TaskStatus.PENDING   (serde: "pending")
    - Rust: TaskStatus::Running   → Python: TaskStatus.RUNNING   (serde: "running")
    - Rust: TaskStatus::Completed → Python: TaskStatus.COMPLETED (serde: "completed")
    - Rust: TaskStatus::Failed    → Python: TaskStatus.FAILED    (serde: "failed")
    """

    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"


class ExportType(str, Enum):
    """導出類型枚舉（與 Rust ExportType enum 一致）

    對應 Rust 的 ExportType enum，定義支援的導出格式

    Rust 對應關係:
    - Rust: ExportType::BacktestResults → Python: ExportType.BACKTEST_RESULTS (serde: "backtest_results")
    - Rust: ExportType::LatestTrades    → Python: ExportType.LATEST_TRADES    (serde: "latest_trades")
    - Rust: ExportType::EnhancedOhlcv   → Python: ExportType.ENHANCED_OHLCV   (serde: "enhanced_ohlcv")
    - Rust: ExportType::OnDemandOhlcv   → Python: ExportType.ON_DEMAND_OHLCV  (serde: "on_demand_ohlcv")
    """

    BACKTEST_RESULTS = "backtest_results"
    LATEST_TRADES = "latest_trades"
    ENHANCED_OHLCV = "enhanced_ohlcv"
    ON_DEMAND_OHLCV = "on_demand_ohlcv"


class ResultSummary(BaseModel):
    """結果摘要（與 Rust ResultSummary struct 一致）

    對應 Rust 的 ResultSummary struct，提供任務完成後的統計摘要
    """

    total_trades: int = Field(..., description="交易記錄總數")
    total_strategies: int = Field(..., description="執行的策略數量")
    data_rows_count: Optional[int] = Field(
        None, description="數據行數（enhanced_ohlcv 使用）"
    )


class ExportTaskResponse(BaseModel):
    """導出任務響應（與 Rust ExportTaskResponse struct 一致）

    對應 Rust 的 ExportTaskResponse struct，包含完整的任務狀態和執行結果

    這是從 GET /api/v1/backtest/export/{task_id}/status 返回的主要響應對象

    Example:
        >>> response = client.get_export_status(task_id)
        >>> print(f"狀態: {response.status}")
        >>> print(f"任務 ID: {response.export_task_id}")
        >>> if response.status == TaskStatus.COMPLETED:
        ...     print(f"總交易數: {response.result_summary.total_trades}")
    """

    export_task_id: str = Field(..., description="任務 ID (UUID)")
    export_type: str = Field(..., description="導出類型")
    status: TaskStatus = Field(..., description="任務狀態")

    input: Dict[str, Any] = Field(..., description="輸入參數 (ExportRequest)")

    executed_strategies: List[str] = Field(
        default_factory=list, description="實際執行的策略列表"
    )

    result_summary: Optional[ResultSummary] = Field(
        None, description="結果摘要（完成後可用）"
    )

    redis_keys: Dict[str, str] = Field(
        default_factory=dict, description="Redis 鍵（完成後可用）"
    )

    created_at: str = Field(..., description="創建時間 (ISO 8601)")

    started_at: Optional[str] = Field(None, description="開始執行時間 (ISO 8601)")

    completed_at: Optional[str] = Field(None, description="完成時間 (ISO 8601)")

    error: Optional[str] = Field(None, description="錯誤信息")


class OnDemandOhlcvRequest(BaseModel):
    """On-Demand OHLCV 導出請求（與 Rust OnDemandOhlcvRequest struct 一致）

    特點：
    - 無需預先註冊策略
    - 直接指定指標規格即可導出
    - 適用於快速探索指標、外部數據分析

    Example:
        >>> from tradepose_client.models import create_indicator_spec, Indicator, Freq
        >>>
        >>> # 定義指標
        >>> sma_spec = create_indicator_spec(Freq.HOUR_1, Indicator.sma(20), shift=1)
        >>> atr_spec = create_indicator_spec(Freq.HOUR_1, Indicator.atr(14), shift=1)
        >>>
        >>> # 創建請求
        >>> request = OnDemandOhlcvRequest(
        ...     base_instrument="TXFR1",
        ...     base_freq="1min",
        ...     indicator_specs=[
        ...         sma_spec.model_dump(exclude_none=True),
        ...         atr_spec.model_dump(exclude_none=True)
        ...     ],
        ...     start_date="2025-01-01T00:00:00",
        ...     end_date="2025-01-02T23:59:59"
        ... )
    """

    base_instrument: str = Field(
        ..., description="基礎商品 ID (例如 'TXFR1', 'TXF_M1_SHIOAJI_FUTURE')"
    )
    base_freq: str = Field(
        ..., description="基礎頻率 ('1min', '5min', '15min', '1h', '4h', '1D' 等)"
    )
    indicator_specs: List[Dict[str, Any]] = Field(
        ..., description="指標規格列表 (IndicatorSpec JSON 數組)", min_length=1
    )
    start_date: Optional[str] = Field(
        None, description="開始時間 (ISO 8601 格式，例如 '2025-01-01T00:00:00')"
    )
    end_date: Optional[str] = Field(
        None, description="結束時間 (ISO 8601 格式，預設為當前時間)"
    )
