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

사용자 레슨 상태 조회 API

사용자 레슨 상태 조회 API는 현재 사용자의 모든 레슨에 대한 해금 상태, 완료 상태, 진행 상황 등을 조회하는 기능을 제공합니다. 이 API는 사용자별 학습 진도를 실시간으로 파악할 수 있도록 하며, 클라이언트는 이 정보를 세션/레슨 목록과 조합하여 UI를 구성할 수 있습니다.

레슨 상태 조회​

현재 로그인한 사용자의 모든 레슨에 대한 개별 상태와 전체 진행 요약 정보를 조회합니다. 각 레슨의 해금 여부, 완료 여부, 차단 이유 등의 세부 정보를 포함합니다.

  • HTTP Method: GET
  • Path: /v1/learning/lessons/me/lesson-states
  • 인증: JWT Token 필요 (Authorization: Bearer {accessToken})

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}JWT 액세스 토큰을 통한 인증Yes
Accept-Languagestring언어 코드 (de-DE, ko-KR, en-US)Yes

Responses​

HTTP Status Code설명Error Code(s)
200 OK레슨 상태 조회 성공-
404 Not Found사용자 상태를 찾을 수 없음7008
401 UnauthorizedJWT 토큰 인증 실패2051
500 Internal Server Error서버 내부 오류11000
200 OK - 레슨 상태 조회 성공

성공적으로 사용자의 레슨 상태를 조회하면 GetUserLessonStatesResponseDto에 정의된 정보가 반환됩니다. 여기에는 사용자 ID, 각 레슨의 상태 목록, 전체 진행 요약이 포함됩니다.

레슨 상태 응답 예시​

{
  "userId": "user_123",
  "bundleId": "latest_learning_bundle_uuid",
  "states": [
    {
      "label": 1,
      "status": "COMPLETED",
      "unlockedAt": 1711929600000,
      "completedAt": 1712048400000,
      "lastAccessedAt": 1712048400000
    },
    {
      "label": 2,
      "status": "UNLOCKED",
      "unlockedAt": 1712048500000,
      "lastAccessedAt": 1712050000000
    },
    {
      "label": 3,
      "status": "LOCKED"
    },
    {
      "label": 46,
      "status": "LOCKED",
      "remainingDaysToUnlock": 72,
      "blockedReason": "TREATMENT_END_LESSON"
    }
  ]
}

상세 필드 설명​

기본 응답 필드

  • userId: 사용자 ID
  • bundleId: 학습 콘텐츠 번들 ID

states (배열)

  • label: 레슨 라벨 번호 (1일차=1, 2일차=2, ...)
  • status: 레슨 상태 (LOCKED, UNLOCKED, BLOCKED, IN_PROGRESS, COMPLETED)
  • unlockedAt: 레슨 해금 시간 (타임스탬프, 밀리초) - 해금된 레슨만 포함
  • completedAt: 레슨 완료 시간 (타임스탬프, 밀리초) - 완료된 레슨만 포함
  • lastAccessedAt: 마지막 접근 시간 (타임스탬프, 밀리초) - 접근한 레슨만 포함
  • remainingDaysToUnlock: 최종 레슨 해금까지 남은 일수 - 최종 레슨이고 LOCKED 상태일 때만 포함
  • blockedReason: 차단 이유 (Lesson Blocked Reason 참조) - 차단된 레슨만 포함

GetUserLessonStatesResponseDto 상세​

사용자 레슨 상태 조회 응답 정보를 담는 DTO에 대한 상세 설명입니다.

필드타입설명예시필수 (Yes/No)
userIdstring사용자 IDuser_123Yes
bundleIdstring학습 콘텐츠 번들 IDlatest_learning_bundle_uuidYes
statesarray레슨 상태 목록UserLessonStateDto[]Yes

UserLessonStateDto 상세​

개별 레슨 상태 정보를 담는 DTO에 대한 상세 설명입니다.

필드타입설명예시필수 (Yes/No)
labelinteger레슨 라벨 번호 (1일차=1, 2일차=2, ...)1Yes
statusstring레슨 상태 (LessonStatus 참조)COMPLETEDYes
unlockedAtinteger레슨 해금 시간 (Unix 타임스탬프, 밀리초 단위)1711929600000No
completedAtinteger레슨 완료 시간 (Unix 타임스탬프, 밀리초 단위)1712048400000No
lastAccessedAtinteger마지막 접근 시간 (Unix 타임스탬프, 밀리초 단위)1712048400000No
remainingDaysToUnlockinteger최종 레슨 해금까지 남은 일수 (최종 레슨이고 LOCKED 상태일 때만 포함)72No
blockedReasonstring차단 이유 (LessonBlockedReason 참조)TREATMENT_END_LESSONNo

레슨 상태별 설명​

상태설명포함 필드
LOCKED아직 해금되지 않은 레슨label, status
UNLOCKED해금되었지만 아직 완료하지 않은 레슨label, status, unlockedAt, lastAccessedAt*
IN_PROGRESS현재 진행 중인 레슨label, status, unlockedAt, lastAccessedAt
COMPLETED완료된 레슨label, status, unlockedAt, completedAt, lastAccessedAt*
BLOCKED특정 조건으로 인해 차단된 레슨 (예: 치료 완료 필요)label, status, remainingDaysToUnlock, blockedReason

*lastAccessedAt은 사용자가 해당 레슨에 접근한 기록이 있을 때만 포함됩니다.

404 Not Found - 사용자 상태를 찾을 수 없음

사용자의 활성 주기를 찾을 수 없는 경우 발생합니다.

{
  "code": 7008,
  "message": "USER_STATE_NOT_FOUND",
  "detail": "사용자의 활성 주기를 찾을 수 없습니다"
}
401 Unauthorized - JWT 토큰 인증 실패

유효하지 않거나 만료된 JWT 토큰으로 요청한 경우 발생합니다.

{
  "code": 2051,
  "message": "UNAUTHORIZED",
  "detail": "JWT 토큰이 유효하지 않습니다"
}
500 Internal Server Error - 서버 내부 오류

서버에서 예상치 못한 오류가 발생한 경우입니다.

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

사용 사례​

학습 진도 화면 구성​

클라이언트는 이 API를 사용하여 다음과 같은 학습 진도 화면을 구성할 수 있습니다:

  1. 레슨 목록 필터링: 상태별로 레슨을 분류하여 표시
  2. 접근 제어: LOCKED 또는 BLOCKED 상태인 레슨에 대한 접근 제한
  3. 치료 완료 레슨 안내: BLOCKED 상태의 레슨에 대해 remainingDaysToUnlock 시간과 blockedReason을 표시

캐싱 전략​

  • 이 API는 사용자의 학습 상태가 변경될 때마다 업데이트되므로, 클라이언트는 적절한 캐싱 전략을 사용해야 합니다.
  • 레슨 완료 후에는 반드시 이 API를 다시 호출하여 최신 상태를 가져오는 것을 권장합니다.
  • 앱 시작 시 또는 학습 화면 진입 시 호출하여 최신 진도를 확인하세요.

변경 이력​

버전날짜작성자변경 내용
1.0.02025-07-10elizabeth@weltcorp.com최초 문서 작성
1.1.02025-07-10elizabeth@weltcorp.comUserLessonStatesSummaryDto 제거 - 응답에서 summary 필드 삭제, 개별 레슨 상태만 제공