수면 기록 조회 API (일차별)

개요

수면 기록 조회 API는 사용자의 특정 일차에 해당하는 수면 데이터를 조회하는 기능을 제공합니다. 이 API는 캐시 우선 조회 방식을 사용하여 빠른 응답 속도를 보장하며, 수면 패턴 분석과 통계 생성의 기반 데이터를 제공합니다.

주요 특징

• 캐시 우선 조회: Redis 캐시에서 먼저 데이터를 조회하여 응답 속도 최적화
• 자동 캐시 저장: DB에서 조회한 데이터를 자동으로 캐시에 저장
• 일차 기반 조회: 치료 주기의 특정 일차(targetDayIndex)를 기준으로 수면 기록 조회
• 완전한 수면 데이터: 수면 시간, 수면의 질, 영향 요인 등 모든 수면 관련 정보 제공

데이터 활용

조회된 수면 기록은 다음과 같은 용도로 활용됩니다:

• 수면 패턴 분석: 개인의 수면 습관과 패턴 파악
• rTIB 계산: 권장 침대 시간 계산의 기반 데이터
• 수면 목표 달성 평가: 설정된 수면 목표와의 비교 분석
• 통계 및 리포트: 주간/월간 수면 통계 생성

제약사항

• 존재하지 않는 일차 조회 시 404 오류 반환
• 사용자는 자신의 수면 기록만 조회 가능
• 임시 수면 기록과 완전한 수면 기록 모두 조회 가능

수면 기록 조회

특정 일차의 수면 기록을 조회합니다.

• HTTP Method: GET
• Path: /v1/sleep/logs/target-day-index/{targetDayIndex}
• 인증: 액세스 토큰 (accessToken) 필요

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
Accept-Language	de-DE, en-US, ko-KR	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Path Parameters

Parameter	Type	Description	Required
targetDayIndex	number	조회할 치료 주기 일차 (1부터 시작하는 정수값, Kotlin: Int, Swift: Int)	Yes

Responses

HTTP Status Code	설명	Error Code(s)
200 OK	성공	-
401 Unauthorized	인증 실패 (유효하지 않은 액세스 토큰)	10001
403 Forbidden	권한 없음 (다른 사용자의 데이터 접근 시도)	10030
404 Not Found	수면 기록을 찾을 수 없음	10040
500 Internal Server Error	서버 내부 오류	10000

200 OK - 성공

완전한 수면 기록 조회 성공 (DNS = false):

{
  "id": "sl_12345",
  "targetDayIndex": 7,
  "date": "2024-05-10",
  "dns": false,
  "lot": 1715371200000,
  "aet": 1715400600000,
  "tstMinutes": 465,
  "sleepEfficiency": 0.92,
  "solMinutes": 30,
  "wasoMinutes": 15,
  "sleepQuality": 3,
  "positiveFactorIds": [1, 3, 5],
  "negativeFactorIds": [2, 4],
  "pill": true,
  "napMinutes": 20,
  "positiveCustomFactors": ["좋은 베개"],
  "negativeCustomFactors": ["옆방 소음"],
  "timezone": {
    "id": "Asia/Seoul",
    "offsetInMinutes": 540
  },
  "isTemporary": false,
  "createdAt": 1715311800000,
  "updatedAt": 1715313600000
}

DNS(Did Not Sleep) 수면 기록 조회 성공 (DNS = true):

{
  "id": "sl_12346",
  "targetDayIndex": 5,
  "date": "2024-05-08",
  "dns": true,
  "lot": null,
  "aet": null,
  "tstMinutes": 0,
  "sleepEfficiency": 0,
  "solMinutes": null,
  "wasoMinutes": null,
  "sleepQuality": null,
  "positiveFactorIds": [],
  "negativeFactorIds": [2, 4, 6],
  "pill": false,
  "napMinutes": 0,
  "positiveCustomFactors": [],
  "negativeCustomFactors": ["스트레스", "소음"],
  "timezone": {
    "id": "Asia/Seoul",
    "offsetInMinutes": 540
  },
  "isTemporary": false,
  "createdAt": 1715048400000,
  "updatedAt": 1715048400000
}

필드	타입	설명	필수
id	string	수면 기록 고유 ID	Yes
targetDayIndex	number	치료 주기 일차	Yes
date	string	수면 기록 날짜 (YYYY-MM-DD, 사용자 시간대 기준)	Yes
dns	boolean	Did Not Sleep 여부 (전혀 잠을 자지 못했는지)	Yes
lot	number	잠자리에 든 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64, DNS=false인 경우에만)	No
aet	number	일어난 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64, DNS=false인 경우에만)	No
tstMinutes	number	총 수면 시간 (분, 시스템 계산값)	No
sleepEfficiency	number	수면 효율 (0~1, 시스템 계산값)	No
solMinutes	number	잠들기까지 걸린 시간 (분)	No
wasoMinutes	number	수면 중 깬 시간 총합 (분)	No
sleepQuality	number	수면의 질 (1~5 등급)	No
positiveFactorIds	array	긍정적 영향 요인 ID 목록	No
negativeFactorIds	array	부정적 영향 요인 ID 목록	No
pill	boolean	수면제 복용 여부	Yes
napMinutes	number	낮잠 시간 (분)	Yes
positiveCustomFactors	array	사용자 지정 긍정적 요인	No
negativeCustomFactors	array	사용자 지정 부정적 요인	No
timezone	object	타임존 정보	Yes
timezone.id	string	타임존 ID (IANA 형식)	Yes
timezone.offsetInMinutes	number	타임존 오프셋 (분 단위)	Yes
isTemporary	boolean	임시 기록 여부	Yes
createdAt	number	생성 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	Yes
updatedAt	number	수정 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	Yes

403 Forbidden - 권한 없음

예시: 권한 부족 (INSUFFICIENT_PERMISSIONS - 10030)

{
  "code": 10030,
  "message": "INSUFFICIENT_PERMISSIONS",
  "detail": "권한이 충분하지 않습니다.",
  "metadata": {
    "requestedResource": "sleep_log",
    "targetDayIndex": 7
  }
}

404 Not Found - 수면 기록을 찾을 수 없음

예시: 수면 기록 없음 (SLEEP_LOG_NOT_FOUND - 10040)

{
  "code": 10040,
  "message": "SLEEP_LOG_NOT_FOUND",
  "detail": "해당 일차의 수면 기록을 찾을 수 없습니다.",
  "metadata": {
    "targetDayIndex": 7,
    "userCycleId": "uc_456"
  }
}

500 Internal Server Error - 서버 내부 오류

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

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

설명

• 이 API는 사용자의 특정 일차 수면 기록을 조회하는 핵심 기능입니다.
• 캐시 우선 조회 방식:
  • Redis 캐시에서 먼저 데이터를 조회하여 빠른 응답 제공
  • 캐시에 데이터가 없으면 데이터베이스에서 조회
  • DB 조회 후 자동으로 캐시에 저장하여 다음 요청 시 성능 향상
• 데이터 형식:
  • lot, aet: Unix timestamp (밀리초) 형식으로 응답
  • date: 사용자 시간대 기준 날짜 문자열 (YYYY-MM-DD)
  • createdAt, updatedAt: Unix timestamp (밀리초) 형식
• 수면 기록 유형별 응답:
  • 완전한 수면 기록: 모든 필드가 포함된 완성된 수면 데이터
  • DNS 기록: 전혀 잠을 자지 못한 경우, 수면 관련 필드는 null
  • 임시 기록: 부분적으로 입력된 미완성 수면 데이터 (isTemporary: true)
• 자동 계산 필드:
  • tstMinutes: 총 수면 시간 = TIB - SOL - WASO
  • sleepEfficiency: 수면 효율 = TST / TIB (0~1 사이의 값)
• 영향 요인 관리:
  • positiveFactorIds, negativeFactorIds: 사전 정의된 영향 요인 ID 목록
  • positiveCustomFactors, negativeCustomFactors: 사용자가 직접 입력한 요인
• 성능 최적화:
  • 최근 3일 데이터는 6시간 캐시, 과거 데이터는 24시간 캐시
  • 캐시 실패 시에도 핵심 기능에 영향 없도록 설계
• 데이터 활용:
  • 수면 패턴 분석 및 개인화된 수면 목표 설정
  • rTIB(권장 침대 시간) 계산의 기반 데이터
  • 주간/월간 수면 통계 및 리포트 생성