import os
import logging
from django.conf import settings

# 获取当前模块的日志记录器，用于输出插件加载过程中的日志信息（如成功或失败记录）
logger = logging.getLogger(__name__)


def load_plugins():
    """
    动态加载并初始化插件。

    功能说明：
    该函数用于在 Django 项目启动时，自动发现并加载配置在 `settings.ACTIVE_PLUGINS` 中的插件。
    它会检查每个插件是否存在于指定的插件目录中，并确认其包含入口文件 `plugin.py`。
    如果条件满足，则导入该插件模块，从而执行其内部的初始化代码（如注册信号、钩子、视图、中间件等）。

    调用时机：
    通常在 Django 的 `AppConfig.ready()` 方法中调用此函数，以确保 Django 的应用注册系统已完全就绪，
    避免因过早导入而导致的依赖问题或模型未加载异常。

    执行逻辑：
    1. 遍历 settings 中定义的活跃插件列表（ACTIVE_PLUGINS）。
    2. 对每个插件，构造其在文件系统中的路径。
    3. 判断该路径是否为一个目录，且包含名为 'plugin.py' 的文件（插件入口）。
    4. 若满足条件，则使用 __import__ 动态导入该模块。
    5. 成功导入后记录一条 info 级别的日志；若导入失败，则捕获 ImportError 异常并记录错误日志。

    注意事项：
    - 此函数不返回任何值，也不对插件进行实例化，仅通过导入模块来触发其副作用（如注册行为）。
    - 插件必须遵循目录结构规范：`plugins/<插件名>/plugin.py`。
    - 错误日志中包含异常堆栈（exc_info=True），便于调试和排查插件加载失败原因。
    """
    # 遍历 settings 中配置的已激活插件名称列表
    for plugin_name in settings.ACTIVE_PLUGINS:
        # 构建当前插件的完整文件路径
        plugin_path = os.path.join(settings.PLUGINS_DIR, plugin_name)
        # 检查该插件路径是否为有效目录，且包含 plugin.py 入口文件
        if os.path.isdir(plugin_path) and os.path.exists(os.path.join(plugin_path, 'plugin.py')):
            try:
                # 动态导入插件模块，触发其初始化逻辑
                __import__(f'plugins.{plugin_name}.plugin')
                # 记录插件加载成功的日志
                logger.info(f"Successfully loaded plugin: {plugin_name}")
            except ImportError as e:
                # 记录插件加载失败的错误日志，并包含完整的异常堆栈信息
                logger.error(f"Failed to import plugin: {plugin_name}", exc_info=e)