@hed-hog/lms 0.0.304 → 0.0.305

package/src/exam/exam-attempt.service.ts

@@ -0,0 +1,1008 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+    BadRequestException,
+    Injectable,
+    NotFoundException,
+} from '@nestjs/common';
+import {
+    OBJECTIVE_EXAM_QUESTION_TYPES,
+    type ExamQuestionType,
+} from './dto/create-exam-question.dto';
+import { SaveExamAttemptAnswersDto } from './dto/save-exam-attempt-answers.dto';
+import { StartExamAttemptDto } from './dto/start-exam-attempt.dto';
+import { SubmitExamAttemptDto } from './dto/submit-exam-attempt.dto';
+
+@Injectable()
+export class ExamAttemptService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getAttemptState(
+    examId: number,
+    userId: number,
+    explicitStudentId?: number,
+  ) {
+    const exam = await this.findExamOrThrow(examId);
+    const studentId = await this.resolveStudentId(userId, explicitStudentId);
+    let attempt = await this.findRelevantAttempt(examId, studentId);
+
+    if (attempt) {
+      attempt = await this.maybeFinalizeExpiredAttempt(exam, attempt);
+    }
+
+    return this.buildAttemptPayload(exam, studentId, attempt);
+  }
+
+  async startAttempt(
+    examId: number,
+    userId: number,
+    ipAddress: string,
+    dto: StartExamAttemptDto,
+  ) {
+    const exam = await this.findExamOrThrow(examId);
+    const studentId = await this.resolveStudentId(userId, dto.studentId);
+    let activeAttempt = await this.findActiveAttempt(examId, studentId);
+
+    if (activeAttempt) {
+      activeAttempt = await this.maybeFinalizeExpiredAttempt(exam, activeAttempt);
+      if (activeAttempt.status === 'in_progress') {
+        return this.buildAttemptPayload(exam, studentId, activeAttempt);
+      }
+    }
+
+    const usedAttempts = await this.countAttempts(examId, studentId);
+    const attemptsAllowed = Math.max(exam.attempts_allowed ?? 1, 1);
+
+    if (usedAttempts >= attemptsAllowed) {
+      throw new BadRequestException('No attempts remaining for this exam');
+    }
+
+    if ((exam.exam_question ?? []).length === 0) {
+      throw new BadRequestException('Exam has no questions');
+    }
+
+    const enrollment = await this.findMatchingEnrollment(exam, studentId);
+    const created = await this.prisma.exam_attempt.create({
+      data: {
+        exam_id: exam.id,
+        student_id: studentId,
+        course_enrollment_id: enrollment?.id ?? null,
+        attempt_number: usedAttempts + 1,
+        started_at: new Date(),
+        ip_address: ipAddress || null,
+      },
+      include: {
+        exam_answer: true,
+      },
+    });
+
+    return this.buildAttemptPayload(exam, studentId, created);
+  }
+
+  async saveAnswers(
+    examId: number,
+    attemptId: number,
+    userId: number,
+    dto: SaveExamAttemptAnswersDto,
+  ) {
+    const exam = await this.findExamOrThrow(examId);
+    const studentId = await this.resolveStudentId(userId);
+    let attempt = await this.findAttemptOrThrow(examId, attemptId, studentId);
+
+    attempt = await this.maybeFinalizeExpiredAttempt(exam, attempt);
+    if (attempt.status !== 'in_progress') {
+      return this.buildAttemptPayload(exam, studentId, attempt);
+    }
+
+    await this.persistAnswers(attempt.id, exam, dto.answers);
+    const updated = await this.findAttemptOrThrow(examId, attemptId, studentId);
+
+    return this.buildAttemptPayload(exam, studentId, updated);
+  }
+
+  async submitAttempt(
+    examId: number,
+    attemptId: number,
+    userId: number,
+    dto: SubmitExamAttemptDto,
+  ) {
+    const exam = await this.findExamOrThrow(examId);
+    const studentId = await this.resolveStudentId(userId);
+    let attempt = await this.findAttemptOrThrow(examId, attemptId, studentId);
+
+    attempt = await this.maybeFinalizeExpiredAttempt(exam, attempt);
+    if (attempt.status === 'completed') {
+      return this.buildAttemptPayload(exam, studentId, attempt);
+    }
+
+    await this.persistAnswers(attempt.id, exam, dto.answers ?? []);
+    const completed = await this.completeAttempt(exam, attempt.id, dto.force ?? false);
+
+    return this.buildAttemptPayload(exam, studentId, completed);
+  }
+
+  private async persistAnswers(attemptId: number, exam: any, answers: any[]) {
+    const normalizedAnswers = new Map<
+      number,
+      {
+        examOptionId: number | null;
+        answerText: string | null;
+        matchingPairs: Array<{ leftId: string; rightId: string }>;
+      }
+    >();
+    for (const answer of answers ?? []) {
+      normalizedAnswers.set(answer.questionId, {
+        examOptionId: answer.examOptionId ?? null,
+        answerText: answer.answerText?.trim() || null,
+        matchingPairs: (answer.matchingPairs ?? []).map((pair: any) => ({
+          leftId: String(pair.leftId ?? '').trim(),
+          rightId: String(pair.rightId ?? '').trim(),
+        })),
+      });
+    }
+
+    const questionsById = new Map<number, any>(
+      (exam.exam_question ?? []).map((item: any) => [item.question_id, item]),
+    );
+
+    for (const questionId of normalizedAnswers.keys()) {
+      if (!questionsById.has(questionId)) {
+        throw new BadRequestException(`Question ${questionId} does not belong to exam`);
+      }
+    }
+
+    const questionIds = [...normalizedAnswers.keys()];
+    if (questionIds.length === 0) {
+      return;
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      const existingAnswers = await tx.exam_answer.findMany({
+        where: {
+          exam_attempt_id: attemptId,
+          question_id: { in: questionIds },
+        },
+        select: {
+          id: true,
+          question_id: true,
+        },
+      });
+
+      const existingByQuestionId = new Map(
+        existingAnswers.map((item) => [item.question_id, item.id]),
+      );
+
+      for (const [questionId, answerValue] of normalizedAnswers.entries()) {
+        const question = questionsById.get(questionId) as any;
+        const existingId = existingByQuestionId.get(questionId);
+
+        if (!question) {
+          throw new BadRequestException(
+            `Question ${questionId} does not belong to exam`,
+          );
+        }
+
+        const questionType = this.resolveQuestionType(
+          question.question?.question_type,
+        );
+
+        if (questionType === 'essay') {
+          if (!answerValue.answerText) {
+            if (existingId) {
+              await tx.exam_answer.delete({ where: { id: existingId } });
+            }
+            continue;
+          }
+
+          const payload = {
+            exam_option_id: null,
+            answer_text: answerValue.answerText,
+            is_correct: null,
+            points_awarded: 0,
+          };
+
+          if (existingId) {
+            await tx.exam_answer.update({
+              where: { id: existingId },
+              data: payload,
+            });
+          } else {
+            await tx.exam_answer.create({
+              data: {
+                exam_attempt_id: attemptId,
+                question_id: questionId,
+                ...payload,
+              },
+            });
+          }
+          continue;
+        }
+
+        if (questionType === 'fill_blank') {
+          if (!answerValue.answerText) {
+            if (existingId) {
+              await tx.exam_answer.delete({ where: { id: existingId } });
+            }
+            continue;
+          }
+
+          const parsedOptions = this.parseSpecialOptions(
+            question.question?.exam_option ?? [],
+          );
+          const expectedAnswers = this.extractFillBlankExpectedAnswers(
+            parsedOptions.fillBlankAnswers,
+          );
+
+          if (expectedAnswers.length === 0) {
+            throw new BadRequestException(
+              `Fill-blank question ${questionId} has no expected answers`,
+            );
+          }
+
+          const isCorrect = this.isFillBlankCorrect(
+            answerValue.answerText,
+            expectedAnswers,
+          );
+
+          const payload = {
+            exam_option_id: null,
+            answer_text: answerValue.answerText,
+            is_correct: isCorrect,
+            points_awarded: isCorrect ? question.question.points ?? 0 : 0,
+          };
+
+          if (existingId) {
+            await tx.exam_answer.update({
+              where: { id: existingId },
+              data: payload,
+            });
+          } else {
+            await tx.exam_answer.create({
+              data: {
+                exam_attempt_id: attemptId,
+                question_id: questionId,
+                ...payload,
+              },
+            });
+          }
+          continue;
+        }
+
+        if (questionType === 'matching') {
+          const parsedOptions = this.parseSpecialOptions(
+            question.question?.exam_option ?? [],
+          );
+          const expectedPairs = this.extractMatchingPairs(
+            parsedOptions.matchingPairs,
+          );
+
+          if (expectedPairs.length < 2) {
+            throw new BadRequestException(
+              `Matching question ${questionId} has no valid pairs`,
+            );
+          }
+
+          const sanitizedPairs = answerValue.matchingPairs.filter(
+            (pair) => pair.leftId.length > 0 && pair.rightId.length > 0,
+          );
+
+          if (sanitizedPairs.length === 0) {
+            if (existingId) {
+              await tx.exam_answer.delete({ where: { id: existingId } });
+            }
+            continue;
+          }
+
+          const isCorrect = this.isMatchingCorrect(sanitizedPairs, expectedPairs);
+
+          const payload = {
+            exam_option_id: null,
+            answer_text: JSON.stringify({ matchingPairs: sanitizedPairs }),
+            is_correct: isCorrect,
+            points_awarded: isCorrect ? question.question.points ?? 0 : 0,
+          };
+
+          if (existingId) {
+            await tx.exam_answer.update({
+              where: { id: existingId },
+              data: payload,
+            });
+          } else {
+            await tx.exam_answer.create({
+              data: {
+                exam_attempt_id: attemptId,
+                question_id: questionId,
+                ...payload,
+              },
+            });
+          }
+          continue;
+        }
+
+        if (!answerValue.examOptionId) {
+          if (existingId) {
+            await tx.exam_answer.delete({ where: { id: existingId } });
+          }
+          continue;
+        }
+
+        const option = (question?.question?.exam_option ?? []).find(
+          (item: any) => item.id === answerValue.examOptionId,
+        );
+
+        if (!option) {
+          throw new BadRequestException(
+            `Option ${answerValue.examOptionId} does not belong to question ${questionId}`,
+          );
+        }
+
+        const payload = {
+          exam_option_id: option.id,
+          answer_text: null,
+          is_correct: Boolean(option.is_correct),
+          points_awarded: option.is_correct ? question.question.points ?? 0 : 0,
+        };
+
+        if (existingId) {
+          await tx.exam_answer.update({
+            where: { id: existingId },
+            data: payload,
+          });
+        } else {
+          await tx.exam_answer.create({
+            data: {
+              exam_attempt_id: attemptId,
+              question_id: questionId,
+              ...payload,
+            },
+          });
+        }
+      }
+    });
+  }
+
+  private async completeAttempt(exam: any, attemptId: number, force: boolean) {
+    const currentAttempt = await this.prisma.exam_attempt.findUnique({
+      where: { id: attemptId },
+      include: {
+        exam_answer: true,
+      },
+    });
+
+    if (!currentAttempt) {
+      throw new NotFoundException('Attempt not found');
+    }
+
+    if (currentAttempt.status === 'completed') {
+      return currentAttempt;
+    }
+
+    const maxPoints = this.getExamMaxPoints(exam);
+    const answeredCount = currentAttempt.exam_answer.length;
+    const questionCount = (exam.exam_question ?? []).length;
+
+    if (
+      !force &&
+      exam.require_all_questions_answered_to_finish &&
+      answeredCount < questionCount
+    ) {
+      throw new BadRequestException('All questions must be answered before finishing');
+    }
+
+    const totalPoints = currentAttempt.exam_answer.reduce(
+      (sum, answer) => sum + (answer.points_awarded ?? 0),
+      0,
+    );
+
+    const maxScore = Math.max(exam.max_score ?? 100, 1);
+    const scaledScore =
+      maxPoints > 0 ? Math.round((totalPoints / maxPoints) * maxScore) : 0;
+
+    return this.prisma.exam_attempt.update({
+      where: { id: attemptId },
+      data: {
+        status: 'completed',
+        finished_at: new Date(),
+        duration_seconds: Math.max(
+          0,
+          Math.floor((Date.now() - currentAttempt.started_at.getTime()) / 1000),
+        ),
+        score: scaledScore,
+      },
+      include: {
+        exam_answer: true,
+      },
+    });
+  }
+
+  private async buildAttemptPayload(exam: any, studentId: number, attempt: any | null) {
+    const attemptsAllowed = Math.max(exam.attempts_allowed ?? 1, 1);
+    const attemptsUsed = await this.countAttempts(exam.id, studentId);
+    const maxPoints = this.getExamMaxPoints(exam);
+    const questions = this.mapQuestions(exam, attempt?.id ?? exam.id);
+
+    return {
+      exam: {
+        id: exam.id,
+        title: exam.title,
+        description: exam.description,
+        instructions: exam.instructions,
+        questionCount: questions.length,
+        maxPoints,
+        timeLimitMinutes: exam.time_limit_minutes,
+        passingScore: this.scoreToTen(exam.min_score ?? 0),
+        passingPercent: this.toPercent(exam.min_score ?? 0, exam.max_score ?? 100),
+        requireAllQuestionsAnsweredToFinish: Boolean(
+          exam.require_all_questions_answered_to_finish,
+        ),
+        showResult: Boolean(exam.show_result ?? true),
+      },
+      attempts: {
+        allowed: attemptsAllowed,
+        used: attemptsUsed,
+        remaining: Math.max(attemptsAllowed - attemptsUsed, 0),
+        canStart: attemptsUsed < attemptsAllowed,
+      },
+      questions,
+      attempt: attempt
+        ? {
+            id: attempt.id,
+            attemptNumber: attempt.attempt_number,
+            status: attempt.status,
+            startedAt: attempt.started_at,
+            finishedAt: attempt.finished_at,
+            timeRemainingSeconds: this.getRemainingSeconds(exam, attempt),
+            answeredCount: attempt.exam_answer.length,
+            answers: (attempt.exam_answer ?? []).map((answer: any) => ({
+              questionId: answer.question_id,
+              examOptionId: answer.exam_option_id,
+              answerText: answer.answer_text,
+              matchingPairs: this.extractMatchingPairsFromAnswerText(
+                answer.answer_text,
+              ),
+            })),
+            result:
+              attempt.status === 'completed'
+                ? this.mapAttemptResult(exam, attempt)
+                : null,
+          }
+        : null,
+    };
+  }
+
+  private mapAttemptResult(exam: any, attempt: any) {
+    const maxPoints = this.getExamMaxPoints(exam);
+    const maxScore = Math.max(exam.max_score ?? 100, 1);
+    const score = attempt.score ?? 0;
+    const answersByQuestion = new Map<number, any>(
+      (attempt.exam_answer ?? []).map((answer: any) => [answer.question_id, answer]),
+    );
+    const hasPendingReview = (exam.exam_question ?? []).some((item: any) => {
+      const answer = answersByQuestion.get(item.question_id);
+      return this.requiresManualReview(item.question?.question_type) && Boolean(answer);
+    });
+
+    return {
+      totalPoints: (attempt.exam_answer ?? []).reduce(
+        (sum: number, answer: any) => sum + (answer.points_awarded ?? 0),
+        0,
+      ),
+      maxPoints,
+      score,
+      scoreDisplay: this.scoreToTen(score),
+      percent: this.toPercent(score, maxScore),
+      passed: hasPendingReview ? null : score >= (exam.min_score ?? 0),
+      hasPendingReview,
+      pendingReviewCount: (exam.exam_question ?? []).filter((item: any) => {
+        const answer = answersByQuestion.get(item.question_id);
+        return this.requiresManualReview(item.question?.question_type) && Boolean(answer);
+      }).length,
+      answersSummary: (exam.exam_question ?? []).map((item: any) => {
+        const answer = answersByQuestion.get(item.question_id);
+        return {
+          questionId: item.question_id,
+          hasAnswer: Boolean(answer),
+          isCorrect:
+            typeof answer?.is_correct === 'boolean' ? Boolean(answer.is_correct) : null,
+          pointsAwarded: answer?.points_awarded ?? 0,
+          requiresManualReview: this.requiresManualReview(
+            item.question?.question_type,
+          ),
+        };
+      }),
+    };
+  }
+
+  private mapQuestions(exam: any, seedBase: number) {
+    const orderedQuestions = this.sortWithSeed(
+      exam.shuffle_questions,
+      (exam.exam_question ?? []) as any[],
+      (item: any) => item.question_id,
+      `${seedBase}:questions`,
+    );
+
+    return orderedQuestions.map((item: any, index: number) => {
+      const questionType = this.resolveQuestionType(item.question?.question_type);
+      const parsedOptions = this.parseSpecialOptions(
+        item.question?.exam_option ?? [],
+      );
+      const objectiveOptions = (item.question?.exam_option ?? []).filter(
+        (option: any) => !this.isJsonString(option.option_text),
+      );
+      const orderedOptions = this.sortWithSeed(
+        exam.shuffle_options,
+        objectiveOptions,
+        (option: any) => option.id,
+        `${seedBase}:question:${item.question_id}:options`,
+      );
+
+      return {
+        id: item.question_id,
+        order: index,
+        questionType,
+        statement: item.question.statement,
+        points: item.question.points,
+        fillBlankAnswers: parsedOptions.fillBlankAnswers,
+        matchingPairs: parsedOptions.matchingPairs,
+        matchingOptions:
+          questionType === 'matching'
+            ? this.sortWithSeed(
+                true,
+                parsedOptions.matchingPairs.map((pair: any) => ({
+                  id: pair.id,
+                  text: pair.rightText,
+                })),
+                (option: any) => this.hash(option.id),
+                `${seedBase}:question:${item.question_id}:matching-options`,
+              )
+            : [],
+        alternatives:
+          questionType === 'multiple_choice' || questionType === 'true_false'
+            ? orderedOptions.map((option: any) => ({
+                id: option.id,
+                text: option.option_text,
+              }))
+            : [],
+      };
+    });
+  }
+
+  private sortWithSeed<T>(
+    enabled: boolean,
+    items: T[],
+    getId: (item: T) => number,
+    seed: string,
+  ) {
+    const list = [...items];
+    if (!enabled) {
+      return list;
+    }
+
+    return list.sort((left, right) => {
+      const leftHash = this.hash(`${seed}:${getId(left)}`);
+      const rightHash = this.hash(`${seed}:${getId(right)}`);
+
+      if (leftHash === rightHash) {
+        return getId(left) - getId(right);
+      }
+
+      return leftHash - rightHash;
+    });
+  }
+
+  private hash(value: string) {
+    let hash = 0;
+    for (let index = 0; index < value.length; index += 1) {
+      hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+    }
+    return hash;
+  }
+
+  private async maybeFinalizeExpiredAttempt(exam: any, attempt: any) {
+    const remainingSeconds = this.getRemainingSeconds(exam, attempt);
+    if (attempt.status !== 'in_progress' || remainingSeconds === null || remainingSeconds > 0) {
+      return attempt;
+    }
+
+    return this.completeAttempt(exam, attempt.id, true);
+  }
+
+  private getRemainingSeconds(exam: any, attempt: any) {
+    if (!exam.time_limit_minutes) {
+      return null;
+    }
+
+    const endsAt =
+      attempt.started_at.getTime() + exam.time_limit_minutes * 60 * 1000;
+
+    return Math.max(0, Math.floor((endsAt - Date.now()) / 1000));
+  }
+
+  private getExamMaxPoints(exam: any) {
+    return (exam.exam_question ?? []).reduce(
+      (sum: number, item: any) => sum + (item.question?.points ?? 0),
+      0,
+    );
+  }
+
+  private isObjectiveQuestion(questionType?: string) {
+    return OBJECTIVE_EXAM_QUESTION_TYPES.includes(
+      this.resolveQuestionType(questionType),
+    );
+  }
+
+  private requiresManualReview(questionType?: string) {
+    return this.resolveQuestionType(questionType) === 'essay';
+  }
+
+  private resolveQuestionType(questionType?: string): ExamQuestionType {
+    return (questionType as ExamQuestionType | undefined) ?? 'multiple_choice';
+  }
+
+  private isJsonString(value: string) {
+    try {
+      const parsed = JSON.parse(value);
+      return typeof parsed === 'object' && parsed !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  private parseSpecialOptions(options: any[]) {
+    const fillBlankAnswers: Array<{ answer: string; alternatives?: string[] }> = [];
+    const matchingPairs: Array<{ id: string; leftText: string; rightText: string }> = [];
+
+    for (const option of options) {
+      try {
+        const parsed = JSON.parse(option.option_text);
+
+        if (parsed?.kind === 'fill_blank' && typeof parsed.answer === 'string') {
+          fillBlankAnswers.push({
+            answer: parsed.answer,
+            alternatives: Array.isArray(parsed.alternatives)
+              ? parsed.alternatives
+              : [],
+          });
+          continue;
+        }
+
+        if (
+          parsed?.kind === 'matching' &&
+          typeof parsed.id === 'string' &&
+          typeof parsed.leftText === 'string' &&
+          typeof parsed.rightText === 'string'
+        ) {
+          matchingPairs.push({
+            id: parsed.id,
+            leftText: parsed.leftText,
+            rightText: parsed.rightText,
+          });
+        }
+      } catch {
+        // Ignore objective options
+      }
+    }
+
+    return {
+      fillBlankAnswers,
+      matchingPairs,
+    };
+  }
+
+  private extractFillBlankExpectedAnswers(rawValue: any): string[] {
+    if (!Array.isArray(rawValue)) {
+      return [];
+    }
+
+    return rawValue.flatMap((item) => {
+      const primary = typeof item?.answer === 'string' ? [item.answer] : [];
+      const alternatives = Array.isArray(item?.alternatives)
+        ? item.alternatives.filter(
+            (alternative: unknown) => typeof alternative === 'string',
+          )
+        : [];
+
+      return [...primary, ...alternatives]
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+    });
+  }
+
+  private isFillBlankCorrect(answerText: string, expectedAnswers: string[]) {
+    const normalizedAnswer = answerText.trim().toLowerCase();
+    return expectedAnswers.some(
+      (expected) => expected.trim().toLowerCase() === normalizedAnswer,
+    );
+  }
+
+  private extractMatchingPairs(rawValue: any) {
+    if (!Array.isArray(rawValue)) {
+      return [] as Array<{ id: string; leftText: string; rightText: string }>;
+    }
+
+    return rawValue
+      .map((pair) => ({
+        id: String(pair?.id ?? '').trim(),
+        leftText: String(pair?.leftText ?? '').trim(),
+        rightText: String(pair?.rightText ?? '').trim(),
+      }))
+      .filter(
+        (pair) =>
+          pair.id.length > 0 &&
+          pair.leftText.length > 0 &&
+          pair.rightText.length > 0,
+      );
+  }
+
+  private isMatchingCorrect(
+    submittedPairs: Array<{ leftId: string; rightId: string }>,
+    expectedPairs: Array<{ id: string; leftText: string; rightText: string }>,
+  ) {
+    if (submittedPairs.length !== expectedPairs.length) {
+      return false;
+    }
+
+    const expectedMap = new Map(expectedPairs.map((pair) => [pair.id, pair.id]));
+    const submittedMap = new Map(
+      submittedPairs.map((pair) => [pair.leftId, pair.rightId]),
+    );
+
+    if (submittedMap.size !== expectedMap.size) {
+      return false;
+    }
+
+    for (const [leftId, expectedRightId] of expectedMap.entries()) {
+      if (submittedMap.get(leftId) !== expectedRightId) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  private extractMatchingPairsFromAnswerText(answerText: string | null) {
+    if (!answerText) {
+      return [] as Array<{ leftId: string; rightId: string }>;
+    }
+
+    try {
+      const parsed = JSON.parse(answerText);
+      if (!Array.isArray(parsed?.matchingPairs)) {
+        return [];
+      }
+
+      return parsed.matchingPairs
+        .map((pair: any) => ({
+          leftId: String(pair?.leftId ?? '').trim(),
+          rightId: String(pair?.rightId ?? '').trim(),
+        }))
+        .filter((pair: any) => pair.leftId.length > 0 && pair.rightId.length > 0);
+    } catch {
+      return [];
+    }
+  }
+
+  private async findExamOrThrow(examId: number) {
+    const exam = await this.prisma.exam.findUnique({
+      where: { id: examId },
+      include: {
+        exam_question: {
+          orderBy: { order: 'asc' },
+          include: {
+            question: {
+              include: {
+                exam_option: {
+                  orderBy: { position: 'asc' },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    if (!exam) {
+      throw new NotFoundException('Exam not found');
+    }
+
+    return exam;
+  }
+
+  private async findRelevantAttempt(examId: number, studentId: number) {
+    const activeAttempt = await this.findActiveAttempt(examId, studentId);
+    if (activeAttempt) {
+      return activeAttempt;
+    }
+
+    return this.prisma.exam_attempt.findFirst({
+      where: {
+        exam_id: examId,
+        student_id: studentId,
+      },
+      orderBy: { created_at: 'desc' },
+      include: {
+        exam_answer: true,
+      },
+    });
+  }
+
+  private findActiveAttempt(examId: number, studentId: number) {
+    return this.prisma.exam_attempt.findFirst({
+      where: {
+        exam_id: examId,
+        student_id: studentId,
+        status: 'in_progress',
+      },
+      orderBy: { created_at: 'desc' },
+      include: {
+        exam_answer: true,
+      },
+    });
+  }
+
+  private async findAttemptOrThrow(
+    examId: number,
+    attemptId: number,
+    studentId: number,
+  ) {
+    const attempt = await this.prisma.exam_attempt.findFirst({
+      where: {
+        id: attemptId,
+        exam_id: examId,
+        student_id: studentId,
+      },
+      include: {
+        exam_answer: true,
+      },
+    });
+
+    if (!attempt) {
+      throw new NotFoundException('Attempt not found');
+    }
+
+    return attempt;
+  }
+
+  private countAttempts(examId: number, studentId: number) {
+    return this.prisma.exam_attempt.count({
+      where: {
+        exam_id: examId,
+        student_id: studentId,
+        status: {
+          not: 'voided',
+        },
+      },
+    });
+  }
+
+  private async findMatchingEnrollment(exam: any, studentId: number) {
+    if (exam.course_class_group_id) {
+      return this.prisma.course_enrollment.findFirst({
+        where: {
+          person_id: studentId,
+          course_class_group_id: exam.course_class_group_id,
+        },
+        orderBy: { updated_at: 'desc' },
+        select: { id: true },
+      });
+    }
+
+    if (exam.course_id) {
+      return this.prisma.course_enrollment.findFirst({
+        where: {
+          person_id: studentId,
+          course_id: exam.course_id,
+        },
+        orderBy: { updated_at: 'desc' },
+        select: { id: true },
+      });
+    }
+
+    return null;
+  }
+
+  private async resolveStudentId(userId: number, explicitStudentId?: number) {
+    if (explicitStudentId) {
+      const person = await this.prisma.person.findUnique({
+        where: { id: explicitStudentId },
+        select: { id: true },
+      });
+
+      if (!person) {
+        throw new NotFoundException('Student not found');
+      }
+
+      return person.id;
+    }
+
+    const user = await this.prisma.user.findUnique({
+      where: { id: userId },
+      select: {
+        id: true,
+        name: true,
+        user_identifier: {
+          where: {
+            type: 'email',
+            enabled: true,
+          },
+          select: {
+            value: true,
+          },
+          take: 1,
+        },
+      },
+    });
+
+    if (!user) {
+      throw new NotFoundException('Authenticated user not found');
+    }
+
+    const userEmail = user.user_identifier?.[0]?.value?.trim().toLowerCase();
+
+    if (userEmail) {
+      const matchingPersons = await this.prisma.person.findMany({
+        where: {
+          contact: {
+            some: {
+              value: { equals: userEmail, mode: 'insensitive' },
+              contact_type: {
+                code: 'email',
+              },
+            },
+          },
+        },
+        select: { id: true },
+        take: 2,
+      });
+
+      if (matchingPersons.length === 1) {
+        return matchingPersons[0].id;
+      }
+    }
+
+    const sameIdPerson = await this.prisma.person.findUnique({
+      where: { id: userId },
+      select: { id: true },
+    });
+
+    if (sameIdPerson) {
+      return sameIdPerson.id;
+    }
+
+    const emailType = await this.prisma.contact_type.findFirst({
+      where: { code: 'email' },
+      select: { id: true },
+    });
+
+    const createdPerson = await this.prisma.person.create({
+      data: {
+        name: user.name,
+        type: 'individual',
+        status: 'active',
+        ...(userEmail && emailType
+          ? {
+              contact: {
+                create: {
+                  contact_type_id: emailType.id,
+                  value: userEmail,
+                  is_primary: true,
+                },
+              },
+            }
+          : {}),
+      },
+      select: { id: true },
+    });
+
+    return createdPerson.id;
+  }
+
+  private toPercent(value: number, max: number) {
+    if (!max) return 0;
+    return Math.round((value / max) * 100);
+  }
+
+  private scoreToTen(score: number) {
+    if (!score) return 0;
+    return score > 10 ? Number((score / 10).toFixed(1)) : Number(score.toFixed(1));
+  }
+}