본문으로 건너뛰기
버전: 0.68.0

레슨 완료 API

레슨 완료 API는 사용자가 특정 레슨을 완료했을 때 호출하는 API입니다. 레슨 완료 처리와 함께 다음 레슨 해금 여부를 확인하여 응답합니다.

주의사항
  • 레슨 상태 확인: 비활성화된 레슨은 완료할 수 없습니다.
  • 사용자 권한: 자신의 레슨만 완료 가능하며, 다른 사용자의 레슨 완료는 불가능합니다.
  • 순차 해금: 일반 레슨은 순차적으로 해금되며, 최종 레슨은 치료 기간 완료 조건을 만족해야 합니다.
  • 중복 완료: 이미 완료된 레슨도 중복 완료 가능하며, 최신 완료 시간으로 업데이트됩니다.

레슨 완료 처리​

특정 레슨을 완료 상태로 변경하고 관련 이벤트를 발행합니다.

  • HTTP Method: POST
  • Path: /learning/lessons/{lessonId}/complete
  • 인증: Access Token 필요 (Authorization: Bearer {accessToken})

Headers​

HeaderTypeDescriptionRequired
AuthorizationstringBearer 토큰 형식의 JWT 액세스 토큰이 필요합니다.Yes
Accept-Languagestring응답 언어 (de-DE, ko-KR, en-US). 기본값: de-DEYes

Path Parameters​

ParameterTypeDescriptionRequiredExample
lessonIdstring완료할 레슨의 고유 IDYeslesson_123

Request Body​

이 API는 Request Body를 필요로 하지 않습니다.

Responses​

HTTP Status Code설명Error Code(s)
200 OK레슨 완료 처리 성공-
400 Bad Request잘못된 요청 (비활성화된 레슨)11015
401 Unauthorized인증 실패2051
404 Not Found리소스 없음 (레슨, 사용자 상태)11010, 7008
500 Internal Server Error서버 내부 오류11000, 11500
200 OK - 레슨 완료 처리 성공

성공적으로 레슨을 완료하면 완료 처리 성공 여부가 반환됩니다.

{
  "success": true
}
필드타입설명예시필수 (Yes/No)
successboolean레슨 완료 처리 성공 여부trueYes
400 Bad Request - 레슨 비활성화
{
  "code": 11015,
  "message": "LESSON_INACTIVE",
  "detail": "비활성화된 레슨입니다"
}

이 오류는 요청한 레슨이 비활성화 상태일 때 발생합니다.

401 Unauthorized - 인증 실패
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

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

404 Not Found - 레슨 없음
{
  "code": 11010,
  "message": "LESSON_NOT_FOUND",
  "detail": "존재하지 않는 레슨입니다"
}

이 오류는 요청한 레슨 ID가 존재하지 않을 때 발생합니다.

404 Not Found - 사용자 상태 없음
{
  "code": 7008,
  "message": "USER_STATE_NOT_FOUND",
  "detail": "사용자의 활성 주기를 찾을 수 없습니다"
}

이 오류는 사용자의 활성 사이클 정보가 존재하지 않을 때 발생합니다.

500 Internal Server Error - 서버 내부 오류

일반적인 서버 오류 (11000)

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

데이터베이스 접근 오류 (11500)

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

이 오류들은 처리 중 예기치 않은 서버 내부 문제나 데이터베이스 접근 문제가 발생했을 때 반환됩니다.

설명​

  • 이 API는 apps/dta-wide-api/src/app/learning/services/learning-lesson.service.ts의 completeLesson 메서드의 로직을 기반으로 합니다.
  • 주요 처리 단계 (서비스 로직 내):
    1. 사용자 상태 조회: 사용자의 활성 사이클 ID와 현재 진행 상태 조회 (GetUserStateQuery)
    2. 레슨 완료 명령 실행: CompleteLessonCommand를 통해 레슨 완료 처리
    3. 데이터 변환: 완료 결과를 CompleteLessonResponseDto 형태로 변환
  • 해금 로직:
    • 일반 레슨 (라벨 1~45): 이전 레슨 완료 시 순차적으로 해금
    • 최종 레슨 (라벨 46): 치료 기간 완료 조건 달성 시 해금
  • 이벤트 발행: 레슨 완료 시 다음 도메인 이벤트들이 발행됩니다:
    • LessonCompletedEvent: 레슨 완료 이벤트
    • SessionProgressUpdatedEvent: 세션 진행률 업데이트 이벤트
    • LessonUnlockedEvent: 다음 레슨 해금 이벤트 (조건부)
    • AllLessonsCompletedEvent: 모든 레슨 완료 이벤트 (조건부)

사용 예시​

예시 1: 일반 레슨 완료 (다음 레슨 해금)

curl -X POST "https://api.example.com/learning/lessons/lesson_001/complete" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept-Language: ko-KR"

응답:

{
  "success": true
}

예시 2: 세션 마지막 레슨 완료 (다음 레슨 없음)

curl -X POST "https://api.example.com/learning/lessons/lesson_010/complete" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Accept-Language: de-DE"

응답:

{
  "success": true
}

활용 사례​

  • 학습 진행 관리: 사용자의 레슨 완료 상태를 관리하고 다음 레슨 해금 처리
  • 진행률 추적: 세션별 학습 진행률을 실시간으로 업데이트
  • 이벤트 기반 알림: 레슨 완료 시 푸시 알림이나 이메일 알림 발송
  • 통계 분석: 사용자별 학습 패턴 분석을 위한 완료 데이터 수집
  • 게임화 요소: 레슨 완료 시 포인트나 뱃지 지급 등의 보상 시스템 연동

변경 이력​

버전날짜작성자변경 내용
0.1.02024-07-09elizabeth@weltcorp.com최초 문서 작성
0.2.02024-07-09elizabeth@weltcorp.com에러 응답 형식 통일, 인증 토큰 요구사항 수정
0.3.02024-07-09elizabeth@weltcorp.comlabel 필드 추가, title 필드 제거, DTO 구조 개선
0.4.02025-07-10elizabeth@weltcorp.com순차 학습 제약 추가 - 이전 레슨 미완료 시 403 오류 응답 추가
0.5.02025-07-10elizabeth@weltcorp.comResponse DTO 간소화 - CompleteLessonResponseDto를 success boolean 필드만 포함하도록 변경
0.6.02025-07-11elizabeth@weltcorp.com실제 구현에 맞춰 문서 수정 - Request Body 제거, Accept-Language 헤더 요구사항 정확히 반영, 에러 응답 실제 ApiResponse와 일치