Class OnboardingQuizService

Namespace

Builvero.Application.Services

Assembly

Builvero.Application.dll

Service for managing the onboarding quiz for TeamCandidate users, including quiz attempts, scoring, and role promotion.

public class OnboardingQuizService : IOnboardingQuizService

Inheritance

object

OnboardingQuizService

Implements

IOnboardingQuizService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This service handles the complete onboarding quiz lifecycle:

• Starting new quiz attempts (15 random questions from question bank)
• Submitting quiz answers and calculating scores
• Retrieving quiz results and scores
• Automatic role promotion (TeamCandidate to TeamMember) upon passing (score >= 14/15)

Only TeamCandidate users can start and submit quizzes. Users can have multiple attempts, but only one active (unsubmitted) attempt at a time. The question bank is loaded from a JSON file at service initialization.

Constructors

OnboardingQuizService(IOnboardingQuizAttemptRepository, IUserRepository, IAdminService, ILogger<OnboardingQuizService>)

Initializes a new instance of the OnboardingQuizService class.

public OnboardingQuizService(IOnboardingQuizAttemptRepository attemptRepository, IUserRepository userRepository, IAdminService adminService, ILogger<OnboardingQuizService> logger)

Parameters

attemptRepository IOnboardingQuizAttemptRepository

Repository for quiz attempt data access.

userRepository IUserRepository

Repository for user data access.

adminService IAdminService

Service for role promotion operations.

logger ILogger<OnboardingQuizService>

Logger for recording operations and errors.

Remarks

The question bank is loaded from a JSON file during initialization. The service searches multiple possible paths to find the quiz-questions.json file.

Methods

GetQuizResultAsync(Guid, Guid, CancellationToken)

Retrieves the result of a submitted quiz attempt.

public Task<QuizResultDto?> GetQuizResultAsync(Guid userId, Guid attemptId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user requesting the result.

attemptId Guid

The unique identifier of the quiz attempt.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<QuizResultDto>

The quiz result DTO if the attempt exists and is submitted; otherwise, null.

Remarks

Returns null if the attempt is not found or has not been submitted yet. Users can only access their own quiz results. The result includes score, pass/fail status, and whether the role was promoted.

Exceptions

UnauthorizedAccessException

Thrown when the attempt belongs to a different user.

StartQuizAsync(Guid, CancellationToken)

Starts a new quiz attempt for a TeamCandidate user.

public Task<QuizStartResponse> StartQuizAsync(Guid userId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user starting the quiz.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<QuizStartResponse>

The quiz start response containing the attempt ID and 15 randomly selected questions.

Remarks

This method:

1. Validates that the user exists and has TeamCandidate role
2. Invalidates any existing unsubmitted attempts for the user
3. Randomly selects 15 questions from the question bank
4. Creates a new quiz attempt record
5. Returns the questions without correct answers

Users can have multiple quiz attempts, but only one active (unsubmitted) attempt at a time.

Exceptions

Exception

Thrown when the user is not found.

UnauthorizedAccessException

Thrown when the user is not a TeamCandidate.

SubmitQuizAsync(Guid, Guid, List<QuizAnswerDto>, CancellationToken)

Submits quiz answers and calculates the score, promoting the user to TeamMember if they pass.

public Task<QuizSubmitResponse> SubmitQuizAsync(Guid userId, Guid attemptId, List<QuizAnswerDto> answers, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user submitting the quiz.

attemptId Guid

The unique identifier of the quiz attempt to submit.

answers List<QuizAnswerDto>

The list of answers for the quiz questions.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<QuizSubmitResponse>

The quiz submit response containing pass/fail status, score, and role promotion status.

Remarks

This method:

1. Validates the attempt exists, belongs to the user, and is not already submitted
2. Loads the question set from the attempt
3. Calculates the score by comparing answers to correct answers
4. Determines pass/fail (passing requires score >= 14 out of 15)
5. Promotes user to TeamMember role if they pass
6. Saves the attempt with score, pass status, and answers

If role promotion fails, the error is logged but the attempt is still saved with the score.

Exceptions

Exception

Thrown when the quiz attempt is not found.

UnauthorizedAccessException

Thrown when the attempt belongs to a different user.

InvalidOperationException

Thrown when the attempt has already been submitted.