#!/usr/bin/env python3
# ==============================================================================
# 用途：時間戳與 log 格式的參考實作（Python 版）。對應 /jsc-shared:spec-time-log
#       規範：更新時間一律 Asia/Taipei、固定 yyyy/MM/dd HH:mm:ss（以
#       zoneinfo.ZoneInfo 取得，不硬編 +8 offset，正確處理 DST／歷史時區變更）；
#       輸出訊息一律 [時間][階段][等級]: 訊息、一行一則、走 stderr。本檔案不會
#       被其他 repo 跨 repo 直接 import，純供其他 repo 的腳本對照複製或標註
#       對應關係（原始寫法見 doc/scripts/worklog/wiki_api.py 的 now_str()／log()）。
# 更新時間：2026/08/11 00:00:00
# 相依：Python 3 標準庫（zoneinfo、datetime）。
# ==============================================================================

import sys
from datetime import datetime
from zoneinfo import ZoneInfo

TAIPEI = ZoneInfo("Asia/Taipei")


def now_taipei():
    """取得台灣時區的 yyyy/MM/dd HH:mm:ss 時間字串。"""
    return datetime.now(TAIPEI).strftime("%Y/%m/%d %H:%M:%S")


def log(level, message, stage=""):
    """輸出統一格式訊息（[時間][階段][等級]: 訊息，一行一則），一律走 stderr 不污染 stdout。"""
    if stage:
        print(f"[{now_taipei()}][{stage}][{level}]: {message}", file=sys.stderr)
    else:
        print(f"[{now_taipei()}][{level}]: {message}", file=sys.stderr)