추천 이완요법 콘텐츠 조회 API

추천 이완요법 콘텐츠 조회 API는 사용자 가입일 기준으로 개인화된 추천 콘텐츠를 제공하는 기능입니다. 사용자가 가입한 지 5일 이내에는 일별로 추천 콘텐츠를 제공하며, 6일차부터는 추천 기간이 만료됩니다.

일일 추천 콘텐츠 조회

사용자의 가입일을 기준으로 현재 일차를 계산하여 해당 일차의 추천 콘텐츠를 반환합니다. 추천 기간(1-5일) 중에는 구체적인 콘텐츠 ID를 제공하며, 추천 기간 만료 후에는 일차 정보만 제공합니다.

• HTTP Method: GET
• Path: /v1/relaxation/daily/content
• 인증: JWT 토큰 필요 (Authorization: Bearer {accessToken})

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증 토큰 (JWT)	Yes
Accept-Language	string	응답 언어 지정 (Language Code 참조, 예: de-DE, en-US, ko-KR)	Yes

Responses

HTTP Status Code	설명	Error Code(s)
200 OK	추천 콘텐츠 조회 성공	-
401 Unauthorized	인증되지 않음	2051
404 Not Found	추천 콘텐츠를 찾을 수 없음	13010
409 Conflict	활성화된 번들이 없음	13031
500 Internal Server Error	서버 내부 오류	13000

200 OK - 추천 콘텐츠 조회 성공

성공적으로 추천 콘텐츠를 조회하면 RelaxationRecommendationResponseDto에 정의된 추천 정보가 반환됩니다. 추천 기간 중에는 구체적인 콘텐츠 ID가 포함되며, 추천 기간 만료 후에는 콘텐츠 ID 없이 일차 정보만 제공됩니다.

추천 기간 중 (1-5일차) 응답 예시

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 1,
  "contentId": "category_01_content_01_uuid",
  "completed": false
}

추천 기간 만료 후 (6일차 이후) 응답 예시

{
  "bundleId": "latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34",
  "currentDayIndex": 6
}

RelaxationRecommendationResponseDto 필드 설명

필드	타입	설명	예시	필수 (Yes/No)
bundleId	string	번들 ID	latest_budle_uuid_123jhr34h_bh54_1l239_dfnle34	Yes
currentDayIndex	integer	현재 일차 (1-5: 추천 기간, 6 이상: 추천 기간 만료)	1	Yes
contentId	string | undefined	추천 콘텐츠 ID (1-5일차에만 제공)	category_01_content_01_uuid	No
completed	boolean | undefined	콘텐츠 완료 상태 - 사용자가 해당 콘텐츠를 완료했는지 여부 (true: 완료됨, false: 미완료됨)	false	No

401 Unauthorized - 인증되지 않음

유효하지 않은 JWT 토큰이 제공되었거나 토큰이 만료된 경우 반환됩니다.

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 추천 콘텐츠를 찾을 수 없음

지정된 추천 콘텐츠를 찾을 수 없는 경우 반환됩니다.

{
  "code": 13010,
  "message": "CONTENT_NOT_FOUND",
  "detail": "콘텐츠를 찾을 수 없음"
}

409 Conflict - 활성화된 번들이 없음

현재 활성화된 이완요법 번들이 존재하지 않는 경우 반환됩니다.

{
  "code": 13031,
  "message": "NO_ACTIVE_BUNDLE",
  "detail": "활성화된 번들이 없음"
}

500 Internal Server Error - 서버 내부 오류

데이터베이스 연결 실패 등 서버 내부 오류가 발생한 경우 반환됩니다.

{
  "code": 13000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

리포지토리 오류 (13500)

{
  "code": 13500,
  "message": "REPOSITORY_ERROR",
  "detail": "리포지토리 오류"
}

주요 특징

개인화된 추천 시스템

• 사용자 가입일을 기준으로 5일간의 추천 기간 제공
• 각 일차별로 서로 다른 이완요법 콘텐츠 추천
• 추천 기간 만료 후에는 사용자가 자유롭게 콘텐츠 선택 가능

추천 기간 관리

• 1-5일차: 추천 기간 중 - contentId 포함하여 구체적인 추천 콘텐츠 제공
• 6일차 이후: 추천 기간 만료 - contentId 없이 일차 정보만 제공
• currentDayIndex를 통해 현재 추천 상태 확인 가능

다국어 지원

• Accept-Language 헤더를 통해 원하는 언어로 응답 받기 가능
• 지원 언어: 독일어(de-DE), 한국어(ko-KR), 영어(en-US)
• 언어별 콘텐츠 제목 및 설명 제공

응답 구조

• bundleId: 현재 활성 번들의 고유 식별자
• currentDayIndex: 사용자 가입일 기준 현재 일차 (1부터 시작)
• contentId: 추천 콘텐츠 ID (1-5일차에만 제공)

사용 시나리오

1. 신규 사용자 (1-5일차):

   • 매일 새로운 추천 콘텐츠 제공
   • 이완요법 학습을 위한 단계별 가이드

2. 기존 사용자 (6일차 이후):

   • 추천 기간 만료 안내
   • 사용자 주도적 콘텐츠 선택 유도

캐싱 고려사항

• 추천 결과는 사용자별로 캐시되어 빠른 응답 제공
• 일차 변경 시 자동으로 캐시 무효화
• 번들 업데이트 시 모든 추천 캐시 갱신

---

에러 응답

발생 가능한 에러들

HTTP 상태 코드	에러 코드	에러 메시지	설명
401	INVALID_TOKEN (2051)	인증되지 않음	인증 토큰이 없거나 유효하지 않을 때
404	CONTENT_NOT_FOUND (13010)	콘텐츠를 찾을 수 없음	추천 콘텐츠를 찾을 수 없을 때
409	NO_ACTIVE_BUNDLE (13031)	활성화된 번들이 없음	활성화된 번들이 존재하지 않을 때
500	SERVER_ERROR (13000)	서버 내부 오류	예상치 못한 서버 오류가 발생했을 때
500	REPOSITORY_ERROR (13500)	리포지토리 오류	데이터베이스 접근 중 오류가 발생했을 때

에러 응답 예시

401 Unauthorized - 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 추천 콘텐츠 없음

{
  "code": 13010,
  "message": "CONTENT_NOT_FOUND",
  "detail": "콘텐츠를 찾을 수 없음"
}

404 Not Found - 활성 번들 없음

{
  "code": 13031,
  "message": "NO_ACTIVE_BUNDLE",
  "detail": "활성화된 번들이 없음"
}

500 Internal Server Error - 서버 오류

{
  "code": 13000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

500 Internal Server Error - 데이터베이스 오류

{
  "code": 13500,
  "message": "REPOSITORY_ERROR",
  "detail": "데이터베이스 연결 및 처리 오류"
}

성능 정보

• 평균 응답 시간: 10-50ms (캐시 활용 시)
• 최대 응답 시간: 500ms (캐시 미스 시)
• 캐시 TTL: 24시간 (일차별 추천)
• 캐시 적중률: 95% 이상 (예상)

변경 이력

버전	날짜	작성자	변경 내용
0.53.19	2025-11-05	pibi@weltcorp.com	콘텐츠 완료 상태 추가: completed 필드 추가로 사용자의 콘텐츠 완료 여부 제공
1.0.0	2025-07-18	elizabeth@weltcorp.com	최초 문서 작성