본문으로 건너뛰기
버전: 개발 버전 (최신)

사용자 현재 상태 조회 API

개요​

사용자 현재 상태 조회 API는 현재 로그인한 사용자의 치료 상태 정보와 일차-날짜 매핑 정보를 통합하여 제공합니다. 이 API는 사용자의 치료 진행 상황, 주기 중단/재개 이력, 일시 정지 기간 등의 포괄적인 정보를 한 번의 요청으로 조회할 수 있도록 설계되었습니다.

주요 기능​

  • 치료 상태 정보: 현재 활성 주기, 치료 시작일, 현재 일차 등
  • 일차-날짜 매핑: 치료 일차와 실제 날짜의 매핑 정보
  • 중단/재개 이력: 사용자 주기 중단 및 재개 이력
  • 일시 정지 기간: 치료 활동 일시 정지 기간 정보
  • 권한 목록 조회 : 사용자의 플랜에 따른 권한 조회 (플랜별 할당된 역할 매핑)

비즈니스 로직​

  • 일차 제한: currentDayIndex는 최대 90까지만 증가하며, 90을 넘길 수 없음
  • 매핑 제한: dayMappings 배열의 모든 항목이 포함되지만, 90일 이후의 dayIndex는 계속 90으로 유지됨

날짜 형식 규칙​

이 API는 두 가지 날짜 형식을 사용합니다:

  • Unix Timestamp (13자리): 정확한 시간 정보가 필요한 필드
    • currentUserTime
    • suspensions[].startDate, suspensions[].endDate
    • suspensionPeriods[].startDate, suspensionPeriods[].endDate
  • YYYY-MM-DD 형식: 날짜만 필요한 필드
    • dayMappings[].date

사용자 현재 상태 조회​

현재 로그인한 사용자의 치료 상태와 관련된 모든 정보를 조회합니다.

  • HTTP Method: GET
  • Path: /v1/users/state/current
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes

Request Body​

이 API는 GET 요청이므로 요청 본문이 없습니다. 모든 필요한 정보는 JWT 토큰을 통해 전달됩니다.

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
401 Unauthorized인증 실패 (토큰 누락, 만료, 유효하지 않음)-
403 Forbidden권한 없음2060
404 Not Found활성 주기가 없음4041
500 Internal Server Error서버 내부 오류2000
200 OK - 성공

기본 사용자 상태 조회 성공:

{
  "planId": "plan_789",
  "currentUserTime": 1715126400000,
  "currentDayIndex": 4,
  "isSuspended": false,
  "isTimeMachineActivated": false,
  "suspensions": [
    {
      "sequence": 1,
      "startDate": 1714521600000,
      "endDate": 1714694400000,
      "durationDays": 2
    }
  ],
  "dayMappings": [
    {
      "dayIndex": 1,
      "date": "2025-05-03"
    },
    {
      "dayIndex": 2,
      "date": "2025-05-04"
    },
    {
      "dayIndex": 3,
      "date": "2025-05-07"
    },
    {
      "dayIndex": 4,
      "date": "2025-05-08"
    }
  ],
  "suspensionPeriods": [
    {
      "startDate": 1714867200000,
      "endDate": 1714953600000,
      "reason": "휴가"
    }
  ],
  "permissions": [
    "sleep.log.create",
    "sleep.log.read",
    "sleep.log.update",
    ...
  ]
}
필드타입설명
planIdstring플랜 ID
currentUserTimenumber현재 사용자 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
currentDayIndexnumber현재 사용자 시간의 일차 (Kotlin: Int, Swift: Int)
isSuspendedboolean주기 중단 여부
isTimeMachineActivatedboolean타임머신 활성화 여부
suspensionsarray중단/재개 이력 목록
suspensions[].sequencenumber중단 순서 (1부터 시작, Kotlin: Int, Swift: Int)
suspensions[].startDatenumber중단 시작일 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
suspensions[].endDatenumber|null중단 종료일 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64), 재개되지 않았으면 null
suspensions[].durationDaysnumber|null중단 기간 (일수, Kotlin: Int, Swift: Int), 아직 재개되지 않았으면 null
dayMappingsarray일차-날짜 매핑 배열
dayMappings[].dayIndexnumber치료 일차 (1부터 시작, Kotlin: Int, Swift: Int)
dayMappings[].datestring해당 일차의 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준)
suspensionPeriodsarray치료 활동 일시 정지 기간 배열
suspensionPeriods[].startDatenumber정지 시작 날짜 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
suspensionPeriods[].endDatenumber|null정지 종료 날짜 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64), null이면 현재 진행 중
suspensionPeriods[].reasonstring정지 사유 (선택적)
permissionsarray(string)현재 사용자의 권한 목록
401 Unauthorized - 인증 실패

예시: 토큰이 누락된 경우

{
  "message": "Unauthorized",
  "statusCode": 401
}
403 Forbidden - 권한 없음

예시: 권한 부족 (PERMISSION_DENIED - 2060)

{
  "code": 2060,
  "message": "PERMISSION_DENIED",
  "detail": "사용자 상태를 조회할 권한이 없습니다."
}
404 Not Found - 활성 주기가 없음

예시: 활성 주기 없음 (ACTIVE_CYCLE_NOT_FOUND - 4041)

{
  "code": 4041,
  "message": "ACTIVE_CYCLE_NOT_FOUND",
  "detail": "현재 활성화된 치료 주기가 없습니다.",
  "metadata": {
    "userId": "user_123"
  }
}
500 Internal Server Error - 서버 내부 오류

예시: 일반 서버 오류 (SERVER_ERROR - 2000)

{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다."
}