truncdate 不能直接按周分组，因其仅支持年月日截断，不支持 week 参数；django 4.2+ 需改用 truncweek，此前版本需借助 extra() 或数据库原生函数实现。
TruncDate 为什么不能直接按周分组
TruncDate 的作用是把 DateTimeField 截断成 DateField，也就是去掉时分秒、只保留年月日。它天生不支持按“周”截断——没有 TruncWeek 这个类（Django 4.2 之前），强行传 week 会报 FieldError: Invalid truncation kind 'week'。
所以想按周聚合，得换函数：用 TruncWeek（Django 4.2+）或退而求其次用 extra() + 数据库原生函数（如 PostgreSQL 的 date_trunc('week', ...)），但后者跨数据库兼容性差。
- Django extra() 或
annotate()配合Func自定义表达式 - Django ≥ 4.2：优先用
TruncWeek，语义清晰、可迁移 - 所有版本都可用
TruncDate按天分组，但注意时区影响：默认按 UTC 截断，若模型字段带时区，需先用Cast或connection.timezone对齐
按天分组：TruncDate 最简写法与陷阱
最常见写法是：annotate(date=TruncDate('created_at'))，然后 values('date').annotate(count=Count('id'))。但实际中容易漏掉两点：
- 如果
created_at是DateTimeField且存的是本地时间（没设时区），TruncDate仍按 UTC 解析，导致某天凌晨的数据被算进前一天 - PostgreSQL 和 MySQL 对
DATE()行为略有差异；SQLite 则完全依赖 Python 的datetime.date()转换，可能出错 - 建议统一显式指定时区：
TruncDate('created_at', tzinfo=ZoneInfo('Asia/Shanghai'))（需 Python 3.9+）或用django.utils.timezone.get_current_timezone()
示例（安全写法）：
from django.db.models import Count
from django.db.models.functions import TruncDate
from django.utils.timezone import get_current_timezone
qs = MyModel.objects.annotate(
date=TruncDate('created_at', tzinfo=get_current_timezone())
).values('date').annotate(count=Count('id')).order_by('date')
按周分组：Django 4.2+ 直接用 TruncWeek
TruncWeek 返回的是周一零点的 datetime（不是字符串），可用于分组、排序、过滤。它的起始日固定为周一，不受 settings.TIME_ZONE 影响，但截断基准仍依赖字段值本身的时区信息。
- 必须确保数据库字段存储的是带时区的
datetime（即USE_TZ=True且字段值由 Django 自动注入时区），否则TruncWeek可能误判周界 - PostgreSQL 下
TruncWeek底层调用date_trunc('week', ...)，MySQL 则模拟实现（Django 自动处理），SQLite 需降级为extra() - 若要按“周几-周日”格式显示，别在数据库层拼接，应在 Python 层用
.strftime('%Y-W%W')或.isocalendar()
示例（按自然周聚合）：
from django.db.models import Count
from django.db.models.functions import TruncWeek
qs = MyModel.objects.annotate(
week_start=TruncWeek('created_at')
).values('week_start').annotate(total=Count('id')).order_by('week_start')
跨数据库兼容的备选方案：用 Func 手写 date_trunc
当项目必须支持多种数据库，又卡在旧版 Django 时，可以用 Func 包装原生函数。但要注意：不同数据库的 date_trunc 参数名和单位不一致——PostgreSQL 用 'week'，MySQL 用 WEEK 函数，SQLite 根本不支持。
- 推荐只对 PostgreSQL 和 MySQL 分别适配，SQLite 场景改用 Python 端分组（
itertools.groupby）避免硬编码 - 不要在
Func中拼 SQL 字符串，应通过template和function控制，例如：template="%(function)s('week', %(expressions)s)" - 这种写法会让 ORM 失去部分优化能力（如无法下推 WHERE 条件），大数据量时性能明显低于原生
TruncWeek
复杂点在于：你得同时维护数据库方言逻辑、时区对齐、以及前端展示时如何把 “2024-01-01T00:00:00+08:00” 变成 “2024-W01”。这些细节一旦漏掉，周统计就偏一天。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
