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

일차-날짜 매핑 조회 API

개요​

일차-날짜 매핑 조회 API는 사용자의 현재 활성화된 치료 주기의 일차(dayIndex)와 실제 날짜의 매핑 정보를 제공합니다. 이 API는 치료 활동 일시 정지 기간을 제외하고 일차를 계산하여, 사용자가 현재 치료의 어느 단계에 있는지 정확하게 파악할 수 있도록 도와줍니다.

일차 계산 로직​

일차(dayIndex) 계산 시 다음 규칙이 적용됩니다:

  • 치료 주기 시작일: 1일차부터 시작
  • 정지 기간 처리: 치료 활동 일시 정지 기간은 일차 계산에서 제외
  • 00:00시 기준: 정지 시작/종료 시각이 00:00시인지 여부에 따라 다르게 처리
    • 정지 시작이 00:00시인 경우: 해당 날짜부터 일차에서 제외
    • 정지 시작이 00:00시가 아닌 경우: 다음 날부터 일차에서 제외
    • 정지 종료가 00:00시인 경우: 해당 날짜부터 일차에 포함
    • 정지 종료가 00:00시가 아닌 경우: 해당 날짜는 일차에 포함
  • 사용자 타임존: 사용자의 설정된 타임존을 기준으로 날짜 계산
  • DST(일광절약시간) 처리:
    • 타임존 오프셋 변화(DST 전환)를 고려한 정확한 날짜 계산
    • DST 전환으로 인한 하루 길이 변화(23시간 또는 25시간) 반영
    • 타임존별 DST 규칙에 따른 자동 오프셋 조정
  • 일차 제한:
    • currentDayIndex는 최대 90까지만 증가하며, 90을 넘길 수 없음
    • dayMappings 배열의 모든 항목이 포함되지만, 90일 이후의 dayIndex는 계속 90으로 유지됨

일차-날짜 매핑 조회​

사용자의 현재 활성 주기에 대한 일차-날짜 매핑을 조회합니다.

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

Headers​

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

Request Body​

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

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
401 Unauthorized인증 실패 (토큰 누락, 만료, 유효하지 않음)-
404 Not Found사용자를 찾을 수 없음7002
500 Internal Server Error서버 내부 오류7000
200 OK - 성공

일차-날짜 매핑 조회 성공:

케이스

  • timezone: Asia/Seoul
  • 오늘: 2025년 5월 6일
  • 시작 날짜: 2025년 5월 1일
  • 치료 중단 기간: 2025년 5월 4일 00:00:00 중단 시작 / 2025년 5월 6일 00:00:00 다시 시작
{
  "userId": "user_123",
  "userCycleId": "cycle_456",
  "currentDayIndex": 4,
  "dayMappings": [
    {
      "dayIndex": 1,
      "date": "2025-05-01"
    },
    {
      "dayIndex": 2,
      "date": "2025-05-02"
    },
    {
      "dayIndex": 3,
      "date": "2025-05-03"
    },
    {
      "dayIndex": 4,
      "date": "2025-05-06"
    }
  ],
  "suspensionPeriods": [
    {
      "startDate": "2025-05-04",
      "endDate": "2025-05-05",
      "reason": "휴가"
    }
  ]
}

정지 기간이 없는 경우:

케이스

  • timezone: Asia/Seoul
  • 오늘: 2025년 5월 6일
  • 시작 날짜: 2025년 5월 1일
  • 치료 중단 기간: X
{
  "userId": "user_123",
  "userCycleId": "cycle_456",
  "currentDayIndex": 6,
  "dayMappings": [
    {
      "dayIndex": 1,
      "date": "2025-05-01"
    },
    {
      "dayIndex": 2,
      "date": "2025-05-02"
    },
    {
      "dayIndex": 3,
      "date": "2025-05-03"
    },
    {
      "dayIndex": 4,
      "date": "2025-05-04"
    },
    {
      "dayIndex": 5,
      "date": "2025-05-05"
    },
    {
      "dayIndex": 6,
      "date": "2025-05-06"
    }
  ],
  "suspensionPeriods": []
}

현재 진행 중인 정지 기간이 있는 경우:

케이스

  • timezone: Asia/Seoul
  • 오늘: 2025년 5월 6일
  • 시작 날짜: 2025년 5월 1일
  • 치료 중단 기간: 2025년 5월 4일 17:00:00 중단 시작, 2025년 5월 8일 00:00:00 다시 시작
{
  "userId": "user_123",
  "userCycleId": "cycle_456",
  "currentDayIndex": 4,
  "dayMappings": [
    {
      "dayIndex": 1,
      "date": "2025-05-01"
    },
    {
      "dayIndex": 2,
      "date": "2025-05-02"
    },
    {
      "dayIndex": 3,
      "date": "2025-05-03"
    },
    {
      "dayIndex": 4,
      "date": "2025-05-04"
    }
  ],
  "suspensionPeriods": [
    {
      "startDate": "2025-05-04",
      "endDate": "2025-05-07",
      "reason": "일시 정지"
    }
  ]
}
필드타입설명
userIdstring사용자 ID
userCycleIdstring현재 활성 주기 ID
currentDayIndexnumber현재 치료 일차
dayMappingsarray일차-날짜 매핑 배열
dayMappings[].dayIndexnumber치료 일차 (1부터 시작)
dayMappings[].datestring해당 일차의 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준)
suspensionPeriodsarray치료 활동 일시 정지 기간 배열
suspensionPeriods[].startDatestring정지 시작 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준)
suspensionPeriods[].endDatestring|null정지 종료 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준), null이면 현재 진행 중
suspensionPeriods[].reasonstring정지 사유 (선택적)
401 Unauthorized - 인증 실패

예시: 토큰이 누락된 경우

{
  "message": "Unauthorized",
  "statusCode": 401
}

예시: 토큰이 만료된 경우

{
  "message": "Token has expired",
  "statusCode": 401
}
404 Not Found - 사용자를 찾을 수 없음

예시: 사용자 정보 없음 (USER_NOT_FOUND - 7002)

{
  "code": 7002,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다.",
  "metadata": {
    "userId": "user_123"
  }
}
500 Internal Server Error - 서버 내부 오류

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

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