"""Tiện ích hiển thị giờ Việt Nam (GMT+7) cho thông báo gửi tới người dùng.

Vì sao cần module này:
    Container Cloud (Docker, python:3.11-slim) chạy múi giờ UTC, nên `datetime.now()`
    trả về giờ UTC dạng naive. Email cảnh báo từng ghi "01:18" trong khi thực tế là
    08:18 sáng giờ VN, khiến người dùng hiểu nhầm sự cố xảy ra lúc nửa đêm.

Nguyên tắc:
    - Chỉ dùng cho HIỂN THỊ (email, Telegram, message trả về UI).
    - Giá trị lưu DB / so sánh logic vẫn giữ ISO-8601 UTC như cũ.
    - Việt Nam không áp dụng giờ mùa hè -> dùng offset cố định UTC+7, không phụ thuộc
      gói `tzdata` (image slim có thể thiếu /usr/share/zoneinfo).
"""

from __future__ import annotations

from datetime import datetime, timedelta, timezone

VN_TZ = timezone(timedelta(hours=7), name="GMT+7")
VN_TZ_LABEL = "(GMT+7)"


def _to_vn(value: datetime | str | None) -> datetime | None:
    """Quy đổi về giờ VN.

    - None            -> thời điểm hiện tại.
    - datetime naive  -> coi là giờ hệ thống của máy đang chạy (UTC trên Cloud,
                         GMT+7 trên máy dev Windows) rồi quy đổi.
    - datetime aware  -> quy đổi trực tiếp.
    - str ISO-8601    -> parse (hỗ trợ hậu tố 'Z'); chuỗi không hợp lệ -> None.
    """
    if value is None:
        return datetime.now(VN_TZ)
    if isinstance(value, str):
        try:
            value = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
        except ValueError:
            return None
    return value.astimezone(VN_TZ)


def format_vn_time(value: datetime | str | None = None) -> str:
    """Định dạng 'dd/mm/YYYY HH:MM:SS (GMT+7)'. Chuỗi không parse được trả về nguyên văn."""
    vn_dt = _to_vn(value)
    if vn_dt is None:
        return str(value)
    return f"{vn_dt.strftime('%d/%m/%Y %H:%M:%S')} {VN_TZ_LABEL}"


def format_vn_clock(value: datetime | str | None = None) -> str:
    """Định dạng giờ:phút 'HH:MM' theo giờ VN (dùng cho nhãn khung giờ chạy)."""
    vn_dt = _to_vn(value)
    if vn_dt is None:
        return str(value)
    return vn_dt.strftime("%H:%M")