# 导入 Django 管理后台模块
from django.contrib import admin

# 导入 reverse 函数，用于反向解析 URL（根据命名 URL 生成实际路径）
from django.urls import reverse

# 导入 format_html，用于安全地格式化 HTML 字符串（防止 XSS）
from django.utils.html import format_html

# 导入 gettext_lazy 作为 _，用于字符串国际化（延迟翻译）
from django.utils.translation import gettext_lazy as _


# 自定义管理员操作：批量禁用选中的评论
def disable_commentstatus(modeladmin, request, queryset):
    """
    将选中的评论设置为“不启用”状态（即不显示）
    此函数将在评论管理界面作为批量操作使用
    """
    # 批量更新：将 queryset 中所有评论的 is_enable 字段设为 False
    queryset.update(is_enable=False)


# 自定义管理员操作：批量启用选中的评论
def enable_commentstatus(modeladmin, request, queryset):
    """
    将选中的评论设置为“启用”状态（即显示）
    此函数将在评论管理界面作为批量操作使用
    """
    # 批量更新：将 queryset 中所有评论的 is_enable 字段设为 True
    queryset.update(is_enable=True)


# 为自定义操作设置在管理界面中显示的描述文本（支持国际化）
disable_commentstatus.short_description = _('Disable comments')  # 显示为“禁用评论”
enable_commentstatus.short_description = _('Enable comments')    # 显示为“启用评论”


# 定义 Comment 模型在 Django 管理后台的显示和操作配置
class CommentAdmin(admin.ModelAdmin):
    # 设置评论列表每页显示 20 条数据
    list_per_page = 20

    # 定义在评论列表页面显示的字段列
    list_display = (
        'id',               # 评论的数据库 ID
        'body',             # 评论正文内容
        'link_to_userinfo', # 自定义方法：显示作者信息（带链接）
        'link_to_article',  # 自定义方法：显示所属文章（带链接）
        'is_enable',        # 是否启用（布尔值，显示为开关）
        'creation_time'     # 评论创建时间
    )

    # 设置哪些字段可以点击，跳转到该评论的编辑页面
    list_display_links = ('id', 'body', 'is_enable')

    # 添加右侧过滤侧边栏，允许按 is_enable 字段（是否启用）筛选评论
    list_filter = ('is_enable',)

    # 在添加或编辑评论时，从表单中排除这两个字段
    # 因为 creation_time 和 last_modify_time 通常由代码自动处理（如默认值或保存时更新）
    exclude = ('creation_time', 'last_modify_time')

    # 注册自定义的批量操作，允许管理员在列表页选择多条评论执行“启用”或“禁用”
    actions = [disable_commentstatus, enable_commentstatus]

    def link_to_userinfo(self, obj):
        """
        自定义列表字段：生成指向评论作者用户信息编辑页面的超链接

        参数：
            obj: 当前评论对象

        返回：
            HTML 格式的链接，链接文本为用户的昵称（若有），否则为邮箱
        """
        # 获取作者用户模型的 app_label 和 model_name（如 'auth', 'user'）
        info = (obj.author._meta.app_label, obj.author._meta.model_name)
        # 使用 reverse 构造 Django 管理后台中该用户的编辑页面 URL
        link = reverse('admin:%s_%s_change' % info, args=(obj.author.id,))
        # 返回一个安全的 HTML 链接
        return format_html(
            u'<a href="%s">%s</a>' %
            (link, obj.author.nickname if obj.author.nickname else obj.author.email))

    def link_to_article(self, obj):
        """
        自定义列表字段：生成指向评论所属文章编辑页面的超链接

        参数：
            obj: 当前评论对象

        返回：
            HTML 格式的链接，链接文本为文章标题
        """
        # 获取文章模型的 app_label 和 model_name（如 'blog', 'article'）
        info = (obj.article._meta.app_label, obj.article._meta.model_name)
        # 构造该文章在管理后台的编辑页面 URL
        link = reverse('admin:%s_%s_change' % info, args=(obj.article.id,))
        # 返回一个安全的 HTML 链接
        return format_html(
            u'<a href="%s">%s</a>' % (link, obj.article.title))

    # 为自定义的列表字段设置列标题（支持国际化）
    link_to_userinfo.short_description = _('User')      # 列标题显示为“用户”
    link_to_article.short_description = _('Article')   # 列标题显示为“文章”