버전: 개발 버전 (최신)

수면 기록 조회 API (일차 범위)

개요

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

주요 특징

캐시 우선 조회: Redis 캐시에서 먼저 데이터를 조회하여 응답 속도 최적화
자동 캐시 저장: DB에서 조회한 데이터를 자동으로 캐시에 저장
범위 기반 조회: 시작 일차와 종료 일차를 지정하여 여러 수면 기록을 한 번에 조회
요약된 수면 데이터: 목록 조회에 최적화된 핵심 수면 정보만 제공

데이터 활용

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

수면 패턴 분석: 기간별 수면 습관과 패턴 파악
통계 및 리포트: 주간/월간 수면 통계 생성
수면 목표 달성 평가: 기간별 수면 목표 달성률 분석
차트 및 그래프: 수면 데이터 시각화

제약사항

존재하지 않는 일차 범위 조회 시 빈 배열 반환
사용자는 자신의 수면 기록만 조회 가능
임시 수면 기록과 완전한 수면 기록 모두 조회 가능

수면 기록 범위 조회

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

HTTP Method: GET
Path: /v1/sleep/logs/day-index-range
인증: 액세스 토큰 (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

Query Parameters

Parameter	Type	Description	Required
`startDayIndex`	number	조회할 시작 일차 (1부터 시작하는 정수값, Kotlin: `Int`, Swift: `Int`)	Yes
`endDayIndex`	number	조회할 종료 일차 (1부터 시작하는 정수값, Kotlin: `Int`, Swift: `Int`)	Yes

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	성공	-
`400 Bad Request`	잘못된 요청 (잘못된 파라미터)	`10002`
`403 Forbidden`	권한 없음 (다른 사용자의 데이터 접근 시도)	`10030`
`500 Internal Server Error`	서버 내부 오류	`10000`

200 OK - 성공

수면 기록 범위 조회 성공:

{
  "items": [
    {
      "sleepLog": {
        "id": "1b09aed9-ed4a-4c0c-ac9e-0450cf1dfc70",
        "dayIndex": 1,
        "dns": false,
        "lot": 1380,
        "aet": 1920,
        "tstMinutes": 480,
        "sleepEfficiency": 1,
        "solMinutes": 0,
        "wasoMinutes": 0,
        "sleepQuality": 4,
        "positiveFactorIds": [3, 4],
        "negativeFactorIds": [3, 4],
        "pill": true,
        "napMinutes": 30,
        "positiveCustomFactors": ["충분한 운동", "따뜻한 샤워"],
        "negativeCustomFactors": [],
        "isTemporary": false,
        "createdAt": 1749716192050,
        "updatedAt": 1749716343687
      },
      "goalAdherence": null
    },
    {
      "sleepLog": {
        "id": "e4abdcc0-be20-42d2-ba57-fc8e77b4221e",
        "dayIndex": 2,
        "dns": false,
        "lot": 1380,
        "aet": 1920,
        "tstMinutes": 505,
        "sleepEfficiency": 0.93519,
        "solMinutes": 15,
        "wasoMinutes": 20,
        "sleepQuality": 4,
        "positiveFactorIds": [0],
        "negativeFactorIds": [3],
        "pill": false,
        "napMinutes": 30,
        "positiveCustomFactors": [],
        "negativeCustomFactors": [],
        "isTemporary": false,
        "createdAt": 1750145181477,
        "updatedAt": 1750145773922
      },
      "goalAdherence": null
    },
    {
      "sleepLog": {
        "id": "b70a376b-c548-488d-a9b1-450222a3c314",
        "dayIndex": 3,
        "dns": false,
        "lot": 1320,
        "aet": 480,
        "tstMinutes": 145,
        "sleepEfficiency": 0.80556,
        "solMinutes": 15,
        "wasoMinutes": 20,
        "sleepQuality": 4,
        "positiveFactorIds": [3, 4],
        "negativeFactorIds": [1],
        "pill": false,
        "napMinutes": 30,
        "positiveCustomFactors": ["충분한 운동", "따뜻한 샤워"],
        "negativeCustomFactors": ["늦은 카페인 섭취", "스마트폰 사용"],
        "isTemporary": false,
        "createdAt": 1750211600306,
        "updatedAt": 1750224769996
      },
      "goalAdherence": null
    },
    {
      "sleepLog": {
        "id": "80117adb-d727-462c-8e84-f60b5180e398",
        "dayIndex": 9,
        "dns": true,
        "lot": null,
        "aet": null,
        "tstMinutes": null,
        "sleepEfficiency": null,
        "solMinutes": null,
        "wasoMinutes": null,
        "sleepQuality": null,
        "positiveFactorIds": [],
        "negativeFactorIds": [],
        "pill": false,
        "napMinutes": 30,
        "positiveCustomFactors": [],
        "negativeCustomFactors": [],
        "isTemporary": false,
        "createdAt": 1750754142818,
        "updatedAt": 1750755467951
      },
      "goalAdherence": {
        "id": "4b5a87d5-2c8d-436a-a591-220238e1294c",
        "targetDayIndex": 9,
        "sleepGoalId": "dsfdsafdsafdasfasdf",
        "lotSuccess": false,
        "aetSuccess": false,
        "createdAt": 1750753836510,
        "updatedAt": 1750753831032
      }
    }
  ],
  "count": 4,
  "startDayIndex": 1,
  "endDayIndex": 9
}

빈 범위 조회 결과:

{
  "items": [],
  "count": 0,
  "startDayIndex": 15,
  "endDayIndex": 17
}

필드	타입	설명	필수
`items`	array	수면 기록 목록	Yes
`items[].sleepLog`	object	수면 기록 데이터	Yes
`items[].sleepLog.id`	string	수면 기록 고유 ID	Yes
`items[].sleepLog.dayIndex`	number	치료 주기 일차	Yes
`items[].sleepLog.dns`	boolean	Did Not Sleep 여부 (전혀 잠을 자지 못했는지)	Yes
`items[].sleepLog.lot`	number	잠자리에 든 시각 (어제 자정부터의 경과 분, DNS=false인 경우에만)	No
`items[].sleepLog.aet`	number	일어난 시각 (어제 자정부터의 경과 분, DNS=false인 경우에만)	No
`items[].sleepLog.tstMinutes`	number	총 수면 시간 (분, 시스템 계산값)	No
`items[].sleepLog.sleepEfficiency`	number	수면 효율 (0~1, 시스템 계산값)	No
`items[].sleepLog.solMinutes`	number	잠들기까지 걸린 시간 (분)	No
`items[].sleepLog.wasoMinutes`	number	중간에 깬 시간 (분)	No
`items[].sleepLog.sleepQuality`	number	수면의 질 (1~5 등급)	No
`items[].sleepLog.positiveFactorIds`	array	긍정적 수면 요인 ID 목록	Yes
`items[].sleepLog.negativeFactorIds`	array	부정적 수면 요인 ID 목록	Yes
`items[].sleepLog.pill`	boolean	수면제 복용 여부	Yes
`items[].sleepLog.napMinutes`	number	낮잠 시간 (분)	Yes
`items[].sleepLog.positiveCustomFactors`	array	사용자 정의 긍정적 수면 요인 목록	Yes
`items[].sleepLog.negativeCustomFactors`	array	사용자 정의 부정적 수면 요인 목록	Yes
`items[].sleepLog.isTemporary`	boolean	임시 기록 여부	Yes
`items[].sleepLog.createdAt`	number	생성 일시 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)	Yes
`items[].sleepLog.updatedAt`	number	최종 수정 일시 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)	Yes
`items[].goalAdherence`	object	수면 목표 달성 정보 (없을 시 null)	No
`items[].goalAdherence.id`	string	목표 달성 기록 고유 ID	Yes
`items[].goalAdherence.targetDayIndex`	number	목표 대상 일차	Yes

400 Bad Request - 잘못된 요청

예시: 잘못된 파라미터 (INVALID_PARAMETERS - 10002)

{
  "code": 10002,
  "message": "INVALID_PARAMETERS",
  "detail": "시작 일차는 종료 일차보다 작거나 같아야 합니다.",
  "metadata": {
    "startDayIndex": 10,
    "endDayIndex": 5
  }
}

403 Forbidden - 권한 없음

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

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

500 Internal Server Error - 서버 내부 오류

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

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

설명

이 API는 사용자의 특정 일차 범위 수면 기록을 조회하는 핵심 기능입니다.
수면 기록 유형별 응답:
- 완전한 수면 기록: 모든 필드가 포함된 완성된 수면 데이터
- DNS 기록: 전혀 잠을 자지 못한 경우, 수면 관련 필드는 null 또는 0
- 임시 기록: 부분적으로 입력된 미완성 수면 데이터 (isTemporary: true)
자동 계산 필드:
- tstMinutes: 총 수면 시간 = TIB - SOL - WASO
- sleepEfficiency: 수면 효율 = TST / TIB (0~1 사이의 값)
데이터 활용:
- 수면 패턴 분석 및 개인화된 수면 목표 설정
- 주간/월간 수면 통계 및 리포트 생성
- 수면 데이터 시각화 (차트, 그래프)
- 기간별 수면 목표 달성률 분석

개요​

주요 특징​

데이터 활용​

제약사항​

수면 기록 범위 조회​

Headers​

Query Parameters​

Responses​

설명​

개요