owntracks模块代码标注

src/owntracks/admin.py

@@ -2,6 +2,9 @@ from django.contrib import admin
 
 # Register your models here.
 
-
+# 定义一个 Django Admin 管理类，用于自定义管理界面中 OwnTrackLogs 模型的显示和行为
+# 当前未添加任何自定义配置，使用默认的管理界面设置
 class OwnTrackLogsAdmin(admin.ModelAdmin):
-    pass
+    # 该类目前为空，表示使用 Django admin 的默认行为来管理 OwnTrackLogs 模型
+    # 可在此处添加如 list_display, list_filter, search_fields 等属性来自定义管理界面
+    pass

src/owntracks/apps.py

@@ -1,5 +1,12 @@
 from django.apps import AppConfig
 
 
+# OwntracksConfig 是 Django 应用 'owntracks' 的配置类。
+# 它继承自 Django 的 AppConfig，用于定义该应用的配置信息。
+# 当 Django 启动时，会自动发现并加载此配置，以正确初始化该应用。
 class OwntracksConfig(AppConfig):
-    name = 'owntracks'
+    # name 属性指定了该 Django 应用的完整 Python 导入路径。
+    # 这个路径告诉 Django 如何导入这个应用。在这个例子中，
+    # 表示该应用位于 PYTHONPATH 下可以直接导入的 'owntracks' 模块（或包）中。
+    # 这个值通常与应用所在目录的名称一致。
+    name = 'owntracks'

src/owntracks/migrations/0001_initial.py

@@ -1,31 +1,77 @@
 # Generated by Django 4.1.7 on 2023-03-02 07:14
 
+# 导入 Django 迁移系统所需的核心模块
+# migrations: 用于定义数据库模式变更
+# models: 用于定义模型字段类型
 from django.db import migrations, models
+# 导入 Django 的时区工具，用于提供默认时间
 import django.utils.timezone
 
 
+# 定义一个 Django 数据库迁移类
+# 该类继承自 migrations.Migration，由 Django 自动生成，用于描述对数据库模式的变更
 class Migration(migrations.Migration):
-
+    # 标记此迁移为应用的初始迁移（initial migration）
+    # 当应用首次被迁移时，Django 会识别并执行此迁移
     initial = True
 
+    # 定义此迁移所依赖的其他迁移
+    # 由于这是初始迁移且没有依赖其他应用的模型，因此为空列表
+    # 如果模型外键关联了其他应用的模型，则需要在此列出对应的迁移
     dependencies = [
     ]
 
+    # 定义此迁移要执行的具体数据库操作列表
+    # 每个操作是一个 Migration 操作类的实例，如 CreateModel、AddField 等
     operations = [
+        # 创建一个名为 'OwnTrackLog' 的新数据库模型（对应一张数据表）
         migrations.CreateModel(
+            # 指定要创建的模型名称
             name='OwnTrackLog',
+            # 定义该模型包含的数据库字段
+            # 每个字段由字段名和字段类型及参数组成
             fields=[
+                # 主键字段 'id'：自增的 BigAutoField（64位整数）
+                # auto_created=True: 表示是 Django 自动创建的主键
+                # primary_key=True: 指定为主键
+                # serialize=False: 在序列化（如 dumpdata）时是否包含此字段
+                # verbose_name='ID': 在管理后台等界面显示的可读名称
                 ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+
+                # 'tid' 字段：存储用户或设备标识，使用 CharField
+                # max_length=100: 最大长度为100个字符
+                # verbose_name='用户': 在界面中显示为“用户”
                 ('tid', models.CharField(max_length=100, verbose_name='用户')),
+
+                # 'lat' 字段：存储纬度值，使用 FloatField（浮点数）
+                # verbose_name='纬度': 在界面中显示为“纬度”
                 ('lat', models.FloatField(verbose_name='纬度')),
+
+                # 'lon' 字段：存储经度值，使用 FloatField（浮点数）
+                # verbose_name='经度': 在界面中显示为“经度”
                 ('lon', models.FloatField(verbose_name='经度')),
+
+                # 'created_time' 字段：记录创建时间，使用 DateTimeField
+                # default=django.utils.timezone.now: 默认值为当前时间（注意：传入函数引用，非调用结果）
+                # verbose_name='创建时间': 在界面中显示为“创建时间”
                 ('created_time', models.DateTimeField(default=django.utils.timezone.now, verbose_name='创建时间')),
             ],
+            # 定义该模型的元数据选项（对应模型内部的 Meta 类）
             options={
+                # verbose_name: 模型在管理后台的单数可读名称
                 'verbose_name': 'OwnTrackLogs',
+
+                # verbose_name_plural: 模型在管理后台的复数可读名称
+                # 此处与单数名称相同
                 'verbose_name_plural': 'OwnTrackLogs',
+
+                # ordering: 查询该模型时的默认排序字段
+                # 按 'created_time' 升序排列
                 'ordering': ['created_time'],
+
+                # get_latest_by: 指定用于获取最新记录的字段
+                # 调用 latest() 方法时会基于此字段排序
                 'get_latest_by': 'created_time',
             },
         ),
-    ]
+    ]

src/owntracks/migrations/0002_alter_owntracklog_options_and_more.py

@@ -1,22 +1,51 @@
 # Generated by Django 4.2.5 on 2023-09-06 13:19
 
+# 导入 Django 数据库迁移模块，用于执行数据库模式变更
 from django.db import migrations
 
 
+# 定义一个 Django 数据库迁移类
+# 该类继承自 migrations.Migration，由 Django 自动生成，用于描述对数据库模式的变更
+# 此迁移是继初始迁移之后的第二次迁移，用于修改现有模型
 class Migration(migrations.Migration):
-
+    # 定义此迁移所依赖的其他迁移
+    # 必须在 'owntracks' 应用的 '0001_initial' 迁移成功执行后，此迁移才能执行
+    # 确保数据库状态的顺序性和一致性
     dependencies = [
         ('owntracks', '0001_initial'),
     ]
 
+    # 定义此迁移要执行的具体数据库操作列表
+    # 包含两个操作：修改模型选项和重命名字段
     operations = [
+        # 操作一：修改模型 'owntracklog' 的元数据选项（Meta options）
+        # 将模型的 verbose_name, verbose_name_plural, ordering, get_latest_by 等选项更新为新的值
+        # 注意：此操作只修改 Django ORM 层的元数据，不直接修改数据库表结构
         migrations.AlterModelOptions(
+            # 指定要修改选项的模型名称（小写）
             name='owntracklog',
-            options={'get_latest_by': 'creation_time', 'ordering': ['creation_time'], 'verbose_name': 'OwnTrackLogs', 'verbose_name_plural': 'OwnTrackLogs'},
+            # 新的元数据选项字典
+            options={
+                # 指定获取最新记录时依据的字段
+                'get_latest_by': 'creation_time',
+                # 指定模型实例的默认排序方式
+                'ordering': ['creation_time'],
+                # 在管理后台等界面中显示的单数名称
+                'verbose_name': 'OwnTrackLogs',
+                # 在管理后台等界面中显示的复数名称
+                'verbose_name_plural': 'OwnTrackLogs',
+            },
         ),
+
+        # 操作二：将模型 'owntracklog' 中的数据库字段从 'created_time' 重命名为 'creation_time'
+        # 这是一个数据库级别的 DDL 操作，会实际执行 ALTER TABLE ... RENAME COLUMN 语句
+        # 确保数据库字段名与 Django 模型代码中的字段名保持一致
         migrations.RenameField(
+            # 指定要操作的模型名称
             model_name='owntracklog',
+            # 旧的字段名（数据库中当前的列名）
             old_name='created_time',
+            # 新的字段名（要更改为的列名）
             new_name='creation_time',
         ),
-    ]
+    ]

src/owntracks/models.py

@@ -4,17 +4,53 @@ from django.utils.timezone import now
 
 # Create your models here.
 
+# 定义一个名为 OwnTrackLog 的数据库模型，用于存储由 OwnTracks 应用程序上传的位置日志数据。
+# 该模型继承自 Django 的 models.Model 类，每个类属性对应数据库中的一列。
 class OwnTrackLog(models.Model):
+    # tid (Tracker ID): 标识发送位置信息的设备或用户。
+    # 使用 CharField 存储字符串，最大长度为100个字符，不允许为空（null=False）。
+    # verbose_name 设置为 '用户'，在 Django 管理后台等界面中显示为“用户”。
     tid = models.CharField(max_length=100, null=False, verbose_name='用户')
+
+    # lat: 存储地理位置的纬度坐标。
+    # 使用 FloatField 存储浮点数，表示纬度值（例如：39.9042）。
+    # verbose_name 设置为 '纬度'，用于在管理后台中显示友好的字段名。
     lat = models.FloatField(verbose_name='纬度')
+
+    # lon: 存储地理位置的经度坐标。
+    # 使用 FloatField 存储浮点数，表示经度值（例如：116.4074）。
+    # verbose_name 设置为 '经度'，用于在管理后台中显示友好的字段名。
     lon = models.FloatField(verbose_name='经度')
+
+    # creation_time: 记录该位置信息被创建的时间。
+    # 使用 DateTimeField 存储日期和时间。
+    # 第一个参数 '创建时间' 是该字段的 verbose_name（可读名称）。
+    # default=now 表示默认值为当前时间（注意：这里传入的是函数引用 now，不是 now()，以避免迁移时时间固定）。
     creation_time = models.DateTimeField('创建时间', default=now)
 
+    # __str__(self) 方法定义了该模型实例对象在转换为字符串时的行为。
+    # 在 Django 管理后台、shell 或其他需要显示对象的地方，会显示此方法的返回值。
+    # 此处返回 self.tid，即该记录对应的用户/设备ID，便于识别。
     def __str__(self):
         return self.tid
 
+    # Meta 类是 Django 模型的内部类，用于定义模型的元数据（metadata），不作为一个字段存在。
     class Meta:
+        # ordering: 指定查询该模型时的默认排序方式。
+        # ['creation_time'] 表示按 creation_time 字段升序排列（最早的数据在前）。
+        # 若需降序，可写为 ['-creation_time']。
         ordering = ['creation_time']
+
+        # verbose_name: 指定该模型在 Django 管理后台或其他用户界面中的可读单数名称。
+        # 这里设置为 "OwnTrackLogs"，会在管理后台的菜单中显示为此名称。
         verbose_name = "OwnTrackLogs"
+
+        # verbose_name_plural: 指定该模型的可读复数名称。
+        # 通常 Django 会自动加 's'，但有时需要自定义。
+        # 此处将其设置为与 verbose_name 相同，即单复数形式一致，都显示为 "OwnTrackLogs"。
         verbose_name_plural = verbose_name
-        get_latest_by = 'creation_time'
+
+        # get_latest_by: 指定用于获取最新记录的字段。
+        # 当调用模型管理器的 latest() 方法时，Django 会使用此字段进行排序并返回最新的对象。
+        # 例如：OwnTrackLog.objects.latest() 将返回 creation_time 最晚的记录。
+        get_latest_by = 'creation_time'

src/owntracks/tests.py

@@ -1,64 +1,115 @@
 import json
 
+# 导入 Django 测试框架所需的核心类和模块
 from django.test import Client, RequestFactory, TestCase
 
+# 导入项目中使用的自定义用户模型和位置日志模型，用于在测试中创建用户和验证数据
 from accounts.models import BlogUser
 from .models import OwnTrackLog
 
 
 # Create your tests here.
 
+# 定义一个测试类，用于测试 OwnTrackLog 相关的功能，如数据接收、地图展示、数据查询等
+# 继承自 Django 的 TestCase，提供数据库隔离、断言方法和测试工具
 class OwnTrackLogTest(TestCase):
+    # setUp 方法在每个测试方法执行前自动运行，用于准备测试所需的环境和对象
+    # 本方法中初始化了测试客户端和请求工厂，便于模拟 HTTP 请求
     def setUp(self):
+        # 创建一个 Django 测试客户端实例，用于模拟浏览器发送 GET、POST 等请求
         self.client = Client()
+
+        # 创建一个请求工厂实例，用于创建伪造的 HTTP 请求对象（如 HttpRequest）
+        # 适用于需要直接调用视图函数的测试场景（本测试中未直接使用，但已准备）
         self.factory = RequestFactory()
 
+    # test_own_track_log 是一个具体的测试用例，用于验证 OwnTrackLog 功能的正确性
+    # 测试内容包括：接收位置数据、数据完整性、权限控制、页面响应等
     def test_own_track_log(self):
+        # 构造一个模拟的位置数据字典，包含 tid（用户标识）、lat（纬度）、lon（经度）
         o = {
             'tid': 12,
             'lat': 123.123,
             'lon': 134.341
         }
 
+        # 使用测试客户端发送一个 POST 请求到 '/owntracks/logtracks' 接口
+        # 将位置数据 o 序列化为 JSON 字符串，并设置内容类型为 application/json
+        # 模拟 OwnTracks 客户端上传位置信息
         self.client.post(
             '/owntracks/logtracks',
             json.dumps(o),
             content_type='application/json')
+
+        # 查询数据库中 OwnTrackLog 模型的所有记录数量
         length = len(OwnTrackLog.objects.all())
+
+        # 断言：验证数据库中记录数为 1，确保第一次 POST 请求成功写入一条数据
         self.assertEqual(length, 1)
 
+        # 构造第二条位置数据，缺少 'lon' 字段（经度）
         o = {
             'tid': 12,
             'lat': 123.123
         }
 
+        # 再次发送 POST 请求上传不完整的位置数据
         self.client.post(
             '/owntracks/logtracks',
             json.dumps(o),
             content_type='application/json')
+
+        # 再次查询数据库中的总记录数
         length = len(OwnTrackLog.objects.all())
+
+        # 断言：验证记录数仍为 1，确保系统能正确处理不完整数据（如忽略或拒绝），未新增无效记录
         self.assertEqual(length, 1)
 
+        # 发送 GET 请求访问 '/owntracks/show_maps' 页面（查看地图）
         rsp = self.client.get('/owntracks/show_maps')
+
+        # 断言：检查响应状态码为 302（重定向），说明未登录用户访问地图页时被重定向（如跳转到登录页）
         self.assertEqual(rsp.status_code, 302)
 
+        # 创建一个超级用户，用于测试需要登录权限的功能
+        # 使用 BlogUser 模型的 create_superuser 方法创建具有管理员权限的测试用户
         user = BlogUser.objects.create_superuser(
             email="liangliangyy1@gmail.com",
             username="liangliangyy1",
             password="liangliangyy1")
 
+        # 使用测试客户端以刚创建的超级用户身份登录
+        # 模拟用户登录过程，使后续请求具有认证状态
         self.client.login(username='liangliangyy1', password='liangliangyy1')
+
+        # 手动创建一条 OwnTrackLog 记录并保存到数据库
+        # 直接操作模型，用于准备测试数据
         s = OwnTrackLog()
         s.tid = 12
         s.lon = 123.234
         s.lat = 34.234
         s.save()
 
+        # 发送 GET 请求访问 '/owntracks/show_dates' 页面（查看日期列表）
         rsp = self.client.get('/owntracks/show_dates')
+
+        # 断言：检查响应状态码为 200（成功），说明登录后可以正常访问该页面
         self.assertEqual(rsp.status_code, 200)
+
+        # 发送 GET 请求访问 '/owntracks/show_maps' 页面（查看地图）
         rsp = self.client.get('/owntracks/show_maps')
+
+        # 断言：检查响应状态码为 200（成功），说明登录后可以正常访问地图页面
         self.assertEqual(rsp.status_code, 200)
+
+        # 发送 GET 请求访问 '/owntracks/get_datas' 接口（获取位置数据）
         rsp = self.client.get('/owntracks/get_datas')
+
+        # 断言：检查响应状态码为 200（成功），说明数据接口正常返回
         self.assertEqual(rsp.status_code, 200)
+
+        # 发送 GET 请求访问 '/owntracks/get_datas' 接口，并携带日期查询参数 date=2018-02-26
         rsp = self.client.get('/owntracks/get_datas?date=2018-02-26')
-        self.assertEqual(rsp.status_code, 200)
+
+        # 断言：检查响应状态码为 200（成功），说明带参数的数据查询功能正常
+        self.assertEqual(rsp.status_code, 200)

src/owntracks/urls.py

@@ -1,12 +1,34 @@
 from django.urls import path
 
+# 导入当前应用（owntracks）的视图模块，用于将 URL 路由映射到具体的视图函数
 from . import views
 
+# 定义应用命名空间（application namespace）
+# 允许在项目其他地方（如模板、reverse() 函数）通过 'owntracks:xxx' 的方式引用本应用的 URL
+# 避免不同应用之间 URL 名称冲突
 app_name = "owntracks"
 
+# urlpatterns 是 Django 用于定义 URL 路由的核心变量
+# 它是一个列表，包含了一系列 path() 实例，每个实例定义了一个 URL 模式与视图函数的映射关系
 urlpatterns = [
+    # 将 URL 路径 'owntracks/logtracks' 映射到 views 模块中的 manage_owntrack_log 视图函数
+    # 该接口用于接收 OwnTracks 客户端上传的位置日志数据（通常为 POST 请求）
+    # 在模板或代码中可通过 {% url 'owntracks:logtracks' %} 反向解析此 URL
     path('owntracks/logtracks', views.manage_owntrack_log, name='logtracks'),
+
+    # 将 URL 路径 'owntracks/show_maps' 映射到 views 模块中的 show_maps 视图函数
+    # 该接口用于渲染并展示用户位置轨迹的地图页面（通常为 GET 请求）
+    # 需要用户登录后访问，显示历史轨迹
     path('owntracks/show_maps', views.show_maps, name='show_maps'),
+
+    # 将 URL 路径 'owntracks/get_datas' 映射到 views 模块中的 get_datas 视图函数
+    # 该接口是一个数据接口（API），用于返回指定日期的位置轨迹数据（通常为 JSON 格式）
+    # 前端地图页面通过 AJAX 调用此接口获取数据进行渲染
+    # 支持通过查询参数（如 ?date=...）指定日期
     path('owntracks/get_datas', views.get_datas, name='get_datas'),
+
+    # 将 URL 路径 'owntracks/show_dates' 映射到 views 模块中的 show_log_dates 视图函数
+    # 该接口用于展示用户有轨迹记录的所有日期列表页面
+    # 通常作为地图页面的前置页面，让用户选择要查看的日期
     path('owntracks/show_dates', views.show_log_dates, name='show_dates')
-]
+]

src/owntracks/views.py

@@ -14,114 +14,187 @@ from django.http import JsonResponse
 from django.shortcuts import render
 from django.views.decorators.csrf import csrf_exempt
 
+# 导入当前应用的模型，用于在视图中操作数据库
 from .models import OwnTrackLog
 
+# 获取一个 logger 实例，用于记录日志信息（如请求、错误等）
 logger = logging.getLogger(__name__)
 
 
+# 视图函数：接收并处理 OwnTracks 客户端上传的位置日志数据
+# 使用 @csrf_exempt 装饰器免除 CSRF 验证，因为客户端可能无法提供 CSRF token
+# 该函数预期接收 JSON 格式的 POST 请求
 @csrf_exempt
 def manage_owntrack_log(request):
     try:
+        # 读取请求体的原始数据，并解码为 UTF-8 字符串，然后解析为 Python 字典
         s = json.loads(request.read().decode('utf-8'))
+        # 从解析后的数据中提取 tid（用户/设备标识）、lat（纬度）、lon（经度）
         tid = s['tid']
         lat = s['lat']
         lon = s['lon']
 
+        # 记录一条 INFO 级别的日志，包含接收到的位置信息
         logger.info(
             'tid:{tid}.lat:{lat}.lon:{lon}'.format(
                 tid=tid, lat=lat, lon=lon))
+
+        # 验证提取的数据是否都存在（非空）
         if tid and lat and lon:
+            # 创建一个新的 OwnTrackLog 模型实例
             m = OwnTrackLog()
+            # 将接收到的数据赋值给模型字段
             m.tid = tid
             m.lat = lat
             m.lon = lon
+            # 保存到数据库（creation_time 会自动使用默认值 now）
             m.save()
+            # 返回 HTTP 响应 'ok'，表示数据接收和保存成功
             return HttpResponse('ok')
         else:
+            # 如果数据不完整，返回 'data error'
             return HttpResponse('data error')
     except Exception as e:
+        # 捕获任何异常，记录错误日志，并返回 'error' 响应
         logger.error(e)
         return HttpResponse('error')
 
 
+# 视图函数：渲染显示地图的 HTML 页面
+# 使用 @login_required 装饰器，确保只有登录用户才能访问
 @login_required
 def show_maps(request):
+    # 进一步检查用户是否为超级用户（管理员）
     if request.user.is_superuser:
+        # 获取当前 UTC 日期，作为默认日期
         defaultdate = str(datetime.datetime.now(timezone.utc).date())
+        # 从 GET 请求参数中获取 'date'，如果不存在则使用默认日期
         date = request.GET.get('date', defaultdate)
+        # 构造模板上下文，将日期传递给前端
         context = {
             'date': date
         }
+        # 使用指定的 HTML 模板渲染响应
         return render(request, 'owntracks/show_maps.html', context)
     else:
+        # 如果不是超级用户，返回 403 禁止访问
         from django.http import HttpResponseForbidden
         return HttpResponseForbidden()
 
 
+# 视图函数：渲染显示有轨迹记录的日期列表页面
+# 使用 @login_required 装饰器，确保只有登录用户才能访问
 @login_required
 def show_log_dates(request):
+    # 查询所有 OwnTrackLog 记录的 creation_time 字段值
     dates = OwnTrackLog.objects.values_list('creation_time', flat=True)
+    # 将 datetime 对象转换为 'YYYY-MM-DD' 格式的字符串，并去重、排序
     results = list(sorted(set(map(lambda x: x.strftime('%Y-%m-%d'), dates))))
 
+    # 构造模板上下文，将日期列表传递给前端
     context = {
         'results': results
     }
+    # 使用指定的 HTML 模板渲染响应
     return render(request, 'owntracks/show_log_dates.html', context)
 
 
+# 辅助函数：将 GPS 坐标（WGS-84）批量转换为高德地图坐标系（GCJ-02）
+# 由于高德 API 有数量限制，此处每次处理最多 30 个点
+# 注意：此函数在 get_datas 中被注释掉，当前未使用
 def convert_to_amap(locations):
-    convert_result = []
-    it = iter(locations)
+    convert_result = []  # 存储转换后的坐标结果
+    it = iter(locations)  # 创建一个迭代器
 
+    # 每次从迭代器中取出最多 30 个位置点
     item = list(itertools.islice(it, 30))
     while item:
+        # 将每个点的经度和纬度拼接成 "lon,lat" 字符串，用分号连接成一个列表
         datas = ';'.join(
             set(map(lambda x: str(x.lon) + ',' + str(x.lat), item)))
 
+        # 高德坐标转换 API 的固定参数
         key = '8440a376dfc9743d8924bf0ad141f28e'
         api = 'http://restapi.amap.com/v3/assistant/coordinate/convert'
+        # 构造请求参数
         query = {
             'key': key,
             'locations': datas,
-            'coordsys': 'gps'
+            'coordsys': 'gps'  # 指定原始坐标系为 GPS（WGS-84）
         }
+        # 发送 GET 请求到高德 API
         rsp = requests.get(url=api, params=query)
+        # 解析 API 返回的 JSON 数据
         result = json.loads(rsp.text)
+        # 如果返回结果包含转换后的坐标，则添加到结果列表
         if "locations" in result:
             convert_result.append(result['locations'])
+        # 继续处理下一批最多 30 个点
         item = list(itertools.islice(it, 30))
 
+    # 将所有批次的转换结果合并成一个以分号分隔的字符串并返回
     return ";".join(convert_result)
 
 
+# 视图函数：返回指定日期的位置轨迹数据，供前端地图使用
+# 返回 JSON 格式的数据，通常由 AJAX 调用
+# 使用 @login_required 装饰器，确保只有登录用户才能访问
 @login_required
 def get_datas(request):
+    # 获取当前 UTC 时间
     now = django.utils.timezone.now().replace(tzinfo=timezone.utc)
+    # 构造查询日期的起始时间（当天 00:00:00 UTC）
     querydate = django.utils.timezone.datetime(
         now.year, now.month, now.day, 0, 0, 0)
+
+    # 如果请求中包含 'date' 参数，则使用该参数指定的日期
     if request.GET.get('date', None):
+        # 解析 'YYYY-MM-DD' 格式的日期字符串
         date = list(map(lambda x: int(x), request.GET.get('date').split('-')))
         querydate = django.utils.timezone.datetime(
             date[0], date[1], date[2], 0, 0, 0)
+
+    # 计算查询结束时间（起始时间 + 1 天）
     nextdate = querydate + datetime.timedelta(days=1)
+
+    # 查询指定日期范围内（当天）的所有位置记录
     models = OwnTrackLog.objects.filter(
         creation_time__range=(querydate, nextdate))
+
+    # 初始化结果列表
     result = list()
+
+    # 如果查询到记录，则按 tid（用户/设备）分组处理
     if models and len(models):
         for tid, item in groupby(
-                sorted(models, key=lambda k: k.tid), key=lambda k: k.tid):
+                # 先按 tid 排序，以便 groupby 正确分组
+                sorted(models, key=lambda k: k.tid),
+                # 指定分组依据为 tid
+                key=lambda k: k.tid):
 
+            # 为每个 tid 创建一个数据字典
             d = dict()
-            d["name"] = tid
-            paths = list()
-            # 使用高德转换后的经纬度
+            d["name"] = tid  # 记录设备/用户名称
+            paths = list()  # 存储该设备的轨迹点序列
+
+            # 方案一（当前启用）：直接使用原始 GPS 坐标
+            # 遍历该设备当天的所有位置点，按时间排序
+            for location in sorted(item, key=lambda x: x.creation_time):
+                # 将每个点的经度和纬度作为字符串列表添加到 paths
+                paths.append([str(location.lon), str(location.lat)])
+
+            # # 方案二（注释中）：使用高德转换后的坐标
+            # # 先转换坐标，然后解析
             # locations = convert_to_amap(
             #     sorted(item, key=lambda x: x.creation_time))
             # for i in locations.split(';'):
             #     paths.append(i.split(','))
-            # 使用GPS原始经纬度
-            for location in sorted(item, key=lambda x: x.creation_time):
-                paths.append([str(location.lon), str(location.lat)])
+
+            # 将轨迹点列表赋值给字典的 "path" 键
             d["path"] = paths
+            # 将该设备的轨迹数据添加到总结果列表
             result.append(d)
-    return JsonResponse(result, safe=False)
+
+    # 将结果列表序列化为 JSON 并返回
+    # safe=False 允许返回非字典类型的对象（如列表）
+    return JsonResponse(result, safe=False)