#!/usr/bin/env bash
# ==============================================================================
# 用途：時間戳與 log 格式的參考實作（bash 版）。對應 /jsc-shared:spec-time-log
#       規範：更新時間一律 Asia/Taipei、固定 yyyy/MM/dd HH:mm:ss；輸出訊息一律
#       [時間][階段][等級]: 訊息、一行一則、走 stderr。本檔案不會被其他 repo
#       跨 repo 直接 source／呼叫，純供其他 repo 的腳本對照複製或標註對應關係
#       （原始寫法見 doc/scripts/worklog/worklog.sh 第23-33行附近）。
# 更新時間：2026/08/11 00:00:00
# 相依：bash、coreutils date（需支援 TZ 環境變數）。
# ==============================================================================

# ------------------------------------------------------------------------------
# now_taipei：回傳 Asia/Taipei 時區的 yyyy/MM/dd HH:mm:ss 時間字串
# ------------------------------------------------------------------------------
now_taipei() {
  TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
}

# ------------------------------------------------------------------------------
# log：輸出統一格式訊息（[時間][階段][等級]: 訊息，一行一則），一律走 stderr
#   $1 = level（INF/WRN/ERR/TRC/DBG）
#   $2 = message
#   $3 = stage（選填；空則不輸出 [階段] 區塊）
# ------------------------------------------------------------------------------
log() {
  local level="$1" message="$2" stage="${3:-}" stamp
  stamp="$(now_taipei)"
  if [ -n "$stage" ]; then
    printf '[%s][%s][%s]: %s\n' "$stamp" "$stage" "$level" "$message" >&2
  else
    printf '[%s][%s]: %s\n' "$stamp" "$level" "$message" >&2
  fi
}