coordinate/vs_plg.py

# vs_plg.py
from typing import Callable
from abc import ABC, abstractmethod
from vs_types import VSPlgConfig, VSQueryResult, VSBookResult

# ================== 接口类 ==================
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) -> None:
        """
        @brief 创建一个新的会话, 抛异常则创建失败
        """
        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 set_log(self, logger: Callable[[str], None]) -> None:
        """
        @brief 设置日志输出工具
        """
        pass