퀴즈 응답 제출 API

퀴즈 응답 제출 API는 사용자가 특정 퀴즈에 대한 답변을 제출할 때 호출하는 API입니다. 퀴즈 응답 처리와 함께 성공 여부를 반환합니다.

주의사항

• 퀴즈 유효성 확인: 존재하지 않는 퀴즈 ID는 응답할 수 없습니다.
• 옵션 유효성 확인: 퀴즈에 존재하지 않는 선택지는 선택할 수 없습니다.
• 사용자 권한: 자신의 퀴즈만 응답 가능하며, 다른 사용자의 퀴즈 응답은 불가능합니다.
• 중복 응답: 동일한 퀴즈에 대한 중복 응답이 가능하며, 최신 응답으로 업데이트됩니다.
• 언어 지원: Accept-Language 헤더를 통해 응답 언어를 지정해야 합니다.

퀴즈 응답 제출

특정 퀴즈에 대한 답변을 제출하고 성공 여부를 반환합니다.

• HTTP Method: POST
• Path: /learning/quiz/{quizId}/answers
• 인증: Access Token 필요 (Authorization: Bearer {accessToken})

Headers

Header	Type	Description	Required
Authorization	string	Bearer 토큰 형식의 JWT 액세스 토큰이 필요합니다.	Yes
Content-Type	string	요청 본문의 미디어 타입 (application/json)	Yes
Accept-Language	string	응답 언어 (de-DE, ko-KR, en-US). 기본값: de-DE	Yes

Path Parameters

Parameter	Type	Description	Required	Example
quizId	string	응답할 퀴즈의 고유 ID	Yes	quiz_123

Request Body

{
  "selectedOptionId": "option_2"
}

Field	Type	Description	Required	Example
selectedOptionId	string	선택한 옵션의 고유 ID	Yes	option_2

Responses

HTTP Status Code	설명	Error Code(s)
200 OK	퀴즈 응답 제출 성공	-
400 Bad Request	잘못된 요청 (유효하지 않은 선택지)	7003
401 Unauthorized	인증 실패	2051
404 Not Found	리소스 없음 (퀴즈, 사용자 상태)	11010, 7008
500 Internal Server Error	서버 내부 오류	11000, 11500

200 OK - 퀴즈 응답 제출 성공

성공적으로 퀴즈 응답을 제출하면 성공 여부가 반환됩니다.

{
  "success": true
}

필드	타입	설명	예시	필수 (Yes/No)
success	boolean	퀴즈 응답 제출 성공 여부	true	Yes

400 Bad Request - 유효하지 않은 선택지

{
  "code": 7003,
  "message": "INVALID_OPTION",
  "detail": "유효하지 않은 선택지입니다"
}

이 오류는 요청한 선택지 ID가 해당 퀴즈에 존재하지 않을 때 발생합니다.

401 Unauthorized - 인증 실패

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

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

404 Not Found - 퀴즈를 찾을 수 없음

{
  "code": 11010,
  "message": "QUIZ_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-quiz.service.ts의 submitQuizResponse 메서드의 로직을 기반으로 합니다.
• 주요 처리 단계 (서비스 로직 내):
  1. 사용자 상태 조회: 사용자의 활성 사이클 ID와 현재 진행 상태 조회 (GetUserStateQuery)
  2. 퀴즈 응답 명령 실행: SubmitQuizAnswerCommand를 통해 퀴즈 응답 처리
  3. 데이터 변환: 응답 결과를 SubmitQuizResponseDto 형태로 변환
• 응답 검증 로직:
  • 퀴즈 존재 여부 확인
  • 선택지 유효성 검증
  • 정답 여부 판단 및 설명 제공
• 이벤트 발행: 퀴즈 응답 시 다음 도메인 이벤트들이 발행됩니다:
  • QuizResultRecordedEvent: 퀴즈 결과 기록 이벤트

사용 예시

예시 1: 퀴즈 응답 제출

curl -X POST "https://api.example.com/learning/quiz/quiz_123/answers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Accept-Language: ko-KR" \
  -d '{
    "selectedOptionId": "option_2"
  }'

응답:

{
  "success": true
}

예시 2: 다른 언어로 퀴즈 응답

curl -X POST "https://api.example.com/learning/quiz/quiz_123/answers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Accept-Language: de-DE" \
  -d '{
    "selectedOptionId": "option_1"
  }'

응답:

{
  "success": true
}

활용 사례

• 학습 효과 측정: 퀴즈를 통해 사용자의 학습 이해도를 측정
• 진행률 추적: 퀴즈 응답을 통해 학습 진행률 업데이트
• 개인화 학습: 응답 패턴을 분석하여 개인화된 학습 콘텐츠 제공
• 통계 분석: 퀴즈 응답 데이터를 통한 학습 패턴 분석
• 이벤트 기반 처리: 퀴즈 완료 시 다음 단계 학습 콘텐츠 해금 등

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-07-11	elizabeth@weltcorp.com	최초 문서 작성