tradepose-client 0.1.0__py3-none-any.whl

tradepose_client/models.py

@@ -0,0 +1,1836 @@
+"""
+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 格式，預設為當前時間)"
+    )