#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
总线通信模块的抽象接口定义 (契约)

此接口定义了面向业务操作的方法，将所有实现细节（包括解析）完全封装。
"""

from abc import ABC, abstractmethod

class IBusManager(ABC):
    """
    总线管理器接口。
    调用方只关心业务，不关心实现。
    """

    @abstractmethod
    def execute_raw_command(self, bus_id: int, command: bytes) -> None:
        """
        【契约】执行一个“发后不理”的原始指令。
        
        Args:
            bus_id (int): 目标总线的编号。
            command (bytes): 要发送的原始命令字节。
        """
        pass

    @abstractmethod
    def execute_collect_task(self, task: dict) -> float | None:
        """
        【契约】执行一个完整的采集任务，并直接返回最终的数值。

        一个符合本接口的实现必须自己处理所有细节：
        - 从task字典中解析出 bus_id, command, parser_type。
        - 发送指令。
        - 接收响应。
        - 根据parser_type选择正确的内部解析器进行解析。
        - 返回最终的float数值，或在任何失败情况下返回None。

        Args:
            task (dict): 从Protobuf解码出的单个CollectTask消息字典。

        Returns:
            float | None: 成功解析则返回数值，否则返回None。
        """
        pass