"""调度时区工具。

背景(P1-3):
    定时任务 cron 触发时区与"今天"的判定必须一致。此前 cron 用
    Asia/Shanghai,而 `date.today()` / `datetime.now()` 取系统时区——
    若系统时区不是 Asia/Shanghai(如 UTC),07:00 上海(=前一日 23:00 UTC)
    触发时 `date.today()` 会返回错误日期,整条 pipeline 落在错日目录。

统一入口:
    schedule_tz(): 调度时区(env SCHEDULE_TZ 可覆盖,默认 Asia/Shanghai)
    today_str():   按调度时区返回 YYYYMMDD
"""

from __future__ import annotations

import os
from datetime import datetime
from zoneinfo import ZoneInfo

# 默认调度时区(与 .env 的 SCHEDULE_TIMES 语义一致)
DEFAULT_SCHEDULE_TZ = "Asia/Shanghai"


def schedule_tz() -> ZoneInfo:
    """调度时区(env SCHEDULE_TZ 可覆盖,默认 Asia/Shanghai)。"""
    return ZoneInfo(os.environ.get("SCHEDULE_TZ") or DEFAULT_SCHEDULE_TZ)


def now() -> datetime:
    """当前时刻(调度时区,aware)。"""
    return datetime.now(schedule_tz())


def today_str() -> str:
    """按调度时区返回今天的 YYYYMMDD。"""
    return now().strftime("%Y%m%d")