본문으로 건너뛰기

endpoints

관련 문서​

TimeMachine API 엔드포인트

목차​

1. 엔드포인트 접근 권한 매트릭스​

엔드포인트System AdminTesterRegular User
GET /v1/time-machine/time✓✓✓
POST /v1/time-machine/time✓✓✘
POST /v1/time-machine/time/day-index✓✓✘
POST /v1/time-machine/time/reset✓✓✘
GET /v1/time-machine/time/history✓✓자신만
GET /v1/time-machine/users/{userId}/time✓✓자신만
POST /v1/time-machine/users/{userId}/time✓✓✘
POST /v1/time-machine/users/{userId}/time/day-index✓✓✘
POST /v1/time-machine/users/{userId}/time/suspension-day✓✓✘
GET /v1/time-machine/users/time✓✓✘
GET /v1/time-machine/users/{userId}/status✓✓자신만
PATCH /v1/time-machine/users/{userId}/enable✓✓✘
PATCH /v1/time-machine/users/{userId}/disable✓✓✘
PATCH /v1/time-machine/enable✓✓자신만
PATCH /v1/time-machine/disable✓✓자신만
GET /v1/time-machine/status✓✓자신만
GET /v1/time-machine/rollback/history✓✓✘
GET /v1/time-machine/users/{userId}/rollback/history✓✓자신만
GET /v1/time-machine/events/history✓✓✘
POST /v1/time-machine/events/{eventId}/retry✓✓✘

참고:

  • ✓: 접근 가능
  • ✘: 접근 불가
  • 자신만: 자신의 데이터에만 접근 가능

2. 가상 시간 관리 API​

📌 기술 구현 문서: 가상 시간 구현 가이드 | 가상 시간 명세

가상 시간 관리 API는 시스템의 현재 시간을 가상으로 조작하여 테스트에 활용할 수 있는 기능을 제공합니다. 테스터는 특정 시점으로 이동하거나, 특정 일차로 이동하여 시간에 민감한 기능을 테스트할 수 있습니다.

2.1 가상 시간 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/time
  • 설명: 현재 사용자의 가상 시간을 조회합니다.
  • 권한: 모든 사용자

요청 (Request)​

헤더에 인증 토큰이 필요합니다.

Authorization: Bearer `{accessToken}`

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "currentTime": 1715123456789,
  "active": true,
  "lastChangeTimestamp": 1715023456789
}
  • 오류 응답 (401 Unauthorized)
{
  "code": 1001,
  "message": "INVALID_AUTH_TOKEN",
  "detail": "인증 토큰이 유효하지 않습니다."
}

2.2 가상 시간 변경​

  • HTTP 메서드: POST
  • 경로: /v1/time-machine/time
  • 설명: 가상 시간을 특정 날짜/시간으로 변경합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "newTime": 1715223456789,
  "reason": "특정 기능 테스트를 위한 시간 변경"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "previousTime": 1715123456789,
  "currentTime": 1715223456789,
  "changeTimestamp": 1715023456789,
  "eventPublished": true
}
  • 오류 응답 (403 Forbidden)
{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "시간 변경 권한이 없습니다."
}

2.3 특정 일차로 이동​

  • HTTP 메서드: POST
  • 경로: /v1/time-machine/time/day-index
  • 설명: 특정 일차(dayIndex)로 시간을 이동합니다. 해당 날짜의 00:00으로 설정됩니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "dayIndex": 30, // 이동할 치료 주기 일차 (2 이상)
  "reason": "30일차 기능 테스트를 위한 시간 변경"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "previousTime": 1715123456789,
  "currentTime": 1717123456789,
  "dayIndex": 30,
  "changeTimestamp": 1715023456789,
  "eventPublished": true
}
  • 오류 응답 (400 Bad Request)
{
  "code": 1002,
  "message": "INVALID_DAY_INDEX",
  "detail": "유효하지 않은 dayIndex입니다."
}

2.4 가상 시간 설정 (dayIndex 기반)​

  • 엔드포인트: POST /v1/time-machine/users/{userId}/time/day-index
  • 설명: 특정 사용자의 가상 시간을 지정된 치료 주기 일차(dayIndex)에 해당하는 날짜의 시작(00:00)으로 설정합니다. 사용자의 주기 시작일 및 중단 이력을 고려하여 실제 날짜가 계산됩니다. dayIndex는 2 이상이어야 합니다.
  • 권한: ADMIN, TESTER
  • 파라미터:
    • userId (Path, string, 필수): 대상 사용자 ID
  • 요청 본문: SetUserVirtualTimeByDayIndexDto 
    {
      "dayIndex": 10, // 설정할 치료 주기 일차 (2 이상)
      "timezoneId": "Europe/Berlin", // 설정할 타임존 ID (선택적, 생략 시 사용자 기본값 사용)
      "reason": "10일차 시나리오 테스트" // 변경 사유
    }
  • 성공 응답 (200 OK): UserVirtualTimeChangeResultDto 
    {
      "userId": "user-uuid-123",
      "previousTime": 1679385600000, // 이전 가상 시간 (UTC ms)
      "previousTimezoneId": "Asia/Seoul",
      "previousLocalTimeString": "2023-03-21 09:00:00",
      "currentTime": 1679497200000, // 현재 가상 시간 (UTC ms, 계산된 날짜 00:00 기준)
      "currentTimezoneId": "Europe/Berlin",
      "currentLocalTimeString": "2023-03-22 08:00:00", // Berlin 기준 00:00에 해당
      // "previousDayIndex": 5, // 이전 dayIndex (선택적 추가 가능)
      // "currentDayIndex": 10, // 현재 dayIndex (선택적 추가 가능)
      "changeTimestamp": 1679471500000, // 변경 작업 시점 (UTC ms)
      "wasActive": true,
      "isActive": true,
      "eventPublished": true // 날짜 변경 이벤트 발행 여부
    }
  • 실패 응답:
    • 400 Bad Request: 잘못된 요청 (예: dayIndex < 2, 유효하지 않은 timezoneId)
    • 403 Forbidden: 권한 부족
    • 404 Not Found: 사용자를 찾을 수 없음, UserCycle 정보를 찾을 수 없음
    • 500 Internal Server Error: 날짜 계산 오류, DB 오류 등

2.5 가상 시간 설정 (일시 정지 기간 내 날짜 기반)​

  • 엔드포인트: POST /v1/time-machine/users/{userId}/time/suspension-day
  • 설명: 특정 사용자의 가상 시간을 지정된 치료 활동 일시 정지 기간 내의 특정 날짜의 시작(00:00)으로 설정합니다. 사용자의 UserSuspensionHistory를 참조하여 실제 날짜가 계산됩니다.
  • 권한: ADMIN, TESTER
  • 파라미터:
    • userId (Path, string, 필수): 대상 사용자 ID
  • 요청 본문: SetUserVirtualTimeBySuspensionDayDto 
    {
      "suspensionSequence": 2, // 몇 번째 일시 정지 기간인지 (1부터 시작)
      "dayWithinSuspension": 3, // 해당 정지 기간 내에서 몇 번째 날인지 (1부터 시작)
      "reason": "두 번째 정지 기간 3일차 시나리오 테스트"
    }
  • 성공 응답 (200 OK): UserVirtualTimeChangeResultDto (기존 dayIndex 응답과 유사) 
    {
      "userId": "user-uuid-456",
      "previousTime": 1680000000000, // 이전 가상 시간 (UTC ms)
      "previousTimezoneId": "Asia/Seoul",
      "previousLocalTimeString": "2023-03-28 17:00:00",
      "currentTime": 1680580800000, // 현재 가상 시간 (UTC ms, 계산된 날짜 00:00 기준)
      "currentTimezoneId": "America/New_York",
      "currentLocalTimeString": "2023-04-03 20:00:00", // New York 기준 00:00에 해당
      "changeTimestamp": 1680570000000, // 변경 작업 시점 (UTC ms)
      "wasActive": true,
      "isActive": true,
      "eventPublished": true // 날짜 변경 이벤트 발행 여부
    }
  • 실패 응답:
    • 400 Bad Request: 잘못된 요청 (예: suspensionSequence <= 0, dayWithinSuspension <= 0, 존재하지 않는 정지 순서, 정지 기간 내 유효하지 않은 날짜, 유효하지 않은 timezoneId)
    • 403 Forbidden: 권한 부족
    • 404 Not Found: 사용자를 찾을 수 없음, UserSuspensionHistory 정보를 찾을 수 없음
    • 500 Internal Server Error: 날짜 계산 오류, DB 오류 등

2.6 가상 시간 리셋 (실제 시간으로)​

  • HTTP 메서드: POST
  • 경로: /v1/time-machine/time/reset
  • 설명: 가상 시간을 실제 시간으로 재설정합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "reason": "테스트 완료 후 시간 재설정"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "previousTime": 1715123456789,
  "currentTime": 1715023456789,
  "changeTimestamp": 1715023456789,
  "eventPublished": true
}

2.7 시간 변경 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/time/history
  • 설명: 시간 변경 이력을 조회합니다.
  • 권한: 시스템 관리자, 테스터, 일반 사용자(자신의 이력만)

요청 (Request)​

- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 10)
- fromDate: 시작 날짜 (선택 사항)
- toDate: 종료 날짜 (선택 사항)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "1234567890",
      "previousTime": 1715123456789,
      "newTime": 1715223456789,
      "changeType": "SET",
      "timestamp": 1715023456789,
      "changedById": "user123",
      "changedByName": "테스터 사용자",
      "reason": "특정 기능 테스트를 위한 시간 변경"
    },
    {
      "id": "1234567891",
      "previousTime": 1715223456789,
      "newTime": 1717123456789,
      "changeType": "MOVE_FORWARD",
      "timestamp": 1715024456789,
      "changedById": "user123",
      "changedByName": "테스터 사용자",
      "reason": "30일차 기능 테스트를 위한 시간 변경"
    },
    {
      "id": "1234567892",
      "previousTime": 1717123456789,
      "newTime": 1717555200000, // 예시: 정지 기간 내 시간으로 설정
      "changeType": "SET_BY_SUSPENSION_DAY", // 새로운 변경 유형 추가
      "changeDetails": {
        "suspensionSequence": 1,
        "dayWithinSuspension": 5
      },
      "timestamp": 1715025456789,
      "changedById": "user123",
      "changedByName": "테스트 사용자",
      "reason": "첫 번째 정지 기간 5일차 테스트"
    }
  ],
  "metadata": {
    "totalCount": 25,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 3
  }
}

3. 사용자별 가상 시간 관리 API​

📌 기술 구현 문서: 사용자별 가상 시간 명세 | 사용자별 가상 시간 구현 가이드

사용자별 가상 시간 관리 API는 테스터가 특정 사용자의 가상 시간을 개별적으로 관리하고 조작할 수 있는 기능을 제공합니다. 각 사용자는 독립적인, 테스트 전용 가상 시간을 가질 수 있습니다.

3.1 사용자 가상 시간 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/users/{userId}/time
  • 설명: 특정 사용자의 가상 시간을 조회합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user123",
  "currentTime": 1715123456789,
  "active": true,
  "lastChangeTimestamp": 1715023456789,
  "changedById": "tester456"
}

3.2 사용자 가상 시간 변경​

  • HTTP 메서드: POST
  • 경로: /v1/time-machine/users/{userId}/time
  • 설명: 특정 사용자의 가상 시간을 변경합니다. 사용자의 현재 가상 시간 날짜를 기준으로 지정된 시간으로 설정됩니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "newTime": "21:30",
  "reason": "특정 사용자 테스트를 위한 시간 변경"
}

필드 설명:

  • newTime (string, 필수): 설정할 시간을 HH:mm 형식으로 지정 (예: "09:30", "14:15", "23:45")
  • reason (string, 선택): 시간 변경 사유

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user123",
  "previousTime": 1715123456789,
  "previousTimezoneId": "Asia/Seoul",
  "previousLocalTimeString": "2025-07-27 14:30:00",
  "currentTime": 1715223456789,
  "currentTimezoneId": "Asia/Seoul", 
  "currentLocalTimeString": "2025-07-27 21:30:00",
  "changeTimestamp": 1715023456789,
  "wasActive": true,
  "isActive": true,
  "eventPublished": true
}

응답 필드 설명:

  • userId: 대상 사용자 ID
  • previousTime: 이전 가상 시간 (UTC timestamp, 밀리초)
  • previousTimezoneId: 이전 시간의 타임존 ID
  • previousLocalTimeString: 이전 시간의 로컬 표현 (YYYY-MM-DD HH:mm:ss 형식)
  • currentTime: 현재 가상 시간 (UTC timestamp, 밀리초)
  • currentTimezoneId: 현재 시간의 타임존 ID
  • currentLocalTimeString: 현재 시간의 로컬 표현 (YYYY-MM-DD HH:mm:ss 형식)
  • changeTimestamp: 변경 작업 시점 (UTC timestamp, 밀리초)
  • wasActive: 이전 TimeMachine 활성화 상태
  • isActive: 현재 TimeMachine 활성화 상태
  • eventPublished: 시간 변경 이벤트 발행 여부

3.3 모든 사용자 가상 시간 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/users/time
  • 설명: 모든 사용자의 가상 시간 정보를 조회합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 20)
- active: TimeMachine 활성화 상태로 필터링 (선택 사항)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "userId": "user123",
      "userName": "테스트 사용자1",
      "currentTime": 1715123456789,
      "active": true,
      "lastChangeTimestamp": 1715023456789
    },
    {
      "userId": "user456",
      "userName": "테스트 사용자2",
      "currentTime": 1714123456789,
      "active": true,
      "lastChangeTimestamp": 1715021456789
    }
  ],
  "metadata": {
    "totalCount": 45,
    "currentPage": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

4. TimeMachine 기능 관리 API​

📌 기술 구현 문서: TimeMachine 기능 관리 구현 가이드 | TimeMachine 기능 관리 명세

TimeMachine 기능 관리 API는 사용자별로 타임머신 기능의 활성화/비활성화를 제어하고, 상태를 조회하는 기능을 제공합니다. 이를 통해 테스트 기간 동안 타임머신을 사용하고, 테스트 완료 후 실제 시간으로 전환할 수 있습니다.

4.1 TimeMachine 기능 활성화​

  • HTTP 메서드: PATCH
  • 경로: /v1/time-machine/enable
  • 설명: 사용자의 TimeMachine 기능을 활성화합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

요청 (Request)​

{
  "reason": "테스트 목적으로 TimeMachine 활성화"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "active": true,
  "activatedAt": 1715023456789,
  "eventPublished": true
}
  • 오류 응답 (409 Conflict)
{
  "code": 1007,
  "message": "TIMEMACHINE_ALREADY_ENABLED",
  "detail": "이미 TimeMachine이 활성화되어 있습니다."
}

4.2 TimeMachine 기능 비활성화​

  • HTTP 메서드: PATCH
  • 경로: /v1/time-machine/disable
  • 설명: 사용자의 TimeMachine 기능을 비활성화합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

요청 (Request)​

{
  "reason": "테스트 완료 후 TimeMachine 비활성화"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "active": false,
  "deactivatedAt": 1715023456789,
  "futureDataCleared": true,
  "eventPublished": true
}
  • 오류 응답 (409 Conflict)
{
  "code": 1008,
  "message": "TIMEMACHINE_ALREADY_DISABLED",
  "detail": "이미 TimeMachine이 비활성화되어 있습니다."
}

4.3 TimeMachine 상태 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/status
  • 설명: 사용자의 TimeMachine 활성화 상태를 조회합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "active": true,
  "lastActivatedAt": 1715023456789,
  "lastDeactivatedAt": 1714923456789,
  "currentTime": 1715123456789
}

4.4 특정 사용자 TimeMachine 상태 조회 (관리자용)​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/users/{userId}/status
  • 설명: 특정 사용자의 TimeMachine 활성화 상태를 조회합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user-uuid-123",
  "isActive": true,
  "lastChangeTimestamp": 1715023456789,
  "changedBy": "admin-uuid-456",
  "changeReason": "Testing purposes",
  "currentVirtualTime": 1715123456789,
  "timezoneId": "Asia/Seoul"
}
  • 오류 응답 (403 Forbidden)
{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "권한 부족"
}
  • 오류 응답 (404 Not Found)
{
  "code": 1006,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없음"
}

4.5 특정 사용자 TimeMachine 활성화 (관리자용)​

  • HTTP 메서드: PATCH
  • 경로: /v1/time-machine/users/{userId}/enable
  • 설명: 특정 사용자의 TimeMachine을 활성화합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "reason": "테스트 목적으로 TimeMachine 활성화"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user-uuid-123",
  "isActive": true,
  "lastChangeTimestamp": 1715023456789,
  "changedBy": "admin-uuid-456",
  "changeReason": "테스트 목적으로 TimeMachine 활성화",
  "currentVirtualTime": 1715123456789,
  "timezoneId": "Asia/Seoul"
}
  • 오류 응답 (403 Forbidden)
{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "권한 부족"
}
  • 오류 응답 (404 Not Found)
{
  "code": 1006,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없음"
}
  • 오류 응답 (409 Conflict)
{
  "code": 1007,
  "message": "TIMEMACHINE_ALREADY_ENABLED",
  "detail": "이미 TimeMachine이 활성화되어 있습니다."
}

4.6 특정 사용자 TimeMachine 비활성화 (관리자용)​

  • HTTP 메서드: PATCH
  • 경로: /v1/time-machine/users/{userId}/disable
  • 설명: 특정 사용자의 TimeMachine을 비활성화합니다. 가상 시간은 실제 시간으로 재설정되고 미래 데이터는 삭제됩니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

{
  "reason": "테스트 완료 후 TimeMachine 비활성화"
}

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "userId": "user-uuid-123",
  "isActive": false,
  "lastChangeTimestamp": 1715023456789,
  "changedBy": "admin-uuid-456",
  "changeReason": "테스트 완료 후 TimeMachine 비활성화",
  "timezoneId": "Asia/Seoul"
}
  • 오류 응답 (403 Forbidden)
{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "권한 부족"
}
  • 오류 응답 (404 Not Found)
{
  "code": 1006,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없음"
}
  • 오류 응답 (409 Conflict)
{
  "code": 1008,
  "message": "TIMEMACHINE_ALREADY_DISABLED",
  "detail": "이미 TimeMachine이 비활성화되어 있습니다."
}

5. 데이터 롤백 관리 API​

📌 기술 구현 문서: 데이터 롤백 구현 가이드

데이터 롤백 관리 API는 가상 시간이 과거로 이동할 때 발생하는 데이터 롤백 작업의 이력과 상태를 조회하고 관리하는 기능을 제공합니다. 시간을 과거로 이동할 때 미래 데이터를 적절히 처리하여 데이터 정합성을 유지합니다.

5.1 롤백 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/rollback/history
  • 설명: 전체 롤백 이력을 조회합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 20)
- fromDate: 시작 날짜 (선택 사항)
- toDate: 종료 날짜 (선택 사항)
- entityType: 엔티티 유형 (선택 사항)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "rollback123",
      "timeChangeId": "change456",
      "affectedEntityType": "SleepLog",
      "affectedEntityCount": 15,
      "rollbackAction": "PERMANENT_DELETE",
      "rollbackTimestamp": 1715023456789,
      "userId": "user123",
      "userName": "테스트 사용자1"
    },
    {
      "id": "rollback124",
      "timeChangeId": "change457",
      "affectedEntityType": "SleepDiary",
      "affectedEntityCount": 5,
      "rollbackAction": "PERMANENT_DELETE",
      "rollbackTimestamp": 1715023456789,
      "userId": "user456",
      "userName": "테스트 사용자2"
    }
  ],
  "metadata": {
    "totalCount": 45,
    "currentPage": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

5.2 특정 사용자 롤백 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/users/{userId}/rollback/history
  • 설명: 특정 사용자의 롤백 이력을 조회합니다.
  • 권한: 시스템 관리자, 테스터, 사용자 본인

요청 (Request)​

- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 20)
- fromDate: 시작 날짜 (선택 사항)
- toDate: 종료 날짜 (선택 사항)
- entityType: 엔티티 유형 (선택 사항)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "rollback123",
      "timeChangeId": "change456",
      "affectedEntityType": "SleepLog",
      "affectedEntityCount": 15,
      "rollbackAction": "PERMANENT_DELETE",
      "rollbackTimestamp": 1715023456789
    },
    {
      "id": "rollback125",
      "timeChangeId": "change458",
      "affectedEntityType": "SleepDiary",
      "affectedEntityCount": 3,
      "rollbackAction": "PERMANENT_DELETE",
      "rollbackTimestamp": 1715033456789
    }
  ],
  "metadata": {
    "totalCount": 12,
    "currentPage": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

6. 이벤트 관리 API​

📌 기술 구현 문서: 이벤트 관리 구현 가이드 | 이벤트 관리 명세

이벤트 관리 API는 시간 변경 이벤트의 발행과 상태를 관리하는 기능을 제공합니다. 시간 변경 시 GCP Pub/Sub를 통해 이벤트를 발행하여 다른 서비스에서 필요한 조치를 취할 수 있도록 합니다.

6.1 이벤트 발행 이력 조회​

  • HTTP 메서드: GET
  • 경로: /v1/time-machine/events/history
  • 설명: 이벤트 발행 이력을 조회합니다.
  • 권한: 시스템 관리자, 테스터

요청 (Request)​

- page: 페이지 번호 (기본값: 1)
- limit: 페이지당 항목 수 (기본값: 20)
- status: 발행 상태 (PENDING, PUBLISHED, FAILED, RETRYING) (선택 사항)
- fromDate: 시작 날짜 (선택 사항)
- toDate: 종료 날짜 (선택 사항)
- userId: 사용자 ID (선택 사항)

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "items": [
    {
      "id": "event123",
      "timeChangeId": "change456",
      "previousDate": 1715123456789,
      "newDate": 1715223456789,
      "timestamp": 1715023456789,
      "userId": "user123",
      "userName": "테스트 사용자1", 
      "publishStatus": "PUBLISHED",
      "publishedAt": 1715023457789
    },
    {
      "id": "event124",
      "timeChangeId": "change457",
      "previousDate": 1715223456789,
      "newDate": 1715323456789,
      "timestamp": 1715023458789,
      "userId": "user456",
      "userName": "테스트 사용자2",
      "publishStatus": "FAILED",
      "publishErrorMessage": "Connection timed out"
    }
  ],
  "metadata": {
    "totalCount": 56,
    "currentPage": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

6.2 실패한 이벤트 재시도​

  • HTTP 메서드: POST
  • 경로: /v1/time-machine/events/{eventId}/retry
  • 설명: 실패한 이벤트 발행을 재시도합니다.
  • 권한: 시스템 관리자, 테스터

응답 (Response)​

  • 성공 응답 (200 OK)
{
  "id": "event124",
  "publishStatus": "RETRYING",
  "retryCount": 1,
  "retryTimestamp": 1715023498789
}
  • 오류 응답 (400 Bad Request)
{
  "code": 1010,
  "message": "INVALID_EVENT_STATUS",
  "detail": "재시도할 수 없는 이벤트 상태입니다."
}

7. 오류 코드​

코드메시지 (상수)HTTP 상태설명
1001INVALID_AUTH_TOKEN401유효하지 않은 인증 토큰 또는 토큰 누락
1002INVALID_DAY_INDEX400{dayIndex}가 유효하지 않음 (예: 2 미만)
1003INVALID_DATE_TIME_FORMAT400{newTime} 등의 날짜/시간 형식이 잘못됨 (예: 타임스탬프가 아닌 문자열)
1004PERMISSION_DENIED403해당 작업을 수행할 권한이 없음
1005TIME_MACHINE_NOT_ENABLED400TimeMachine 기능이 비활성화 상태임 (또는 특정 사용자에 대해)
1006USER_NOT_FOUND404{userId}에 해당하는 사용자를 찾을 수 없음
1007REASON_REQUIRED400시간 변경 시 사유(reason) 필드가 누락됨
1008INVALID_TARGET_USER_ID400{targetUserId}가 유효하지 않거나, 권한상 지정할 수 없음
1009EVENT_NOT_FOUND404{eventId}에 해당하는 이벤트를 찾을 수 없음
1010EVENT_NOT_RETRYABLE400해당 이벤트는 재시도할 수 없는 상태임 (예: 이미 성공)
1011INVALID_DAY_INDEX400{dayIndex}가 유효하지 않음 (예: 2 미만)
1012INVALID_TIMEZONE_ID400{timezoneId}가 유효하지 않은 IANA 타임존 ID임
1013USER_CYCLE_NOT_FOUND404사용자의 치료 주기(UserCycle) 정보를 찾을 수 없어 날짜 계산 불가
1014INVALID_SUSPENSION_SEQUENCE400{suspensionSequence}가 유효하지 않음 (예: 1 미만, 또는 해당 순서의 정지 이력 없음)
1015INVALID_DAY_WITHIN_SUSPENSION400{dayWithinSuspension}이 유효하지 않음 (예: 1 미만, 또는 해당 정지 기간의 일수를 초과)
2001VIRTUAL_TIME_CHANGE_FAILED500가상 시간 변경 중 내부 서버 오류 발생
2002EVENT_PUBLISH_FAILED500시간 변경 이벤트 발행 중 내부 서버 오류 발생
2003DB_OPERATION_FAILED500데이터베이스 작업 중 오류 발생
2004DATE_CALCULATION_ERROR500날짜 계산 로직(예: dayIndex 기반)에서 오류 발생

8. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-05-15bok@weltcorp.com초기 API 엔드포인트 초안 작성