wy 注释accounts/admin.py

accounts/admin.py

@@ -4,57 +4,98 @@ from django.contrib.auth.forms import UserChangeForm
 from django.contrib.auth.forms import UsernameField
 from django.utils.translation import gettext_lazy as _
 
-# Register your models here.
+# 模块级注释——accounts应用的Admin后台表单配置文件，
+# 自定义BlogUser（自定义用户模型）的创建表单、修改表单，以及Admin后台管理配置，
+# 适配Django Admin的用户管理逻辑，支持自定义字段（如nickname、source）的后台操作
 from .models import BlogUser
 
 
 class BlogUserCreationForm(forms.ModelForm):
+    """
+    自定义用户创建表单（用于Django Admin后台添加新用户）
+    扩展默认表单，增加密码二次验证逻辑，适配BlogUser模型的字段要求
+    """
+    # 密码输入字段：label支持国际化，使用密码输入控件（隐藏输入内容）
     password1 = forms.CharField(label=_('password'), widget=forms.PasswordInput)
+    # 密码二次确认字段：用于验证两次输入密码一致
     password2 = forms.CharField(label=_('Enter password again'), widget=forms.PasswordInput)
 
     class Meta:
-        model = BlogUser
-        fields = ('email',)
+        model = BlogUser  # 关联的模型：accounts应用的BlogUser（自定义用户模型）
+        fields = ('email',)  # 后台创建用户时，必填的核心字段（仅邮箱，用户名可后续补充或自动生成）
 
     def clean_password2(self):
-        # Check that the two password entries match
+        """
+        密码二次验证的清洁方法（Django表单验证机制）
+        检查两次输入的密码是否一致，不一致则抛出验证错误
+        """
+        # 获取第一次和第二次输入的密码（已通过表单基础验证的清洁数据）
         password1 = self.cleaned_data.get("password1")
         password2 = self.cleaned_data.get("password2")
+        # 若两次密码均存在且不一致，抛出验证错误（错误信息支持国际化）
         if password1 and password2 and password1 != password2:
             raise forms.ValidationError(_("passwords do not match"))
+        # 验证通过，返回第二次输入的密码（用于后续保存）
         return password2
 
     def save(self, commit=True):
-        # Save the provided password in hashed format
+        """
+        重写保存方法，实现密码哈希存储和创建来源标记
+        Django默认会对密码进行哈希处理，此处明确调用set_password确保安全性
+        """
+        # 调用父类save方法，先不提交到数据库（commit=False）
         user = super().save(commit=False)
+        # 对密码进行哈希处理后存储（避免明文存储，符合Django安全规范）
         user.set_password(self.cleaned_data["password1"])
+        # 若需要提交到数据库（默认commit=True）
         if commit:
-            user.source = 'adminsite'
-            user.save()
+            user.source = 'adminsite'  # 标记用户创建来源：Django Admin后台
+            user.save()  # 最终保存用户数据到数据库
         return user
 
 
 class BlogUserChangeForm(UserChangeForm):
+    """
+    自定义用户修改表单（用于Django Admin后台编辑用户信息）
+    继承Django内置UserChangeForm，适配BlogUser模型的所有字段
+    """
     class Meta:
-        model = BlogUser
-        fields = '__all__'
-        field_classes = {'username': UsernameField}
+        model = BlogUser  # 关联的模型：accounts应用的BlogUser
+        fields = '__all__'  # 后台可修改的字段：所有模型字段（支持自定义扩展字段）
+        field_classes = {'username': UsernameField}  # 用户名字段的类：使用Django内置UsernameField（确保符合用户名验证规则）
 
     def __init__(self, *args, **kwargs):
+        """
+        初始化表单，调用父类构造方法保持默认逻辑
+        若后续需要扩展表单初始化行为（如隐藏字段、设置默认值），可在此方法中添加
+        """
         super().__init__(*args, **kwargs)
 
 
 class BlogUserAdmin(UserAdmin):
-    form = BlogUserChangeForm
-    add_form = BlogUserCreationForm
+    """
+    自定义UserAdmin配置（用于Django Admin后台管理BlogUser模型）
+    配置后台显示字段、排序规则、搜索字段等，优化用户管理体验
+    """
+    form = BlogUserChangeForm  # 关联用户修改表单：使用自定义的BlogUserChangeForm
+    add_form = BlogUserCreationForm  # 关联用户创建表单：使用自定义的BlogUserCreationForm
+
+    # 后台列表页显示的字段（按业务优先级排序）
     list_display = (
-        'id',
-        'nickname',
-        'username',
-        'email',
-        'last_login',
-        'date_joined',
-        'source')
+        'id',  # 用户ID（唯一标识）
+        'nickname',  # 用户昵称（自定义扩展字段）
+        'username',  # 用户名（Django用户模型核心字段）
+        'email',  # 邮箱（用于登录和通知，核心字段）
+        'last_login',  # 最后登录时间（安全审计字段）
+        'date_joined',  # 注册时间（业务统计字段）
+        'source'  # 创建来源（区分后台创建/前台注册等，自定义扩展字段）
+    )
+
+    # 后台列表页可点击跳转的字段（用于快速进入编辑页）
     list_display_links = ('id', 'username')
+
+    # 后台列表页默认排序规则：按ID倒序（新创建的用户排在前面）
     ordering = ('-id',)
-    search_fields = ('username', 'nickname', 'email')
+
+    # 后台搜索支持的字段（支持模糊查询，提升管理效率）
+    search_fields = ('username', 'nickname', 'email')