# UTC Aware DateTime 처리 전략

## 작성일: 2025-08-28
## 작성자: 서버 관리자
## 카테고리: 아이디어/베스트 프랙티스

---

## 배경
- Gmail 토큰 만료 체크 시 `can't subtract offset-naive and offset-aware datetimes` 오류 발생
- 타임존 혼용으로 인한 반복적인 버그 발생 (250819, 250828 사례)

## 핵심 전략: 내부 UTC, 외부 KST

### 1. 저장 및 처리 (UTC)
```python
# 모든 DB 저장은 UTC
expires_at = datetime.now(timezone.utc) + timedelta(hours=1)

# 비교도 UTC로 통일
if datetime.now(timezone.utc) > expires_at:
    refresh_token()
```

### 2. 한국 시간 이벤트 처리
```python
from zoneinfo import ZoneInfo

def is_kst_hour(hour: int) -> bool:
    """KST 특정 시간 체크 (예: 9시 브리핑)"""
    return datetime.now(ZoneInfo("Asia/Seoul")).hour == hour

def kst_to_utc(kst_hour: int) -> datetime:
    """KST 시간을 UTC로 변환"""
    kst_now = datetime.now(ZoneInfo("Asia/Seoul"))
    kst_target = kst_now.replace(hour=kst_hour, minute=0, second=0)
    return kst_target.astimezone(timezone.utc)
```

### 3. 범용 변환 함수
```python
def to_utc_aware(dt_str: str) -> datetime:
    """모든 datetime 문자열을 UTC aware로 통일"""
    if not dt_str:
        return None
    dt = datetime.fromisoformat(dt_str.replace('Z', '+00:00'))
    return dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt
```

## 적용 원칙
1. **DB Schema**: TIMESTAMP WITH TIME ZONE 사용 권장
2. **API Response**: ISO 8601 with Z suffix (예: `2025-08-28T00:00:00Z`)
3. **Cron Jobs**: 서버 타임존(KST) 기준, 코드에서 UTC 변환
4. **Frontend Display**: 사용자 로컬 시간으로 표시

## 기대 효과
- ✅ naive/aware datetime 충돌 완전 방지
- ✅ 글로벌 서비스 확장 시 타임존 이슈 없음
- ✅ 코드 일관성 및 유지보수성 향상