模块接口规格 · Contracts

from abc import ABC, abstractmethod
from .types import TrendResult

class TrendModule(ABC):
    
    def configure(self, params: dict) -> None:
        """接收来自 SystemConfig 的参数字典，算法自行解析所需字段。"""
        pass
    
    @abstractmethod
    def analyze(self, klines: list[dict], symbol: str, timeframe: str) -> TrendResult | None:
        """
        分析 K 线序列，返回趋势判断结果。
        返回 None 或 direction=="ranging" 时，流水线短路。
        
        Args:
            klines: K 线列表，每条格式 {time, open, high, low, close, volume}
            symbol: 交易对
            timeframe: 时间周期
        """
        ...
    
    @property
    @abstractmethod
    def name(self) -> str:
        """算法注册名称，与方法注册表中的 key 一致。"""
        ...

from abc import ABC, abstractmethod
from .types import KeyLevel

class KeyLevelModule(ABC):
    
    def configure(self, params: dict) -> None:
        pass
    
    @abstractmethod
    def identify(self, klines: list[dict], symbol: str, timeframe: str) -> list[KeyLevel]:
        """
        识别关键价位区间列表。
        返回空列表 [] 时，流水线短路。
        
        返回的每个 KeyLevel 必须包含 zone_low 和 zone_high（区间，非单条线）。
        """
        ...
    
    @property
    @abstractmethod
    def name(self) -> str: ...

from abc import ABC, abstractmethod
from .types import TrendResult, KeyLevel, SignalResult

class SignalModule(ABC):
    
    def configure(self, params: dict) -> None:
        pass
    
    @abstractmethod
    def detect(
        self,
        klines: list[dict],
        trend: TrendResult,
        key_levels: list[KeyLevel],
        symbol: str,
    ) -> SignalResult | None:
        """
        在给定趋势和关键位上下文中检测入场信号。
        返回 None 时，流水线短路。
        
        Args:
            klines: K 线序列（最新一根为当前 K 线收盘）
            trend: M1 输出的趋势判断
            key_levels: M2 输出的关键位列表
        """
        ...
    
    @property
    @abstractmethod
    def name(self) -> str: ...

from abc import ABC, abstractmethod
from .types import SignalResult, TradePlan

class PlanModule(ABC):
    
    def configure(self, params: dict) -> None:
        pass
    
    @abstractmethod
    def generate(
        self,
        signal: SignalResult,
        account_balance: float,
        min_rr_ratio: float,
    ) -> TradePlan | None:
        """
        根据入场信号生成完整交易计划。
        rr_ratio < min_rr_ratio 时返回 None（短路）。
        
        Args:
            signal: M3 输出的入场信号
            account_balance: 当前账户余额（USDT），用于仓位计算
            min_rr_ratio: 最小盈亏比阈值，来自 SystemConfig
        """
        ...
    
    @property
    @abstractmethod
    def name(self) -> str: ...