본문으로 건너뛰기

사용자별 가상 시간 API 명세

개요​

이 문서는 TimeMachine 도메인의 사용자별 가상 시간 관리 API에 대한 상세 명세를 제공합니다. 이 API를 통해 테스터는 특정 사용자의 가상 시간을 개별적으로 관리하고 조작할 수 있으며, 각 사용자는 독립적인 테스트 전용 가상 시간을 가질 수 있습니다.

API 엔드포인트​

경로메서드설명
/v1/time-machine/users/{userId}/timeGET특정 사용자의 가상 시간 조회
/v1/time-machine/users/{userId}/timePOST특정 사용자의 가상 시간 변경
/v1/time-machine/users/timeGET모든 사용자의 가상 시간 정보 조회

상세 명세​

1. 특정 사용자의 가상 시간 조회​

요청​

  • URL: /v1/time-machine/users/{userId}/time
  • 메서드: GET
  • 인증: Bearer 토큰 필요
  • 권한: 시스템 관리자, 테스터, 사용자 본인

경로 파라미터:

파라미터타입설명
userIdstring가상 시간을 조회할 사용자 ID

응답​

성공 응답: 200 OK

{
  "userId": "user123",
  "currentTime": 1715123456789,
  "active": true,
  "lastChangeTimestamp": 1715023456789,
  "changedById": "tester456"
}
필드타입설명
userIdstring사용자 ID
currentTimenumber현재 가상 시간 (13자리 Unix 타임스탬프, 밀리초)
activebooleanTimeMachine 기능 활성화 여부
lastChangeTimestampnumber마지막 변경 시간 (13자리 Unix 타임스탬프, 밀리초)
changedByIdstring마지막으로 시간을 변경한 사용자 ID

실패 응답: 404 Not Found

{
  "code": 1005,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다."
}

실패 응답: 403 Forbidden

{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "다른 사용자의 가상 시간을 조회할 권한이 없습니다."
}

2. 특정 사용자의 가상 시간 변경​

요청​

  • URL: /v1/time-machine/users/{userId}/time
  • 메서드: POST
  • 인증: Bearer 토큰 필요
  • 권한: 시스템 관리자, 테스터
  • Content-Type: application/json

경로 파라미터:

파라미터타입설명
userIdstring가상 시간을 변경할 사용자 ID

요청 본문:

{
  "newTime": 1715223456789,
  "reason": "특정 사용자 테스트를 위한 시간 변경"
}
필드타입필수설명
newTimenumber예설정할 새 시간 (13자리 Unix 타임스탬프, 밀리초)
reasonstring예시간 변경 사유

응답​

성공 응답: 200 OK

{
  "userId": "user123",
  "previousTime": 1715123456789,
  "currentTime": 1715223456789,
  "changeTimestamp": 1715023456789,
  "eventPublished": true
}
필드타입설명
userIdstring사용자 ID
previousTimenumber이전 가상 시간 (13자리 Unix 타임스탬프, 밀리초)
currentTimenumber변경된 가상 시간 (13자리 Unix 타임스탬프, 밀리초)
changeTimestampnumber변경 시간 (13자리 Unix 타임스탬프, 밀리초)
eventPublishedboolean이벤트 발행 성공 여부

실패 응답: 404 Not Found

{
  "code": 1005,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다."
}

실패 응답: 403 Forbidden

{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "다른 사용자의 가상 시간을 변경할 권한이 없습니다."
}

3. 모든 사용자의 가상 시간 정보 조회​

요청​

  • URL: /v1/time-machine/users/time
  • 메서드: GET
  • 인증: Bearer 토큰 필요
  • 권한: 시스템 관리자, 테스터

쿼리 파라미터:

파라미터타입필수기본값설명
pagenumber아니오1페이지 번호
limitnumber아니오20페이지당 항목 수
activeboolean아니오-TimeMachine 활성화 상태로 필터링

응답​

성공 응답: 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
  }
}
필드타입설명
itemsarray가상 시간 정보 항목 배열
items[].userIdstring사용자 ID
items[].userNamestring사용자 이름
items[].currentTimenumber현재 가상 시간 (13자리 Unix 타임스탬프, 밀리초)
items[].activebooleanTimeMachine 기능 활성화 여부
items[].lastChangeTimestampnumber마지막 변경 시간 (13자리 Unix 타임스탬프, 밀리초)
metadataobject페이지네이션 메타데이터
metadata.totalCountnumber전체 항목 수
metadata.currentPagenumber현재 페이지 번호
metadata.pageSizenumber페이지당 항목 수
metadata.totalPagesnumber전체 페이지 수

실패 응답: 403 Forbidden

{
  "code": 1004,
  "message": "PERMISSION_DENIED",
  "detail": "모든 사용자의 가상 시간을 조회할 권한이 없습니다."
}

API 기능 확장​

1. 다중 사용자 일괄 변경 API (계획 중)​

  • URL: /v1/time-machine/users/time/batch
  • 메서드: POST
  • 설명: 여러 사용자의 가상 시간을 한 번에 변경
  • 요청 본문: 
    {
      "userIds": ["user123", "user456", "user789"],
      "newTime": 1715223456789,
      "reason": "다중 사용자 테스트를 위한 시간 변경"
    }

2. 사용자별 특정 일차/주차 이동 API (계획 중)​

  • URL: /v1/time-machine/users/{userId}/time/day/{day}

  • 메서드: POST

  • 설명: 특정 사용자를 특정 일차로 이동

  • URL: /v1/time-machine/users/{userId}/time/week/{week}

  • 메서드: POST

  • 설명: 특정 사용자를 특정 주차로 이동

3. 사용자 그룹 관리 API (계획 중)​

  • URL: /v1/time-machine/user-groups
  • 메서드: POST, GET, PUT, DELETE
  • 설명: 테스트 사용자 그룹을 생성, 조회, 수정, 삭제 및 그룹별 가상 시간 관리

에러 코드​

코드메시지설명
1001INVALID_AUTH_TOKEN인증 토큰이 유효하지 않습니다.
1004PERMISSION_DENIED권한이 없습니다.
1005USER_NOT_FOUND사용자를 찾을 수 없습니다.
1006VIRTUAL_TIME_NOT_FOUND가상 시간 정보를 찾을 수 없습니다.
1011ROLLBACK_FAILED데이터 롤백에 실패했습니다.
1012INVALID_TIME_FORMAT유효하지 않은 시간 형식입니다.
1013PROD_TIMEMACHINE_RESTRICTED운영 환경에서 TimeMachine 기능이 제한됩니다.
1014EVENT_PUBLISH_FAILED이벤트 발행에 실패했습니다.
1015BATCH_OPERATION_PARTIALLY_FAILED일괄 작업이 일부 실패했습니다.
1016USER_GROUP_NOT_FOUND사용자 그룹을 찾을 수 없습니다.

보안 고려사항​

  1. 접근 제어: 사용자별 가상 시간 조회 및 변경은 적절한 권한이 필요합니다.
  2. 데이터 격리: 각 사용자의 가상 시간은 독립적으로 관리되어야 합니다.
  3. 운영 환경 제한: 운영 환경에서는 특별한 권한이 있는 사용자만 사용 가능합니다.

변경 이력​

버전날짜작성자변경 내용
0.1.02025-04-05bok@weltcorp.com최초 작성