[REFACTOR] 글로벌 타임 UTC 표준화 (Date/Time UTC Migration)

[zzmnxn]

1. 배경 및 목적 (Context)

현재 프로젝트는 한국 시간(KST)에 종속되어 있어, 글로벌 서비스 확장 시 데이터 정합성 문제가 발생할 수 있습니다. 이를 해결하기 위해 "Back-end는 절대 시간(UTC), Front-end는 상대 시간(Local)" 원칙을 도입합니다.

• 현황: serverTimezone=Asia/Seoul 고정 및 LocalDateTime 사용 (타임존 정보 없음)
• 목표: 서버 및 DB는 표준시(UTC)만 취급하고, 사용자에게 보여주는 시점만 각자의 로컬 시간으로 변환합니다.

---

2. 역할별 핵심 변경 사항 (Action Items)

Front-end

프론트엔드는 서버에서 받은 UTC 시간을 사용자 기기 설정에 맞춰 변환하는 역할에 집중합니다.

• [삭제] 시간 입력값 제외: 일기 생성(CreateDiaryRequest) 시 dateTime 필드를 전송하지 않습니다. 서버가 요청 수신 시점을 기준으로 자동 생성합니다.
• [추가] 타임존 변환 로직: 서버 응답(Response DTO)으로 오는 ISO 8601 형식의 UTC 시간(예: 2024-05-20T10:00:00Z)을 브라우저/앱의 로컬 타임존으로 변환하여 노출해야 합니다.
• [참고] 스웨거 확인: API 문서상에서 삭제된 필드와 변경된 응답 포맷(끝에 Z가 붙는 형태)을 확인해 주세요.

Back-end (구현 세부 사항)

데이터의 저장 및 처리 신뢰성을 높이기 위해 서버 설정을 전면 수정합니다.

• 환경 설정: application.yml 내 serverTimezone을 UTC로 변경.

• 데이터 모델:

• Entity의 LocalDateTime 타입을 OffsetDateTime으로 변경.

• @PrePersist 등을 활용해 OffsetDateTime.now(ZoneOffset.UTC)로 시간 스탬프 자동화.

• 로직 수정: Trip 등의 도메인에서 LocalDate.now() 사용 시 반드시 UTC 기준임을 명시적으로 처리.

• API 문서화: Swagger Schema에 UTC 표준 사용 및 프론트엔드 변환 가이드를 주석으로 추가.

---

3. 기대 효과 (Benefits)

• 데이터 정합성: 전 세계 어디서 접속해도 동일한 시점의 데이터를 유지할 수 있습니다.
• 보안 및 신뢰성: 클라이언트가 임의로 생성 시간을 조작하는 것을 방지합니다.
• 인프라 독립성: 서버 호스팅 지역(IDC)의 시스템 시간 설정과 무관하게 일관된 서비스 운영이 가능합니다.

---

4. 체크리스트 (To-Do)

• DB 연결 설정(JDBC URL) serverTimezone=UTC 확인
• CreateDiaryRequest 내 dateTime 필드 삭제 및 컨트롤러 수정
• Diary, Trip 엔티티 필드 타입 및 생성 로직 변경
• API 응답 테스트 (끝에 Z가 포함된 ISO 8601 포맷 출력 여부)
• 스웨거(Swagger) 가이드 문구 업데이트

[zzmnxn]

UTC 작동 흐름

1. 백엔드: 요청 수신 시점 (UTC 생성)

프론트엔드 → POST /api/diaries
           ↓
DiaryService.createDiary()

// DiaryService.java:86
OffsetDateTime dateTime = OffsetDateTime.now(ZoneOffset.UTC);
// 예: 2024-12-20T10:30:00.000Z (UTC 기준)

• 클라이언트가 시간을 보내지 않음
• 서버가 요청 수신 시점을 UTC로 생성
• 서버 시스템 시간대와 무관하게 UTC로 고정

2. 엔티티: 자동 타임스탬프 생성 (UTC)

// Diary.java:63-68
@PrePersist
protected void onCreate() {
    if (this.createdAt == null) {
        this.createdAt = OffsetDateTime.now(ZoneOffset.UTC);
        // 예: 2024-12-20T10:30:00.000Z
    }
}

• @PrePersist: DB 저장 전 실행
• OffsetDateTime.now(ZoneOffset.UTC): UTC 기준 생성
• createdAt이 null이면 자동 설정

3. 데이터베이스: UTC로 저장

application.yml:6
serverTimezone=UTC

// MySQL에 저장되는 값
createdAt: 2024-12-20 10:30:00 (UTC 시간대로 저장)
dateTime: 2024-12-20 10:30:00 (UTC 시간대로 저장)

• JDBC URL의 serverTimezone=UTC 설정으로 MySQL에 UTC로 저장
• 서버/DB 인스턴스의 로컬 시간대와 무관하게 UTC 기준으로 저장

4. API 응답: UTC 정보 포함하여 반환

// DiaryResponseDto.java:34-39
@Schema(description = "일기 작성 날짜 및 시간 (UTC 기준, ISO-8601 형식). 
                      프론트엔드에서는 사용자의 로컬 타임존으로 변환하여 표시해야 합니다.", 
        example = "2024-05-20T10:00:00.000Z")
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX")
private final OffsetDateTime dateTime;

// API 응답 (JSON)
{
  "dateTime": "2024-12-20T10:30:00.000Z",  // ← Z = UTC 표시
  "createdAt": "2024-12-20T10:30:00.000Z"  // ← Z = UTC 표시
}

• @JsonFormat: ISO-8601 형식으로 직렬화
• "Z": UTC 표시 (예: +00:00)
• Swagger 문서에 UTC 명시 및 변환 가이드 포함

5. 프론트엔드: 로컬 시간으로 변환 (클라이언트 측)

// 프론트엔드 예시 (JavaScript)
const utcTime = "2024-12-20T10:30:00.000Z";  // 서버에서 받은 UTC 시간

// 브라우저/앱의 로컬 타임존으로 변환
const localTime = new Date(utcTime);
// 한국(KST, UTC+9): 2024-12-20 19:30:00
// 미국 뉴욕(EST, UTC-5): 2024-12-20 05:30:00
// 일본(JST, UTC+9): 2024-12-20 19:30:00

// 표시
console.log(localTime.toLocaleString());

• 프론트엔드는 변환만 담당
• 브라우저/앱의 타임존 설정에 따라 자동 변환
• 서버 시간은 항상 UTC로 고정

전체 흐름 요약

[사용자 액션]
  └─> 일기 작성 버튼 클릭 (한국 시간 19:30)
       ↓
[프론트엔드]
  └─> POST /api/diaries (dateTime 필드 없음)
       ↓
[백엔드 - DiaryService]
  └─> OffsetDateTime.now(ZoneOffset.UTC)
       → 생성 시간: 2024-12-20T10:30:00.000Z (UTC)
       ↓
[엔티티 - Diary @PrePersist]
  └─> createdAt = OffsetDateTime.now(ZoneOffset.UTC)
       → 2024-12-20T10:30:00.000Z
       ↓
[데이터베이스]
  └─> MySQL (serverTimezone=UTC)
       → 저장: 2024-12-20 10:30:00 (UTC 기준)
       ↓
[API 응답]
  └─> JSON: { "dateTime": "2024-12-20T10:30:00.000Z" }
       ↓
[프론트엔드]
  └─> new Date("2024-12-20T10:30:00.000Z")
       → 한국 사용자에게: "2024-12-20 19:30" (KST, UTC+9)
       → 미국 사용자에게: "2024-12-20 05:30" (EST, UTC-5)

핵심 포인트

1. 백엔드는 항상 UTC를 사용

   • 시간 생성: OffsetDateTime.now(ZoneOffset.UTC)
   • DB 저장: serverTimezone=UTC

2. 프론트엔드는 로컬 타임존으로 변환

   • 서버 응답의 UTC 시간을 사용자 기기의 로컬 시간으로 변환하여 표시

3. 일관된 기준으로 저장

   • 서버 위치와 무관하게 UTC로 통일
   • 표시는 각 사용자의 로컬 시간으로 변환

4. UTC 정보 보존

   • OffsetDateTime 사용으로 UTC 정보 유지
   • ISO-8601 형식 ("Z" 포함)으로 직렬화

이 방식으로 시간대 이슈 없이 일관된 시간을 저장하고 표시할 수 있습니다.