버전: 0.68.0

일차-날짜 매핑 조회 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

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Accept-Language`	`de-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": "일시 정지"
    }
  ]
}

필드	타입	설명
`userId`	string	사용자 ID
`userCycleId`	string	현재 활성 주기 ID
`currentDayIndex`	number	현재 치료 일차
`dayMappings`	array	일차-날짜 매핑 배열
`dayMappings[].dayIndex`	number	치료 일차 (1부터 시작)
`dayMappings[].date`	string	해당 일차의 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준)
`suspensionPeriods`	array	치료 활동 일시 정지 기간 배열
`suspensionPeriods[].startDate`	string	정지 시작 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준)
`suspensionPeriods[].endDate`	string\|null	정지 종료 날짜 (YYYY-MM-DD 형식, 사용자 타임존 기준), null이면 현재 진행 중
`suspensionPeriods[].reason`	string	정지 사유 (선택적)

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": "서버 내부 오류가 발생했습니다."
}

개요​

일차 계산 로직​

일차-날짜 매핑 조회​

Headers​

Request Body​

Responses​

개요

일차 계산 로직

일차-날짜 매핑 조회

Headers

Request Body

Responses