# 导入必要的模块
# os: 用于处理文件路径和目录操作
# logging: 用于记录插件加载过程中的日志信息（成功/失败状态）
# django.conf.settings: 用于获取Django项目的配置信息（如插件目录、激活的插件列表）
import os
import logging
from django.conf import settings

# 创建当前模块的日志记录器，日志名称与模块绑定，便于追踪插件加载相关的日志
logger = logging.getLogger(__name__)


def load_plugins():
    """
    动态加载并初始化位于'plugins'目录中的插件
    
    功能说明：
    - 从Django配置中读取激活的插件列表（settings.ACTIVE_PLUGINS）
    - 检查每个插件的目录结构是否合法（是否存在plugin.py文件）
    - 动态导入插件的核心模块（plugin.py），触发插件的初始化流程
    - 通过日志记录每个插件的加载结果（成功/失败及原因）
    
    调用时机：
    该函数应在Django应用注册表（app registry）准备就绪后调用，
    通常在项目启动时（如通过AppConfig.ready()方法触发），确保Django环境已初始化完成。
    """
    # 遍历配置中激活的所有插件名称（settings.ACTIVE_PLUGINS是一个插件名称列表）
    for plugin_name in settings.ACTIVE_PLUGINS:
        # 构建插件的完整目录路径：
        # settings.PLUGINS_DIR是项目中存放所有插件的根目录（如"project_root/plugins"）
        # 拼接根目录与当前插件名称，得到具体插件的目录路径（如"project_root/plugins/my_plugin"）
        plugin_path = os.path.join(settings.PLUGINS_DIR, plugin_name)
        
        # 验证插件目录的合法性：
        # 1. 必须是一个存在的目录（os.path.isdir(plugin_path)）
        # 2. 目录中必须包含核心文件plugin.py（插件的入口模块）
        if os.path.isdir(plugin_path) and os.path.exists(os.path.join(plugin_path, 'plugin.py')):
            try:
                # 动态导入插件的plugin.py模块：
                # 导入路径格式为"plugins.{插件名称}.plugin"（基于Python包结构）
                # 导入后会自动执行plugin.py中的顶级代码（如插件类的定义和注册逻辑）
                __import__(f'plugins.{plugin_name}.plugin')
                
                # 记录INFO级日志，提示插件加载成功
                logger.info(f"Successfully loaded plugin: {plugin_name}")
            
            # 捕获导入过程中的异常（如模块不存在、语法错误、依赖缺失等）
            except ImportError as e:
                # 记录ERROR级日志，提示插件导入失败，并附带异常信息
                # exc_info=e 会将异常堆栈信息写入日志，便于排查问题
                logger.error(f"Failed to import plugin: {plugin_name}", exc_info=e)