Interface IOnboardingQuizService

Namespace

Builvero.Application.Interfaces.Services

Assembly

Builvero.Application.dll

Defines the contract for onboarding quiz operations including starting quizzes, submitting answers, and retrieving results.

public interface IOnboardingQuizService

Remarks

This interface provides methods for managing the onboarding quiz for TeamCandidate users. The quiz consists of 15 randomly selected questions from a question bank. Users can have multiple quiz attempts, but only one active (unsubmitted) attempt at a time. Passing the quiz (score >= 14/15) automatically promotes the user to TeamMember role.

Methods

GetQuizResultAsync(Guid, Guid, CancellationToken)

Retrieves the result of a submitted quiz attempt.

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.

Exceptions

UnauthorizedAccessException

Thrown when the attempt belongs to a different user.

StartQuizAsync(Guid, CancellationToken)

Starts a new quiz attempt for a TeamCandidate user.

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.

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.

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.

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.