時區處理技術完全指南：從 UTC 到本地時間Complete Timezone Handling Guide: From UTC to Local Time

IANA 時區命名格式IANA Timezone Naming Format

格式: Area/Location
範例:
  - Asia/Taipei          # 台北（UTC+8，無夏令時）
  - America/New_York     # 紐約（EST UTC-5 / EDT UTC-4）
  - Europe/London        # 倫敦（GMT UTC+0 / BST UTC+1）
  - Australia/Sydney     # 雪梨（AEST UTC+10 / AEDT UTC+11）
  - Pacific/Auckland     # 奧克蘭（NZST UTC+12 / NZDT UTC+13）

特殊時區:
  - UTC                  # 協調世界時
  - Etc/GMT+5            # ⚠️ 注意：Etc/GMT+5 實際是 UTC-5（符號相反！）Format: Area/Location
Examples:
  - Asia/Taipei          # Taipei (UTC+8, no DST)
  - America/New_York     # New York (EST UTC-5 / EDT UTC-4)
  - Europe/London        # London (GMT UTC+0 / BST UTC+1)
  - Australia/Sydney     # Sydney (AEST UTC+10 / AEDT UTC+11)
  - Pacific/Auckland     # Auckland (NZST UTC+12 / NZDT UTC+13)

Special timezones:
  - UTC                  # Coordinated Universal Time
  - Etc/GMT+5            # ⚠️ Note: Etc/GMT+5 is actually UTC-5 (signs are reversed!)

範例：2025 年美國夏令時轉換

春季轉換（3月第二個週日 2:00 AM）：
  2025-03-09 01:59:59 → 2025-03-09 03:00:00
  ⚠️ 2:00-3:00 之間的時間不存在！

  // 錯誤：嘗試建立不存在的時間
  new Date(2025, 2, 9, 2, 30) // 會被自動調整為 3:30

秋季轉換（11月第一個週日 2:00 AM）：
  2025-11-02 01:59:59 → 2025-11-02 01:00:00（第二次）
  ⚠️ 1:00-2:00 會經歷兩次！

  // 問題：1:30 AM 是第一次還是第二次？
  // 需要額外資訊（UTC offset）來區分

// 方法 1：顯示特定時區的時間
function formatInTimezone(date, timezone) {
  return new Intl.DateTimeFormat('zh-TW', {
    timeZone: timezone,
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    hour12: false
  }).format(date);
}

const now = new Date();
console.log(formatInTimezone(now, 'Asia/Taipei'));
// 輸出: "2025/01/27 14:00:00"

console.log(formatInTimezone(now, 'America/New_York'));
// 輸出: "2025/01/27 01:00:00"

// 方法 2：取得時區偏移量
function getTimezoneOffset(date, timezone) {
  const utcDate = new Date(date.toLocaleString('en-US', { timeZone: 'UTC' }));
  const tzDate = new Date(date.toLocaleString('en-US', { timeZone: timezone }));
  return (tzDate.getTime() - utcDate.getTime()) / (60 * 1000); // 分鐘
}

console.log(getTimezoneOffset(new Date(), 'Asia/Taipei'));
// 輸出: 480 （480分鐘 = 8小時）

// 方法 3：檢測夏令時
function isDST(date, timezone) {
  const jan = new Date(date.getFullYear(), 0, 1);
  const jul = new Date(date.getFullYear(), 6, 1);
  const janOffset = getTimezoneOffset(jan, timezone);
  const julOffset = getTimezoneOffset(jul, timezone);
  const currentOffset = getTimezoneOffset(date, timezone);

  // 當前偏移與最大偏移不同時，表示處於 DST
  return currentOffset !== Math.max(janOffset, julOffset);
}

console.log(isDST(new Date('2025-07-01'), 'America/New_York')); // true
console.log(isDST(new Date('2025-01-01'), 'America/New_York')); // false

// 方法 4：取得時區縮寫
function getTimezoneAbbr(date, timezone) {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone: timezone,
    timeZoneName: 'short'
  }).formatToParts(date);

  const abbr = parts.find(part => part.type === 'timeZoneName');
  return abbr ? abbr.value : '';
}

console.log(getTimezoneAbbr(new Date('2025-01-01'), 'America/New_York')); // "EST"
console.log(getTimezoneAbbr(new Date('2025-07-01'), 'America/New_York')); // "EDT"

// 安裝: npm install luxon
import { DateTime } from 'luxon';

// 建立特定時區的時間
const dt = DateTime.fromObject(
  { year: 2025, month: 1, day: 27, hour: 14 },
  { zone: 'Asia/Taipei' }
);

console.log(dt.toISO());
// 輸出: "2025-01-27T14:00:00.000+08:00"

// 轉換時區
const ny = dt.setZone('America/New_York');
console.log(ny.toFormat('yyyy-MM-dd HH:mm:ss'));
// 輸出: "2025-01-27 01:00:00"

// 取得時區資訊
console.log(dt.offsetNameShort);  // "CST"
console.log(dt.offset);            // 480 (分鐘)
console.log(dt.isInDST);           // false

// 安全處理 DST 轉換日
const springForward = DateTime.fromObject(
  { year: 2025, month: 3, day: 9, hour: 2, minute: 30 },
  { zone: 'America/New_York' }
);

console.log(springForward.toFormat('HH:mm'));
// 輸出: "03:30" （自動調整為 3:30，因為 2:30 不存在）

console.log(springForward.invalid);
// 輸出: null （Luxon 自動修正，不會拋出錯誤）

from datetime import datetime
from zoneinfo import ZoneInfo

# 建立帶時區的 datetime
dt = datetime(2025, 1, 27, 14, 0, 0, tzinfo=ZoneInfo('Asia/Taipei'))
print(dt)
# 輸出: 2025-01-27 14:00:00+08:00

# 轉換時區
ny_dt = dt.astimezone(ZoneInfo('America/New_York'))
print(ny_dt)
# 輸出: 2025-01-27 01:00:00-05:00

# 取得當前 UTC 時間
utc_now = datetime.now(ZoneInfo('UTC'))
print(utc_now)

# 轉換為不同時區
taipei_now = utc_now.astimezone(ZoneInfo('Asia/Taipei'))
london_now = utc_now.astimezone(ZoneInfo('Europe/London'))

print(f"台北: {taipei_now.strftime('%Y-%m-%d %H:%M:%S %Z')}")
print(f"倫敦: {london_now.strftime('%Y-%m-%d %H:%M:%S %Z')}")

# 檢測夏令時
def is_dst(dt):
    return bool(dt.dst())

summer = datetime(2025, 7, 1, tzinfo=ZoneInfo('America/New_York'))
winter = datetime(2025, 1, 1, tzinfo=ZoneInfo('America/New_York'))

print(f"7月是否為DST: {is_dst(summer)}")  # True
print(f"1月是否為DST: {is_dst(winter)}")  # False

# 安裝: pip install pytz
from datetime import datetime
import pytz

# ⚠️ pytz 需要使用 localize() 而非直接傳入 tzinfo
taipei = pytz.timezone('Asia/Taipei')

# ❌ 錯誤方式（會有問題）
dt_wrong = datetime(2025, 1, 27, 14, 0, 0, tzinfo=taipei)

# ✅ 正確方式
dt_correct = taipei.localize(datetime(2025, 1, 27, 14, 0, 0))

# 轉換時區
ny_tz = pytz.timezone('America/New_York')
ny_dt = dt_correct.astimezone(ny_tz)

print(dt_correct)  # 2025-01-27 14:00:00+08:00
print(ny_dt)       # 2025-01-27 01:00:00-05:00

# 處理 DST 轉換日（重複時間）
eastern = pytz.timezone('America/New_York')

# 2025-11-02 01:30 會經歷兩次，需要 is_dst 參數指定
dt_first = eastern.localize(datetime(2025, 11, 2, 1, 30), is_dst=True)   # DST 期間
dt_second = eastern.localize(datetime(2025, 11, 2, 1, 30), is_dst=False)  # 標準時間

print(f"第一次 1:30: {dt_first} (offset: {dt_first.strftime('%z')})")
print(f"第二次 1:30: {dt_second} (offset: {dt_second.strftime('%z')})")

// ✅ 好的 API 設計
{
  "event_id": "evt_123",
  "created_at": "2025-01-27T06:00:00Z",           // ISO 8601, UTC
  "scheduled_at": "2025-02-01T02:00:00Z",         // UTC 時間
  "scheduled_timezone": "America/New_York",       // 原始時區（可選）
  "scheduled_local_time": "2025-01-31T21:00:00",  // 本地時間（可選）
  "user_timezone": "Asia/Taipei"                  // 使用者時區（可選）
}

// ❌ 不好的 API 設計
{
  "created_at": "2025-01-27 14:00:00",  // 沒有時區資訊！
  "scheduled_at_taipei": "2025-02-01 10:00:00",
  "scheduled_at_newyork": "2025-01-31 21:00:00"  // 冗餘，難以維護
}