vs_plg.py 2.8 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. # vs_plg.py
  2. from typing import Callable, List, Dict
  3. from abc import ABC, abstractmethod
  4. from vs_types import VSPlgConfig, AppointmentType, VSQueryResult, VSBookResult, PluginStatus
  5. # ================== 接口类 ==================
  6. class IVSPlg(ABC):
  7. """
  8. @brief 签证 API 接口类
  9. 该接口定义了签证系统的基本操作,包括配置、会话管理、查询、预订、
  10. 健康检查以及错误处理等。所有具体的签证 API 实现都需要继承该接口。
  11. """
  12. name: str = ""
  13. version: str = "1.0.0"
  14. description: str = ""
  15. @classmethod
  16. def get_plugin_info(cls) -> Dict[str, str]:
  17. """
  18. @brief 获取插件静态元数据信息
  19. """
  20. return {
  21. "name": cls.name or cls.__name__,
  22. "version": cls.version,
  23. "description": cls.description,
  24. }
  25. @abstractmethod
  26. def set_config(self, config: VSPlgConfig):
  27. """
  28. @brief 设置 API 的配置信息
  29. @param config 签证 API 配置对象
  30. """
  31. pass
  32. @abstractmethod
  33. def set_log(self, logger: Callable[[str], None]) -> None:
  34. """
  35. @brief 设置日志输出工具, 该函数不允许抛异常
  36. """
  37. pass
  38. @abstractmethod
  39. def create_session(self) -> None:
  40. """
  41. @brief 创建一个新的会话, 抛异常则创建失败
  42. """
  43. pass
  44. @abstractmethod
  45. def query(self, apt_type: AppointmentType) -> VSQueryResult:
  46. """
  47. @brief 查询可用的签证预约信息, 抛异常则查询失败
  48. @return VSQueryResult 查询结果
  49. """
  50. pass
  51. @abstractmethod
  52. def book(self, slot_info: VSQueryResult, user_inputs) -> VSBookResult:
  53. """
  54. @brief 进行预约操作, 抛异常则预定失败
  55. @param slot_info 查询得到的可用时段信息
  56. @param user_inputs 用户输入的预约信息
  57. @return VSBookResult 预约结果
  58. """
  59. pass
  60. @abstractmethod
  61. def keep_alive(self):
  62. """
  63. @brief 会话保活, 如果会定时调用query则不需要调用该函数, 该函数不允许抛异常
  64. """
  65. pass
  66. @abstractmethod
  67. def health_check(self) -> bool:
  68. """
  69. @brief 健康检查,用于检测 API 服务是否正常, 该函数不允许抛异常
  70. @return true 表示健康状态良好,false 表示存在问题
  71. """
  72. pass
  73. @abstractmethod
  74. def cleanup(self) -> None:
  75. """
  76. @brief 清理实例使用的资源
  77. """
  78. pass
  79. def get_plugin_status(self) -> PluginStatus:
  80. """
  81. @brief 获取插件实例当前的运行状态快照(默认返回基础状态,插件按需重写)
  82. @return PluginStatus
  83. """
  84. return PluginStatus()