assessment 모듈

책임: 레벨테스트 (비로그인 가능), 본강의 퀴즈/유닛 시험, 최종 합격 판정, 문제은행 관리.

의존:

• identity — 응시자 식별 (레벨테스트 제외)
• learning — 수강권이 있는 강의의 시험만 응시 가능
• notification — 합격/불합격 결과 알림

관련 DB 테이블:

• exam, exam_question — 유닛/모듈별 시험
• question_bank — 문제 풀
• quiz_result, quiz_result_answer — 응시 결과/답안
• level_test_list, level_test_list_right, level_test_examples, level_test_answer, level_test_poll, level_test_poll_answer — 레벨테스트 전용 (6개 테이블)

현재 UI 상태:

• 유닛 시험은 구현됨. 응시 /my-class/unit-quiz/[unit]/[kind], 결과 /my-class/unit-result/[unit]/[kind] (TEC 은 tec- 접두어). 도메인 규칙은 src/lib/exam.ts, 제출은 서버 액션 src/actions/exam.ts 에 있고, 원본 myclass/unitSloving.php · quiz_proc.php 의 판정을 그대로 옮겼다.
  • 합격선 70점 (문항당 5점 × 20문항). exam.pass_score 도 70 으로 맞춰 두었다.
  • 차수: TESOL A/B/C, TEC A/B. 직전 유닛을 통과해야 다음 유닛이 열리고, 차수는 순서대로만 열린다.
  • 복수정답 문항은 checkbox 로 렌더하고, 고른 집합이 정답 집합과 완전히 일치해야 득점한다.
• 남은 것: 합격/불합격 알림 발송(notification 모듈 대기), 그리고 레벨테스트. /tesol-lab/level-test 는 여전히 신청 폼(STEP 01)뿐이고, 원본 tesolLab/leveltest_form_v_01.php 의 객관식 15 + 주관식 5 응시 화면(STEP 02)이 없다.

예상 API 엔드포인트

레벨테스트 (비로그인 가능)

GET /api/assessment/level-test

레벨테스트 문제 세션 시작. 보통 랜덤 셔플된 N 개 문항.

• Auth: 불필요 (비회원도 응시 가능)
• Query: ?count=20 (기본 문항 수)
• Response:

  {
    sessionId: string;   // 서버 세션 or JWT (정답 공개 방지)
    questions: Array<{
      id: number;
      text: string;
      choices: string[];
      imageUrl?: string;
    }>;
  }
  

• 쿼리 대상: level_test_list (문제), level_test_examples (보기)
• 보안: level_test_list_right (정답) 은 절대 노출하지 않음. 채점은 서버에서.

POST /api/assessment/level-test/submit

레벨테스트 답안 제출 + 즉시 채점.

• Auth: 불필요
• Body:

  {
    sessionId: string;
    answers: Array<{ questionId: number; choiceIndex: number }>;
    respondent?: {
      name: string;
      email: string;
      phone: string;
    };
  }
  

• Response:

  {
    score: number;
    level: 'beginner' | 'intermediate' | 'advanced';
    recommendation: string;
    resultId: number;
  }
  

• 사이드이펙트:
  • level_test_answer INSERT (응시 로그)
  • level_test_poll + level_test_poll_answer INSERT (통계용)
  • notification 으로 "상담 요청" 이벤트 (respondent 있는 경우)

GET /api/assessment/level-test/results/[resultId]

응시 결과 조회 (URL 공유 가능).

• Auth: 불필요 (resultId 를 아는 사람만)
• Response: 응시 결과 상세 + 상담 예약 CTA

본강의 시험/퀴즈

GET /api/assessment/exams?courseCode=TESOL

특정 강의에서 응시 가능한 시험 목록.

• Auth: 필수 + learning 모듈의 수강권 검증
• Response:

  {
    exams: Array<{
      id: number;
      unitNumber: number;
      title: string;
      questionCount: number;
      attemptCount: number;       // 내 응시 횟수
      maxAttempts: number;        // 보통 2~3회
      bestScore: number | null;
      passed: boolean;
      locked: boolean;            // 이전 유닛 미합격 시 잠금
    }>
  }
  

POST /api/assessment/exams/[examId]/start

시험 응시 시작. 세션 생성 + 시험 시간 타이머 시작.

• Auth: 필수
• Response:

  {
    attemptId: number;
    startedAt: string;
    durationSec: number;
    questions: Array<{
      id: number;
      text: string;
      choices: string[];
    }>;
  }
  

• 사이드이펙트: quiz_result INSERT (status='in_progress')

POST /api/assessment/exams/attempts/[attemptId]/submit

시험 제출 및 채점.

• Auth: 필수
• Body: { answers: Array<{ questionId: number; choiceIndex: number }> }
• Response:

  {
    score: number;
    passed: boolean;
    correctCount: number;
    totalCount: number;
    canRetry: boolean;
  }
  

• 사이드이펙트:
  • quiz_result_answer INSERT (문항별)
  • quiz_result UPDATE (status='completed', score 저장)
  • 최종 유닛 합격 시 notification "유닛 합격" 이벤트
  • 전체 과정 합격 시 notification "최종 합격" 이벤트 + learning 모듈에 passDate 갱신 훅

시험 결과 조회

GET /api/assessment/results/me?courseCode=TESOL

내 전체 시험 결과 (unit 별 점수).

• Auth: 필수
• Response:

  {
    perUnit: Array<{
      unitNumber: number;
      bestScore: number;
      attempts: number;
      passed: boolean;
    }>;
    overall: {
      passed: boolean;
      passedAt: string | null;
    };
  }
  

• 대체 대상: /my-class/result-of-course (현재 scores 하드코딩)

관리자용 (낮은 우선순위)

GET /api/assessment/admin/question-bank?courseCode=...

문제은행 관리. admin 권한 필요.

POST /api/assessment/admin/questions

문제 등록/수정.

GET /api/assessment/admin/attempts?memberId=...

특정 회원의 응시 로그 조회.