coordinate/vs_plg.py

# vs_plg.py
from abc import ABC, abstractmethod
from vs_types import VSPlgConfig, VSQueryResult, VSBookResult # type: ignore

# 错误类型模拟，Python中通常直接抛异常
class VSError:
    def __init__(self, code: int, message: str):
        self.error_code = code
        self.error_message = message

    def __str__(self):
        return f"Error {self.error_code}: {self.error_message}"

# ================== 接口类 ==================
class IVSPlg(ABC):
    """
    @brief 签证 API 接口类
    该接口定义了签证系统的基本操作，包括配置、会话管理、查询、预订、
    健康检查以及错误处理等。所有具体的签证 API 实现都需要继承该接口。
    """
    
    @abstractmethod
    def set_config(self, config: VSPlgConfig):
        """
        @brief 设置 API 的配置信息
        @param config 签证 API 配置对象
        """
        pass

    # set_log_callback 在Python中通常通过配置logging模块或注入logger实例实现
    # 这里为了简化，不显式提供，直接使用全局logging

    @abstractmethod
    def create_session(self) -> bool:
        """
        @brief 创建一个新的会话
        @return true 表示会话创建成功，false 表示失败
        """
        pass

    @abstractmethod
    def query(self) -> VSQueryResult:
        """
        @brief 查询可用的签证预约信息
        @return VSQueryResult 查询结果
        """
        pass

    @abstractmethod
    def book(self, slot_info: VSQueryResult, user_inputs) -> VSBookResult:
        """
        @brief 进行预约操作
        @param slot_info 查询得到的可用时段信息
        @param user_inputs 用户输入的预约信息
        @return VSBookResult 预约结果
        """
        pass

    @abstractmethod
    def get_group_id(self) -> str:
        """
        @brief 获取当前 API 实例所属的分组 ID
        @return 分组 ID 字符串
        """
        pass

    @abstractmethod
    def health_check(self) -> bool:
        """
        @brief 健康检查，用于检测 API 服务是否正常
        @return true 表示健康状态良好，false 表示存在问题
        """
        pass

    @abstractmethod
    def get_last_error(self) -> VSError:
        """
        @brief 获取最近一次操作的错误信息
        @return 错误对象（VSError）
        """
        pass

# Python中不需要显式地C接口导出，动态加载模块通常通过importlib或直接import完成
# CreatePlg 函数逻辑将在 VSPlgFactory 中实现