微信小程序页面迁移校验之前 P5任务处理之前

packages/shared/src/neozqyy_shared/datetime_utils.py

@@ -3,6 +3,7 @@
 
 默认时区：Asia/Shanghai（UTC+8），与业务数据库 timestamptz 对齐。
 """
+import calendar
 from datetime import datetime, date, timedelta
 from dateutil import tz
 
@@ -23,3 +24,94 @@ def date_range(start: date, end: date) -> list[date]:
         return []
     days = (end - start).days + 1
     return [start + timedelta(days=i) for i in range(days)]
+
+
+# 营业日切点默认值（小时），与 .env BUSINESS_DAY_START_HOUR 对齐
+DEFAULT_BUSINESS_DAY_START_HOUR = 8
+
+
+def business_date(dt: datetime, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR) -> date:
+    """将时间戳归属到营业日。
+
+    day_start_hour 之前的记录归属前一天。
+    例：day_start_hour=8 时，07:59 归属前一天，08:00 归属当天。
+    """
+    if dt.hour < day_start_hour:
+        return (dt - timedelta(days=1)).date()
+    return dt.date()
+
+
+def business_month(dt: datetime, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR) -> date:
+    """将时间戳归属到营业月（返回该月第一天）。
+
+    当月1日 day_start_hour 之前的记录归属上月。
+    """
+    biz_d = business_date(dt, day_start_hour)
+    return biz_d.replace(day=1)
+
+
+def business_week_monday(dt: datetime, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR) -> date:
+    """将时间戳归属到营业周（返回该周周一日期）。
+
+    周一 day_start_hour 之前的记录归属上周。
+    """
+    biz_d = business_date(dt, day_start_hour)
+    return biz_d - timedelta(days=biz_d.weekday())
+
+
+def biz_date_sql_expr(col: str, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR) -> str:
+    """生成 PostgreSQL 营业日归属 SQL 表达式。
+
+    返回形如 DATE(col - INTERVAL '8 hours') 的字符串，
+    用于替换原来的 DATE(col)。
+    """
+    return f"DATE({col} - INTERVAL '{day_start_hour} hours')"
+
+
+def business_day_range(
+    biz_date: date, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR
+) -> tuple[datetime, datetime]:
+    """返回给定营业日的精确时间戳范围 [start, end)。
+
+    start = biz_date 当天 day_start_hour:00（Asia/Shanghai）
+    end   = biz_date 次日 day_start_hour:00（Asia/Shanghai）
+    """
+    start = datetime(biz_date.year, biz_date.month, biz_date.day,
+                     day_start_hour, 0, 0, tzinfo=SHANGHAI_TZ)
+    end = start + timedelta(days=1)
+    return (start, end)
+
+
+def business_week_range(
+    week_monday: date, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR
+) -> tuple[datetime, datetime]:
+    """返回给定营业周（周一）的精确时间戳范围 [start, end)。
+
+    start = week_monday 当天 day_start_hour:00（Asia/Shanghai）
+    end   = week_monday + 7天 day_start_hour:00（Asia/Shanghai）
+    """
+    start = datetime(week_monday.year, week_monday.month, week_monday.day,
+                     day_start_hour, 0, 0, tzinfo=SHANGHAI_TZ)
+    end = start + timedelta(days=7)
+    return (start, end)
+
+
+def business_month_range(
+    month_first: date, day_start_hour: int = DEFAULT_BUSINESS_DAY_START_HOUR
+) -> tuple[datetime, datetime]:
+    """返回给定营业月（首日）的精确时间戳范围 [start, end)。
+
+    start = month_first 当天 day_start_hour:00（Asia/Shanghai）
+    end   = 次月1日 day_start_hour:00（Asia/Shanghai）
+    """
+    start = datetime(month_first.year, month_first.month, month_first.day,
+                     day_start_hour, 0, 0, tzinfo=SHANGHAI_TZ)
+    # 计算次月1日
+    if month_first.month == 12:
+        next_month_first = date(month_first.year + 1, 1, 1)
+    else:
+        next_month_first = date(month_first.year, month_first.month + 1, 1)
+    end = datetime(next_month_first.year, next_month_first.month,
+                   next_month_first.day, day_start_hour, 0, 0,
+                   tzinfo=SHANGHAI_TZ)
+    return (start, end)