coordinate/vs_plg.py

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

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

    @abstractmethod
    def create_session(self) -> None:
        """
        @brief 创建一个新的会话, 抛异常则创建失败
        """
        pass

    @abstractmethod
    def query(self, apt_type: AppointmentType) -> 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 keep_alive(self):
        """
        @brief 会话保活, 该函数不允许抛异常
        """
        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