Update models.py

src/DjangoBlog-master/owntracks/models.py

@@ -1,20 +1,54 @@
+# 导入 Django ORM 核心模块：models 用于定义数据模型，对应数据库表结构
 from django.db import models
+# 导入 Django 时区工具：now() 用于获取当前时区的时间（避免时区不一致问题）
 from django.utils.timezone import now
 
 
 # Create your models here.
+# 说明：该注释为 Django 自动生成，提示开发者在此处定义数据模型类
+# 模型类与数据库表的映射关系：每个模型类对应一张数据库表，类属性对应表字段
 
 class OwnTrackLog(models.Model):
-    tid = models.CharField(max_length=100, null=False, verbose_name='用户')
-    lat = models.FloatField(verbose_name='纬度')
+    """
+    轨迹数据模型类：继承自 Django 内置的 models.Model（所有数据模型的基类）
+    核心作用：存储用户的地理轨迹信息（用户标识、经纬度、创建时间）
+    映射数据库表名：默认生成规则为「应用名_模型名小写」→ owntracks_owntracklog
+    """
+
+    # 1. 用户标识字段：存储用户唯一标识（如设备ID、用户名等）
+    tid = models.CharField(
+        max_length=100,  # 字段最大长度（CharField 必填参数），适配多数用户标识场景
+        null=False,      # 数据库层面不允许为空（必填字段），确保数据完整性
+        verbose_name='用户'  # Django 后台管理界面显示的字段名称（支持中文）
+    )
+
+    # 2. 纬度字段：存储地理纬度值（如 39.9042，支持正负值，适配全球地理坐标）
+    lat = models.FloatField(verbose_name='纬度')  # FloatField 对应数据库 float 类型，满足精度需求
+
+    # 3. 经度字段：存储地理经度值（如 116.4074，与纬度配合定位地理坐标）
     lon = models.FloatField(verbose_name='经度')
-    creation_time = models.DateTimeField('创建时间', default=now)
+
+    # 4. 创建时间字段：记录轨迹数据的生成时间
+    creation_time = models.DateTimeField(
+        '创建时间',  # verbose_name 的简写形式（第一个参数直接指定后台显示名称）
+        default=now  # 默认值：当前时区的当前时间（now 是可调用对象，每次创建记录时动态获取）
+        # 注：区别于 datetime.datetime.now()，django.utils.timezone.now() 包含时区信息，符合 Django 时区配置
+    )
 
     def __str__(self):
+        """
+        模型实例的字符串表示方法：
+        作用：在 Django 后台、终端打印实例时，显示直观的标识（而非默认的 <OwnTrackLog object>）
+        返回值：以用户标识（tid）作为实例的字符串描述，便于区分不同用户的轨迹数据
+        """
         return self.tid
 
     class Meta:
-        ordering = ['creation_time']
-        verbose_name = "OwnTrackLogs"
-        verbose_name_plural = verbose_name
-        get_latest_by = 'creation_time'
+        """
+        模型元数据类：用于配置模型的整体属性（不对应表字段，影响表的行为和显示）
+        所有配置仅作用于当前模型，不影响其他模型
+        """
+        ordering = ['creation_time']  # 默认排序规则：按创建时间升序排列（-creation_time 表示降序）
+        verbose_name = "OwnTrackLogs"  # 后台管理界面显示的「单数模型名称」
+        verbose_name_plural = verbose_name  # 后台管理界面显示的「复数模型名称」（此处与单数一致，避免英文复数歧义）
+        get_latest_by = 'creation_time'  # 支持 Model.objects.latest() 方法，默认按创建时间获取最新一条记录