优化更新

2026-09-13 17:33:13 +08:00
parent 8be23a62a3
commit 7f758cc6e9
97 changed files with 2333 additions and 3595 deletions
@@ -53,65 +53,100 @@ JsonResponse  <-- Django HTTP响应

 ```python
 class BaseModel(models.Model):
-    """基础模型抽象类"""
+    """
+    基础模型抽象类
+    ==============
+    功能：提供所有模型的公共字段，如主键、创建人、创建时间等
+    特点：定义为抽象类，不会在数据库中创建对应的表
+    用途：被其他业务模型继承，实现字段复用
+
+    继承此基类的模型会自动拥有以下6个公共字段：
+    - id: 自增主键
+    - create_user: 创建人
+    - create_time: 创建时间
+    - update_user: 更新人
+    - update_time: 更新时间
+    - is_delete: 逻辑删除标识
+
+    注意：公共字段会自动排列在业务字段之后，使数据库表结构更清晰
+    """
+
+    # ==================== 公共字段定义 ====================

    # 主键ID字段
+    # 自增主键，每个模型的唯一标识符
    id = models.AutoField(
-        auto_created=True,
-        primary_key=True,
-        serialize=False,
-        verbose_name='主键ID',
-        db_comment='主键ID'
+        auto_created=True,  # 自动创建主键字段
+        primary_key=True,  # 设置为主键
+        serialize=False,  # 不参与序列化（避免在API响应中暴露）
+        verbose_name='主键ID',  # 字段中文名称
+        db_comment='主键ID'  # 数据库字段注释
    )

    # 创建人字段
+    # 记录数据由谁创建，通常关联用户表的用户名或ID
+    # 例如：admin, zhangsan, system
    create_user = models.CharField(
-        null=True,
-        max_length=50,
-        default=None,
-        db_default=None,
-        verbose_name='创建人',
-        db_comment='创建人'
+        null=True,  # 数据库允许为NULL
+        max_length=50,  # 最大长度50个字符
+        default=None,  # 默认值为None
+        db_default=None,  # 数据库层默认值
+        verbose_name='创建人',  # 字段中文名称
+        db_comment='创建人'  # 数据库字段注释
    )

    # 创建时间字段
+    # 自动记录数据创建的时间戳
+    # auto_now_add: 仅在创建时自动设置当前时间，后续更新不会改变
    create_time = models.DateTimeField(
-        null=True,
-        auto_now_add=True,
-        verbose_name="创建时间",
-        max_length=11,
-        db_comment='创建时间'
+        null=True,  # 数据库允许为NULL
+        auto_now_add=True,  # 创建时自动设为当前时间
+        verbose_name="创建时间",  # 字段中文名称
+        max_length=11,  # 时间戳长度
+        db_comment='创建时间'  # 数据库字段注释
    )

    # 更新人字段
+    # 记录数据最后由谁更新，通常关联用户表的用户名或ID
+    # null=True: 允许数据库为NULL（新创建记录时可能没有更新人）
    update_user = models.CharField(
-        null=True,
-        max_length=50,
-        default=None,
-        db_default=None,
-        verbose_name='更新人',
-        db_comment='更新人'
+        null=True,  # 数据库允许为NULL
+        max_length=50,  # 最大长度50个字符
+        default=None,  # 默认值为None
+        db_default=None,  # 数据库层默认值
+        verbose_name='更新人',  # 字段中文名称
+        db_comment='更新人'  # 数据库字段注释
    )

    # 更新时间字段
+    # 自动记录数据最后更新的时间戳
+    # auto_now: 每次保存（更新）时自动设为当前时间
    update_time = models.DateTimeField(
-        null=True,
-        auto_now=True,
-        verbose_name="更新时间",
-        max_length=11,
-        db_comment='更新时间'
+        null=True,  # 数据库允许为NULL
+        auto_now=True,  # 每次保存时自动更新为当前时间
+        verbose_name="更新时间",  # 字段中文名称
+        max_length=11,  # 时间戳长度
+        db_comment='更新时间'  # 数据库字段注释
    )

    # 逻辑删除标识
+    # 用于软删除，避免物理删除数据造成的数据丢失
+    # 0：正常（默认值）| 1：已删除
    is_delete = models.BooleanField(
-        default=0,
-        db_default=0,
-        verbose_name="逻辑删除",
-        db_comment='逻辑删除：0-正常 1-已删除'
+        default=0,  # 默认为0，表示正常
+        db_default=0,  # 数据库层默认值
+        verbose_name="逻辑删除",  # 字段中文名称
+        db_comment='逻辑删除：0-正常 1-已删除'  # 数据库字段注释
    )

    class Meta:
-        abstract = True  # 抽象模型，不创建数据库表
+        """
+        元数据配置
+        """
+        # 定义为抽象模型类
+        # abstract = True 表示这个模型是抽象的，不会在数据库中创建对应的表
+        # 子类模型会继承这些字段，并在各自对应的表中创建这些列
+        abstract = True
 ```

 ### 字段说明