TimeMachine 도메인 비즈니스 규칙

1. 시간 관리 규칙

1.1 시간 표현 규칙

• 서버 내부 저장은 13자리 Unix 타임스탬프(밀리초) 형식 사용 (예: 1679471431000)
• 시간대(timezone)는 항상 UTC 기준으로 처리하되, 사용자별 Timezone ID를 명시적으로 저장하고 관리
• 클라이언트 응답 시에도 13자리 Unix 타임스탬프(밀리초) 형식으로 제공 (필요시 ZonedDateTime 객체 정보 포함)
• 테스터의 시간 설정 인터페이스(Web Chat 등)에서는 주로 치료 주기 일차(dayIndex)를 기준으로 시간을 지정
• 표시 시에는 사용자의 로컬 시간대로 변환하여 제공
• 날짜 범위 표현은 시작 시간과 종료 시간을 타임스탬프로 명확히 정의

1.2 시간 정확도 규칙

• 시스템 내부 처리는 밀리초(ms) 단위까지 정확도 보장
• 사용자 인터페이스에서는 상황에 따라 적절한 정확도로 표시 (날짜, 시간 등)
• 시간 비교 연산 시 정확도 손실을 고려하여 처리

1.3 시간 변환 규칙

• 다른 시간대 간 변환 시 일광 절약 시간제(DST) 고려 (@shared/utils 활용)
• 날짜 계산 시 윤년, 월별 일수 차이 등 고려 (@shared/utils 활용)
• 시간 단위 변환 시 정밀도 손실 최소화

2. 이벤트 시간 관리 규칙

2.1 이벤트 시간 속성 규칙

• 모든 이벤트는 다음 시간 속성을 포함해야 함
  • occurredAt: 이벤트가 실제로 발생한 시간
  • recordedAt: 시스템에 기록된 시간
  • validFrom: 이벤트가 유효해지는 시간
  • validUntil: 이벤트가 유효한 마지막 시간 (null인 경우 무기한 유효)
• 시간 속성은 명시적으로 설정되지 않은 경우 기본값 적용 (현재 시간 등)
• 시간 변경 관련 이벤트(VirtualTimeChanged 등) 페이로드에는 변경 전/후의 UTC 타임스탬프 및 해당 dayIndex 정보를 포함할 수 있음
• DayChanged 이벤트는 시스템 레벨 이벤트로, 날짜 변경 시점과 관련 컨텍스트 정보(자정 도달 vs 시간 조작)를 포함해야 함

2.2 이벤트 순서 규칙

• 이벤트 처리 순서는 occurredAt 시간을 기준으로 결정
• 동일 occurredAt 시간을 가진 이벤트는 recordedAt 시간으로 순서 결정
• 시스템은 시간 역전(time inversion) 감지 및 보정 메커니즘 제공

2.3 이벤트 시간 유효성 규칙

• occurredAt은 recordedAt보다 과거 시간이어야 함
• validFrom은 occurredAt 이후 시간이어야 함
• validUntil이 지정된 경우 validFrom 이후 시간이어야 함
• 미래 시간의 이벤트는 특별한 처리 필요 (예약 이벤트로 표시)

3. 날짜 변경 감지 및 시스템 이벤트 규칙

3.1 날짜 변경 감지 규칙

• 시스템은 자정 도달 또는 시간 조작으로 인한 날짜 변경을 자동으로 감지해야 함
• 날짜 변경 감지는 시스템 레벨에서 수행되며, 개별 사용자가 아닌 전체 시스템에 영향을 미침
• 날짜 변경 시 DayChanged 이벤트를 즉시 발행하여 다른 도메인의 일차별 로직을 트리거함
• 날짜 변경 감지 메커니즘은 실시간 성능을 보장해야 함 (100ms 이내 이벤트 발행)

3.2 DayChanged 이벤트 발행 규칙

• DayChanged 이벤트는 다음 상황에서 발행됨:
  • 자정 도달로 인한 자연스러운 날짜 변경
  • 시간 조작(가상 시간 설정)으로 인한 날짜 변경
• 이벤트 페이로드에는 날짜 변경의 원인(자정 도달 vs 시간 조작)을 명시해야 함
• 이벤트는 GCP Pub/Sub을 통해 발행되어 다른 도메인에서 구독 가능해야 함
• 이벤트 발행 실패 시 재시도 메커니즘을 적용해야 함

3.3 시스템 이벤트 처리 규칙

• DayChanged 이벤트는 컨텐츠 해금, rTIB 계산 등 일차별 로직을 트리거하는 시스템 이벤트임
• 다른 도메인에서는 이 이벤트를 구독하여 각자의 일차별 비즈니스 로직을 실행해야 함
• 이벤트 처리 순서와 의존성을 고려하여 적절한 순서로 처리되어야 함
• 이벤트 처리 실패 시 시스템 전체의 일관성에 영향을 줄 수 있으므로 에러 처리가 중요함

4. 가상 시간 설정 규칙 (dayIndex 기반)

4.1 시간 포인트 관리 규칙 (제거됨 - dayIndex 기반 설정으로 대체)

4.2 dayIndex 설정 규칙

• 가상 시간 설정은 TimeMachine 기능을 활성화하여 특정 dayIndex로 시스템 날짜를 변경하여 앱 기능을 테스트하는 것을 의미함
• 시간 설정 기준: 시간 변경은 사용자의 치료 주기 일차(dayIndex)를 기준으로 함 (절대 시간 지정 불가)
• dayIndex 유효 범위: 설정 가능한 dayIndex는 2 이상이어야 함 (1일차는 시작일 당일이므로, 과거 이동은 2일차부터 가능)
• 목표 날짜 계산: 목표 dayIndex에 해당하는 실제 날짜는 다음을 고려하여 계산됨:
  • 해당 사용자의 UserCycle 시작일
  • 사용자의 서비스 이용 중단/재개 이력 (중단 기간은 일차 계산에서 제외)
• 시간 설정 시각: 계산된 목표 날짜의 시작 시각 (00:00:00.000)으로 설정됨. 이때 사용자의 개별 Timezone ID가 적용됨.
• 권한: 시간 설정은 테스터 권한을 가진 사용자만 가능
• 환경 제한: 운영 환경에서는 기능 활성화 및 사용이 제한될 수 있음 (별도 정책 필요)
• 변경 이력: 모든 dayIndex 변경 및 그로 인한 시간 변경은 감사 로그 및 시간 변경 이력에 기록됨 (변경자, 사유, 변경 전/후 dayIndex 및 timestamp 포함)

4.3 TimeMachine 활성화 시 데이터 관리 규칙

• TimeMachine 활성화 시 데이터 관리는 다음 중 한 가지 방식 사용

  • 메타데이터 테이블 접근 방식:

    • 별도의 테스트 메타데이터 테이블에 테스트 정보 관리
    • 각 레코드의 ID와 생성 시간을 메타데이터 테이블에 매핑하여 테스트 데이터 식별
    • 장점: 기존 스키마 변경 필요 없음
    • 단점: 조회 시 조인 쿼리 필요

  • 스키마 분리 접근 방식:

    • TimeMachine 활성화 시 생성된 데이터는 프로덕션과 동일한 구조의 별도 스키마에 저장
    • TimeMachine 기능 활성화 시 테스트 스키마로 연결 전환
    • 장점: 데이터 완전 분리로 안전성 높음
    • 단점: 스키마 동기화 및 유지 관리 필요

  • 컨텍스트 기반 접근 방식:

    • 요청 컨텍스트에 사용자 ID 및 TimeMachine 활성화 상태 포함
    • 모든 데이터 액세스 계층이 컨텍스트를 확인하여 TimeMachine 활성화 상태 인식
    • 장점: 유연성, 기존 스키마 유지
    • 단점: 애플리케이션 코드 수정 필요

• TimeMachine 활성화 시 데이터 관리

  • 각 사용자는 독립적인 가상 시간과 데이터를 관리
  • 사용자 ID로 데이터 그룹화 및 격리
  • TimeMachine 활성화 시 생성된 데이터는 기본적으로 다른 사용자에게 보이지 않음

• TimeMachine 비활성화 시 데이터 처리

  • 기능 비활성화 시 해당 사용자의 가상 시간은 사용자의 Timezone 기준 현재 실제 날짜의 00:00으로 재설정됨
  • 재설정된 시간 이후에 생성된 모든 사용자 데이터는 영구 삭제됨 (기존 롤백 원칙 적용)

4.4 가상 시간 설정 성능 규칙

• 자주 접근하는 사용자의 가상 시간 정보는 캐싱하여 성능 최적화
• dayIndex -> 날짜 계산 로직은 성능 영향이 있을 수 있으므로 최적화 필요 (UserCycle 정보 조회 포함)
• 시간 설정 요청 처리 시간은 500ms 이내여야 함 (99번째 백분위수)
• 대규모 사용자에 대한 동시 시간 설정 요청 처리 능력 고려 (필요시)

5. 데이터 버전 관리 규칙

5.1 데이터 변경 추적 규칙

• 모든 엔티티는 변경 이력 추적을 위한 시간 속성 포함
  • createdAt: 생성 시간
  • updatedAt: 마지막 업데이트 시간
  • deletedAt: 삭제 시간 (soft delete용, null이면 활성 상태)
• 속성별 변경 이력 추적을 위한 메커니즘 제공
• 변경 주체(사용자 또는 시스템) 기록

5.2 데이터 버전 관리 규칙

• 주요 엔티티는 버전 번호로 관리
• 버전 번호는 변경 시마다 자동 증가
• 버전별 차이점을 조회할 수 있는 기능 제공
• 충돌 감지 및 해결 메커니즘 제공

5.3 데이터 일관성 규칙

• 특정 시점의 데이터는 해당 시점의 비즈니스 규칙을 따름
• 과거 데이터를 현재 규칙으로 검증하지 않음
• 시점 간 데이터 마이그레이션 시 변환 규칙 적용
• 데이터 정합성 검증은 해당 시점의 규칙 기준으로 수행
• 과거 시점 (낮은 dayIndex)으로 시간 이동 시, 해당 시점 이후의 데이터는 영구적으로 삭제되어야 함 (TimeMachine 롤백 정책)

6. 감사 및 규정 준수 규칙

6.1 감사 로그 규칙

• 모든 시간 관련 작업은 감사 로그에 기록
  • 시간 포인트 생성/삭제
  • 시간 여행 수행
  • 시간 관련 설정 변경
• 감사 로그는 변경 불가능(immutable)해야 함
• 감사 로그 항목에는 다음 정보 포함
  • 작업 유형
  • 수행 시간
  • 수행자
  • 영향 받은 데이터
  • 이전/이후 상태

6.2 규정 준수 규칙

• GDPR 요구사항에 따른 개인정보 처리 이력 관리
  • 개인정보 수집/사용/삭제 시점 기록
  • 동의 시점 및 범위 기록
  • 법적 보관 기간 준수
• 의료 데이터 관련 규제 준수
  • 의료 기록 변경 시 원본 보존
  • 변경 이력 완전 추적 가능
  • 접근 이력 기록

6.3 백업 및 보관 규칙

• 시간 포인트 데이터 정기 백업
• 백업 데이터 암호화 저장
• 백업에서 복원 시 시간 정확성 유지
• 법적 요구사항에 따른 데이터 보관 기간 준수

7. 성능 및 확장성 규칙

7.1 성능 최적화 규칙

• 시간 기반 쿼리 최적화를 위한 인덱싱 전략
  • 시간 범위 검색 최적화
  • 특정 시점 상태 조회 최적화
• 대용량 이력 데이터 처리를 위한 분할 전략
  • 시간 기반 샤딩
  • 콜드/핫 스토리지 분리

7.2 확장성 규칙

• 이벤트 소싱 패턴 적용으로 이력 관리 확장성 확보
• 시간 여행 기능의 분산 처리 지원
• 다중 리전 배포 시 시간 동기화 메커니즘 적용
• 데이터 볼륨 증가에 따른 자동 스케일링 지원

7.3 가용성 규칙

• 타임머신 서비스 가용성 목표: 99.9%
• 장애 상황에서도 현재 시점 데이터 접근성 보장
• 시간 여행 기능은 부하 상황에서 우선순위 낮춤
• 중요 시스템 이벤트의 시간 정확성 보장

8. 통합 인터페이스 규칙

8.1 API 규칙

• 시간 관련 파라미터 형식 통일
  • 서버에서 클라이언트로의 응답은 13자리 Unix 타임스탬프(밀리초) 형식 및/또는 ZonedDateTime 표현 사용
  • 시간 설정 요청 시 클라이언트(Web Chat 등)는 dayIndex를 주요 파라미터로 사용 (필요시 targetTimezoneId 포함)
  • 내부 API 간 통신도 13자리 Unix 타임스탬프(밀리초) 형식 사용
• 시간 관련 API 표준화
  • 특정 사용자 가상 시간 조회 엔드포인트
  • dayIndex 기반 시간 설정 엔드포인트
  • 시간 변경 이력 조회 엔드포인트
• API 버전 관리로 하위 호환성 보장

8.2 이벤트 스키마 규칙

• 모든 이벤트는 표준화된 시간 속성 포함
• 시간 변경 이벤트는 dayIndex 관련 정보 포함 가능
• 이벤트 스키마 변경 시 버전 관리
• 이벤트 스키마에 시간 메타데이터 섹션 포함
• 이벤트 간 시간 관계 표현을 위한 참조 메커니즘 제공

8.3 외부 시스템 통합 규칙

• 외부 시스템과 시간 동기화 메커니즘 구현
• 다른 시간대 사용 시스템과 통합 시 변환 규칙 적용
• 외부 이벤트 수신 시 내부 시간 체계로 정규화
• 시스템 간 시간 불일치 감지 및 해결 전략 적용