# plugin.py from typing import Callable, List, Dict from abc import ABC, abstractmethod from core_types import PluginConfig, AppointmentType, QueryResult, BookResult, PluginStatus # ================== 接口类 ================== class IPlugin(ABC): """ @brief 签证 API 接口类 该接口定义了签证系统的基本操作,包括配置、会话管理、查询、预订、 健康检查以及错误处理等。所有具体的签证 API 实现都需要继承该接口。 """ name: str = "" version: str = "1.0.0" description: str = "" @classmethod def get_plugin_info(cls) -> Dict[str, str]: """ @brief 获取插件静态元数据信息 """ return { "name": cls.name or cls.__name__, "version": cls.version, "description": cls.description, } @abstractmethod def set_config(self, config: PluginConfig): """ @brief 设置 API 的配置信息 @param config 签证 API 配置对象 """ pass @abstractmethod def set_log(self, logger: Callable[[str], None]) -> None: """ @brief 设置日志输出工具, 该函数不允许抛异常 """ pass @abstractmethod def create_session(self) -> None: """ @brief 创建一个新的会话, 抛异常则创建失败 """ pass @abstractmethod def query(self, apt_type: AppointmentType) -> QueryResult: """ @brief 查询可用的签证预约信息, 抛异常则查询失败 @return QueryResult 查询结果 """ pass @abstractmethod def book(self, slot_info: QueryResult, user_inputs) -> BookResult: """ @brief 进行预约操作, 抛异常则预定失败 @param slot_info 查询得到的可用时段信息 @param user_inputs 用户输入的预约信息 @return BookResult 预约结果 """ pass @abstractmethod def keep_alive(self): """ @brief 会话保活, 如果会定时调用query则不需要调用该函数, 该函数不允许抛异常 """ pass @abstractmethod def health_check(self) -> bool: """ @brief 健康检查,用于检测 API 服务是否正常, 该函数不允许抛异常 @return true 表示健康状态良好,false 表示存在问题 """ pass @abstractmethod def cleanup(self) -> None: """ @brief 清理实例使用的资源 """ pass def get_plugin_status(self) -> PluginStatus: """ @brief 获取插件实例当前的运行状态快照(默认返回基础状态,插件按需重写) @return PluginStatus """ return PluginStatus()