优化更新

DjangoAdmin_Django_EleVue/zh/volume2/model.md

@@ -17,6 +17,10 @@ from application.models import BaseModel
 from utils.common import get_table_name
 
 
+# =============================================================
+# 案例模型类
+# =============================================================
+
 class Example(BaseModel):
     """
     案例模型类
@@ -29,29 +33,53 @@ class Example(BaseModel):
     - create_time: 创建时间
     - update_user: 更新人
     - update_time: 更新时间
+
+    主要业务字段：
+    - name: 案例名称
+    - avatar: 案例图片
+    - type: 案例类型
+    - status: 案例状态（1-正常, 2-禁用）
+    - sort: 排序权重（数值越小越靠前）
     """
 
+    # ----------------------------------------------------------
     # 案例名称
+    # ----------------------------------------------------------
+    # 字段说明: 案例的名称
+    # 字段类型: 字符串（CharField）
+    # 约束: 非空（null=False），最大长度100字符
+    # 索引: 添加了数据库索引（db_index=True）以提升查询效率
+    # 作用: 案例的核心标识字段，用于列表展示和搜索
     name = models.CharField(
         null=False,
         max_length=100,
         db_index=True,
         verbose_name="案例名称",
         help_text="案例名称",
-        db_comment='案例名称'
+        db_comment='案例名称'  # 数据库字段注释
     )
 
+    # ----------------------------------------------------------
     # 案例图片
+    # ----------------------------------------------------------
+    # 字段说明: 案例的图片
+    # 字段类型: 字符串（CharField）
+    # 约束: 允许为空（null=True, blank=True），最大长度255字符
+    # 存储: 存储的是相对路径，通过 get_file_url() 生成完整访问URL
+    # 作用: 用于案例列表展示和详情页的图片
     avatar = models.CharField(
         null=True,
         blank=True,
         max_length=255,
         verbose_name="案例图片",
         help_text="案例图片",
-        db_comment='案例图片'
+        db_comment='案例图片'  # 数据库字段注释
     )
 
+    # ----------------------------------------------------------
     # 案例类型
+    # ----------------------------------------------------------
+    # 类型常量定义
     TYPE_CHOICES = (
         (1, "类型1"),
         (2, "类型2"),
@@ -59,44 +87,98 @@ class Example(BaseModel):
         (4, "类型4"),
     )
 
+    # 字段说明: 案例的分类类型
+    # 字段类型: 整数（IntegerField）
+    # 约束: 非空（null=False）
+    # 选择项: 使用 TYPE_CHOICES 限制可选值
+    # 作用: 对案例进行分类管理，支持按类型筛选
     type = models.IntegerField(
         null=False,
         choices=TYPE_CHOICES,
         verbose_name="案例类型：1-类型1 2-类型2 3-类型3 4-类型4",
         help_text="案例类型：1-类型1 2-类型2 3-类型3 4-类型4",
-        db_comment='案例类型：1-类型1 2-类型2 3-类型3 4-类型4'
+        db_comment='案例类型：1-类型1 2-类型2 3-类型3 4-类型4'  # 数据库字段注释
     )
 
+    # ----------------------------------------------------------
     # 案例状态
+    # ----------------------------------------------------------
+    # 状态常量定义
     STATUS_CHOICES = (
-        (1, "正常"),
-        (2, "禁用"),
+        (1, "正常"),  # 正常状态：案例正常显示
+        (2, "禁用"),  # 禁用状态：案例不对外展示
     )
 
+    # 字段说明: 案例的显示状态
+    # 字段类型: 整数（IntegerField）
+    # 约束: 非空（null=False）
+    # 选择项: 使用 STATUS_CHOICES 限制可选值
+    # 作用: 控制案例是否在前端展示
     status = models.IntegerField(
         null=False,
         choices=STATUS_CHOICES,
         verbose_name="案例状态：1-正常 2-禁用",
         help_text="案例状态：1-正常 2-禁用",
-        db_comment='案例状态：1-正常 2-禁用'
+        db_comment='案例状态：1-正常 2-禁用'  # 数据库字段注释
     )
 
+    # ----------------------------------------------------------
     # 排序
+    # ----------------------------------------------------------
+    # 字段说明: 案例的排序权重
+    # 字段类型: 整数（IntegerField）
+    # 约束: 非空（null=False）
+    # 排序规则: 数值越小越靠前（升序排列）
+    # 作用: 手动控制案例在列表中的显示顺序
     sort = models.IntegerField(
         null=False,
         verbose_name="排序",
         help_text="排序",
-        db_comment='排序'
+        db_comment='排序'  # 数据库字段注释
     )
 
+    # =============================================================
+    # 模型元数据配置
+    # =============================================================
+
     class Meta:
+        """
+        模型元数据配置类
+
+        定义模型在数据库中的表名、显示名称、默认排序规则等。
+        """
+
+        # 数据表名
+        # 使用配置文件中的表前缀 + "example"，避免与其他应用表名冲突
         db_table = get_table_name('example')
+
+        # 表注释（Django 3.2+ 支持）
+        # 在数据库中生成 COMMENT 语句，便于数据库管理
         db_table_comment = "案例表"
+
+        # 模型在admin后台显示的友好名称（单数）
         verbose_name = "案例表"
+
+        # 模型在admin后台显示的友好名称（复数）
         verbose_name_plural = verbose_name
+
+        # 默认排序规则
+        # 按照 sort 字段升序排列（数值小的在前），确保显示顺序可控
         ordering = ("sort",)
 
+    # =============================================================
+    # 实例方法
+    # =============================================================
+
     def __str__(self):
+        """
+        模型的字符串表示方法
+
+        当需要将模型实例转换为字符串时调用，如admin后台显示、日志输出等。
+
+        Returns:
+            str: 包含案例名称的字符串
+        """
         return f"案例{self.name}"
 ```