# cycle_models.py

from abc import ABC, abstractmethod
from typing import Dict, Any, List

class CycleModel(ABC):
    """
    周期模型抽象基类 (Abstract Base Class)。

    定义了所有市场周期、板块轮动或生命周期模型的统一接口。
    确保上层应用（如FSM）可以调用周期分析功能，而无需关心其具体实现
    （例如，是十二长生、二十四节气还是美林投资时钟）。
    """

    @abstractmethod
    def get_current_stage(self, data: Dict[str, Any]) -> str:
        """
        根据输入数据，判断当前处于哪个周期阶段。
        :param data: 包含用于分析的数据的字典 (e.g., economic indicators, price momentum).
        :return: 当前周期阶段的名称。
        """
        pass

    @abstractmethod
    def get_stage_characteristics(self, stage: str) -> Dict[str, Any]:
        """
        获取特定阶段的特征描述或建议策略。
        :param stage: 阶段名称。
        :return: 包含该阶段特征描述的字典。
        """
        pass

    @abstractmethod
    def get_all_stages(self) -> List[str]:
        """
        返回模型中所有阶段的有序列表。
        :return: 包含所有阶段名称的列表。
        """
        pass


class TwelveStagesOfLifeCycleModel(CycleModel):
    """
    十二长生周期模型的具体实现。

    该模型将事物的生命周期分为十二个阶段，用于描述板块轮动或个股的生命周期。
    """

    def __init__(self):
        self._stages = [
            "长生", "沐浴", "冠带", "临官", "帝旺",
            "衰", "病", "死", "墓", "绝", "胎", "养"
        ]
        self._characteristics = {
            "长生": {"description": "新生，事物初生，潜力巨大。", "strategy": "关注，少量试探"},
            "沐浴": {"description": "萌芽，成长初期，易受挫折。", "strategy": "谨慎观察，识别风险"},
            "冠带": {"description": "成型，初步获得社会承认。", "strategy": "逐步建仓"},
            "临官": {"description": "高速增长，事业有成。", "strategy": "持有并加仓"},
            "帝旺": {"description": "顶峰，达到全盛时期。", "strategy": "警惕风险，考虑减仓"},
            "衰":   {"description": "衰退，开始走下坡路。", "strategy": "逐步卖出"},
            "病":   {"description": "问题暴露，盈利能力减弱。", "strategy": "清仓"},
            "死":   {"description": "明显下滑，失去活力。", "strategy": "避免接触"},
            "墓":   {"description": "估值塌陷，被市场遗忘。", "strategy": "观望，等待转机"},
            "绝":   {"description": "市场失忆，完全被忽视。", "strategy": "观望"},
            "胎":   {"description": "潜伏，新一轮周期的孕育。", "strategy": "研究，寻找新催化剂"},
            "养":   {"description": "建仓期，主力资金开始布局。", "strategy": "少量布局，等待信号"}
        }

    def get_current_stage(self, data: Dict[str, Any]) -> str:
        """
        模拟根据市场数据判断当前所处的“十二长生”阶段。
        在真实实现中，这里会是一个复杂的量化模型。
        """
        # 模拟逻辑：简单地根据一个随机分数来确定阶段
        # score 范围 0-11
        mock_score = data.get("mock_score", 0)
        stage_index = int(mock_score) % len(self._stages)
        return self._stages[stage_index]

    def get_stage_characteristics(self, stage: str) -> Dict[str, Any]:
        """
        获取指定“十二长生”阶段的特征和策略建议。
        """
        return self._characteristics.get(stage, {"description": "未知阶段", "strategy": "无"})

    def get_all_stages(self) -> List[str]:
        """
        返回所有十二长生阶段。
        """
        return self._stages

# --- 示例：如何使用解耦的周期模型 ---
if __name__ == '__main__':
    import random

    # 上层应用（如FSM）依赖于抽象的 CycleModel
    def analyze_market_cycle(model: CycleModel, market_data: Dict[str, Any]):
        current_stage = model.get_current_stage(market_data)
        characteristics = model.get_stage_characteristics(current_stage)
        
        print(f"当前市场周期分析 (模型: {model.__class__.__name__}):")
        print(f"  - 所处阶段: 【{current_stage}】")
        print(f"  - 阶段描述: {characteristics['description']}")
        print(f"  - 建议策略: {characteristics['strategy']}")

    # 运行时，传入一个具体的周期模型实例
    twelve_stages_model = TwelveStagesOfLifeCycleModel()

    # 模拟不同的市场数据
    for i in range(3):
        # 在真实场景中，这里会是真实的经济或市场数据
        simulated_market_data = {"mock_score": random.randint(0, 11)}
        analyze_market_cycle(twelve_stages_model, simulated_market_data)
        print("-" * 50)

    # 如果未来要添加“美林投资时钟”模型，只需实现一个新的类，
    # 上层应用 analyze_market_cycle 的代码完全不需要修改。
    # class MerrillClockModel(CycleModel):
    #     ...
    # merrill_model = MerrillClockModel()
    # analyze_market_cycle(merrill_model, real_economic_data)