타임머신 가상 시간 API 명세
개요
이 문서는 TimeMachine 도메인의 가상 시간 관리 API에 대한 상세 명세를 제공합니다. 이 API는 테스트 환경에서 시간을 조작하여 시간에 민감한 기능을 검증할 수 있게 합니다.
API 엔드포인트
| 경로 | 메서드 | 설명 |
|---|---|---|
/v1/time-machine/time | GET | 현재 가상 시간 조회 |
/v1/time-machine/time | POST | 가상 시간 변경 |
/v1/time-machine/time/day/{day} | POST | 특정 일차로 이동 |
/v1/time-machine/time/week/{week} | POST | 특정 주차로 이동 |
/v1/time-machine/time/reset | POST | 실제 시간으로 재설정 |
/v1/time-machine/time/history | GET | 시간 변경 이력 조회 |
상세 명세
1. 현재 가상 시간 조회
요청
- URL:
/v1/time-machine/time - 메서드:
GET - 인증: Bearer 토큰 필요
- 권한: 모든 사용자
응답
성공 응답: 200 OK
{
"currentTime": 1715123456789,
"active": true,
"lastChangeTimestamp": 1715023456789
}
| 필드 | 타입 | 설명 |
|---|---|---|
currentTime | number | 현재 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
active | boolean | TimeMachine 기능 활성화 여부 |
lastChangeTimestamp | number | 마지막 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
실패 응답: 401 Unauthorized
{
"code": 1001,
"message": "INVALID_AUTH_TOKEN",
"detail": "인증 토큰이 유효하지 않습니다."
}
2. 가상 시간 변경
요청
- URL:
/v1/time-machine/time - 메서드:
POST - 인증: Bearer 토큰 필요
- 권한: 시스템 관리자, 테스터
- Content-Type:
application/json
요청 본문:
{
"newTime": 1715223456789,
"reason": "특정 기능 테스트를 위한 시간 변경"
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
newTime | number | 예 | 설정할 새 시간 (13자리 Unix 타임스탬프, 밀리초) |
reason | string | 예 | 시간 변경 사유 |
응답
성공 응답: 200 OK
{
"previousTime": 1715123456789,
"currentTime": 1715223456789,
"changeTimestamp": 1715023456789,
"eventPublished": true
}
| 필드 | 타입 | 설명 |
|---|---|---|
previousTime | number | 이전 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
currentTime | number | 변경된 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
changeTimestamp | number | 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
eventPublished | boolean | 이벤트 발행 성공 여부 |
실패 응답: 403 Forbidden
{
"code": 1004,
"message": "PERMISSION_DENIED",
"detail": "시간 변경 권한이 없습니다."
}
3. 특정 일차로 이동
요청
- URL:
/v1/time-machine/time/day/{day} - 메서드:
POST - 인증: Bearer 토큰 필요
- 권한: 시스템 관리자, 테스터
- Content-Type:
application/json
경로 파라미터:
| 파라미터 | 타입 | 설명 |
|---|---|---|
day | number | 이동할 일차 (1부터 시작) |
요청 본문:
{
"reason": "30일차 기능 테스트를 위한 시간 변경"
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
reason | string | 예 | 시간 변경 사유 |
응답
성공 응답: 200 OK
{
"previousTime": 1715123456789,
"currentTime": 1717123456789,
"day": 30,
"changeTimestamp": 1715023456789,
"eventPublished": true
}
| 필드 | 타입 | 설명 |
|---|---|---|
previousTime | number | 이전 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
currentTime | number | 변경된 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
day | number | 이동한 일차 |
changeTimestamp | number | 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
eventPublished | boolean | 이벤트 발행 성공 여부 |
실패 응답: 400 Bad Request
{
"code": 1002,
"message": "INVALID_DAY",
"detail": "유효하지 않은 일차입니다."
}
4. 특정 주차로 이동
요청
- URL:
/v1/time-machine/time/week/{week} - 메서드:
POST - 인증: Bearer 토큰 필요
- 권한: 시스템 관리자, 테스터
- Content-Type:
application/json
경로 파라미터:
| 파라미터 | 타입 | 설명 |
|---|---|---|
week | number | 이동할 주차 (1부터 시작) |
요청 본문:
{
"reason": "5주차 기능 테스트를 위한 시간 변경"
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
reason | string | 예 | 시간 변경 사유 |
응답
성공 응답: 200 OK
{
"previousTime": 1715123456789,
"currentTime": 1718123456789,
"week": 5,
"day": 29,
"changeTimestamp": 1715023456789,
"eventPublished": true
}
| 필드 | 타입 | 설명 |
|---|---|---|
previousTime | number | 이전 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
currentTime | number | 변경된 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
week | number | 이동한 주차 |
day | number | 이동한 일차 |
changeTimestamp | number | 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
eventPublished | boolean | 이벤트 발행 성공 여부 |
실패 응답: 400 Bad Request
{
"code": 1003,
"message": "INVALID_WEEK",
"detail": "유효하지 않은 주차입니다."
}
5. 실제 시간으로 재설정
요청
- URL:
/v1/time-machine/time/reset - 메서드:
POST - 인증: Bearer 토큰 필요
- 권한: 시스템 관리자, 테스터
- Content-Type:
application/json
요청 본문:
{
"reason": "테스트 완료 후 시간 재설정"
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
reason | string | 예 | 시간 변경 사유 |
응답
성공 응답: 200 OK
{
"previousTime": 1715123456789,
"currentTime": 1715023456789,
"changeTimestamp": 1715023456789,
"eventPublished": true
}
| 필드 | 타입 | 설명 |
|---|---|---|
previousTime | number | 이전 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
currentTime | number | 변경된 가상 시간 (13자리 Unix 타임스탬프, 밀리초) |
changeTimestamp | number | 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
eventPublished | boolean | 이벤트 발행 성공 여부 |
6. 시간 변경 이력 조회
요청
- URL:
/v1/time-machine/time/history - 메서드:
GET - 인증: Bearer 토큰 필요
- 권한: 시스템 관리자, 테스터, 일반 사용자(자신의 이력만)
쿼리 파라미터:
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
page | number | 아니오 | 1 | 페이지 번호 |
limit | number | 아니오 | 10 | 페이지당 항목 수 |
fromDate | number | 아니오 | - | 시작 날짜 (13자리 Unix 타임스탬프, 밀리초) |
toDate | number | 아니오 | - | 종료 날짜 (13자리 Unix 타임스탬프, 밀리초) |
응답
성공 응답: 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일차 기능 테스트를 위한 시간 변경"
}
],
"metadata": {
"totalCount": 25,
"currentPage": 1,
"pageSize": 10,
"totalPages": 3
}
}
| 필드 | 타입 | 설명 |
|---|---|---|
items | array | 시간 변경 이력 항목 배열 |
items[].id | string | 이력 ID |
items[].previousTime | number | 이전 시간 (13자리 Unix 타임스탬프, 밀리초) |
items[].newTime | number | 변경 후 시간 (13자리 Unix 타임스탬프, 밀리초) |
items[].changeType | string | 변경 유형 (SET, MOVE_FORWARD, MOVE_BACKWARD, RESET) |
items[].timestamp | number | 변경 시간 (13자리 Unix 타임스탬프, 밀리초) |
items[].changedById | string | 변경자 ID |
items[].changedByName | string | 변경자 이름 |
items[].reason | string | 변경 사유 |
metadata | object | 페이지네이션 메타데이터 |
metadata.totalCount | number | 전체 항목 수 |
metadata.currentPage | number | 현재 페이지 번호 |
metadata.pageSize | number | 페이지당 항목 수 |
metadata.totalPages | number | 전체 페이지 수 |
에러 코드
| 코드 | 메시지 | 설명 |
|---|---|---|
| 1001 | INVALID_AUTH_TOKEN | 인증 토큰이 유효하지 않습니다. |
| 1002 | INVALID_DAY | 유효하지 않은 일차입니다. |
| 1003 | INVALID_WEEK | 유효하지 않은 주차입니다. |
| 1004 | PERMISSION_DENIED | 시간 변경 권한이 없습니다. |
| 1005 | USER_NOT_FOUND | 사용자를 찾을 수 없습니다. |
| 1006 | VIRTUAL_TIME_NOT_FOUND | 가상 시간 정보를 찾을 수 없습니다. |
| 1011 | ROLLBACK_FAILED | 데이터 롤백에 실패했습니다. |
| 1012 | INVALID_TIME_FORMAT | 유효하지 않은 시간 형식입니다. |
| 1013 | PROD_TIMEMACHINE_RESTRICTED | 운영 환경에서 TimeMachine 기능이 제한됩니다. |
| 1014 | EVENT_PUBLISH_FAILED | 이벤트 발행에 실패했습니다. |
API 확장 계획
추가 예정 기능
-
시간 변경 예약 API
- 특정 시간에 자동으로 시간 변경을 예약하는 기능
- 예약 생성, 조회, 취소 API 추가 예정
-
시간 시나리오 API
- 미리 정의된 시간 변경 시퀀스를 생성하고 실행하는 기능
- 시나리오 생성, 조회, 실행, 삭제 API 추가 예정
-
다중 사용자 일괄 변경 API
- 여러 사용자의 가상 시간을 한 번에 변경하는 기능
- 특정 테스트 그룹의 사용자들을 동일한 시간으로 설정 가능
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 0.1.0 | 2025-04-06 | bok@weltcorp.com | 최초 작성 |