Pular para o conteúdo principal

Feature: Quiz

Introdução ao documento​

Este documento cobre a feature de quiz por slug: carregamento do quiz, resolução do userId, resposta das questões, feedback e conclusão. Evidências: src/app/(protected-routes)/quiz/page.tsx:21-231, src/components/Quiz/QuizBackend.component.tsx:33-335, src/services/quizApi.ts:130-242.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem quiz/page.tsx, QuizBackend, useQuiz ou services/quizApi.ts. Evidências: src/app/(protected-routes)/quiz/page.tsx:21-231, src/components/Quiz/QuizBackend.component.tsx:33-335, src/services/quizApi.ts:130-242.

Referencial teórico​

O fluxo foi derivado da página client-side do quiz, do componente QuizBackend e do client HTTP da Quiz API. Evidências: src/app/(protected-routes)/quiz/page.tsx:35-105, src/components/Quiz/QuizBackend.component.tsx:50-335, src/services/quizApi.ts:130-242.

Visão geral​

  • A página resolve slug a partir de searchParams, do curso da turma ou do classId. Evidências: src/app/(protected-routes)/quiz/page.tsx:43-76.
  • O userId pode vir explicitamente na query string ou da sessão do usuário. Evidências: src/app/(protected-routes)/quiz/page.tsx:78-82.
  • Antes de iniciar, a UI busca os metadados do quiz e mostra uma tela introdutória com título, descrição e botão Começar. Evidências: src/app/(protected-routes)/quiz/page.tsx:84-105, src/app/(protected-routes)/quiz/page.tsx:141-203.

Atores​

  • Participante ou facilitador respondendo quiz. Evidências: src/components/Home/HomeAluno.component.tsx:177-185, src/components/Home/HomeFacilitador.component.tsx:142-149.
  • Quiz API externa. Evidências: src/services/quizApi.ts:130-242.

Pré-condições​

  • Sessão carregada ou userId explícito na query string. Evidências: src/app/(protected-routes)/quiz/page.tsx:23-35, src/app/(protected-routes)/quiz/page.tsx:78-82.
  • slug válido para o curso/turma. Evidências: src/app/(protected-routes)/quiz/page.tsx:70-76, src/services/quizApi.ts:130-138.
  • QUIZ_API_URL configurada no ambiente exposto por /api/envs. Evidências: src/app/api/envs/route.ts:23-25.

Fluxo principal​

  1. A página resolve slug e userId. Evidências: src/app/(protected-routes)/quiz/page.tsx:70-82.
  2. A UI busca getQuizBySlug(slug) e carrega os metadados do quiz. Evidências: src/app/(protected-routes)/quiz/page.tsx:84-105, src/services/quizApi.ts:130-138.
  3. Ao clicar em Começar, a página renderiza QuizBackend. Evidências: src/app/(protected-routes)/quiz/page.tsx:193-208.
  4. QuizBackend usa useQuiz e a Quiz API para percorrer questões, salvar respostas e obter feedback. Evidências: src/components/Quiz/QuizBackend.component.tsx:50-60, src/services/quizApi.ts:143-217.

Fluxos alternativos​

  • Se a busca de quiz falhar, a página mostra um bloco de erro amarelo. Evidências: src/app/(protected-routes)/quiz/page.tsx:128-139.
  • Se o usuário já tiver respostas salvas, QuizBackend entra direto na tela de sucesso após buscar respostas e questões. Evidências: src/components/Quiz/QuizBackend.component.tsx:79-170.
  • Se o feedback final não puder ser carregado pelo attemptId, o componente tenta recompor o resultado a partir das respostas já salvas. Evidências: src/components/Quiz/QuizBackend.component.tsx:306-325.

Regras de negócio​

  • A página prioriza slug explícito da query, depois classesData[slug], depois classId atual. Evidências: src/app/(protected-routes)/quiz/page.tsx:43-76.
  • O quiz considera concluído quando já existem respostas para slug + userId, mesmo antes da navegação manual pela UI. Evidências: src/components/Quiz/QuizBackend.component.tsx:79-170.
  • Ao salvar uma resposta, a API exige userId e questionId como query string. Evidências: src/services/quizApi.ts:161-177.
  • O carregamento do feedback final usa /answers/attempt/{attemptId}/final-feedback; quando isso falha, o frontend monta feedback básico com correctAnswers, incorrectAnswers e score. Evidências: src/services/quizApi.ts:205-217, src/components/Quiz/QuizBackend.component.tsx:149-169, src/components/Quiz/QuizBackend.component.tsx:239-255.

Estados possíveis​

  • loading: sessão, classes ou quiz ainda carregando. Evidências: src/app/(protected-routes)/quiz/page.tsx:107-125.
  • erro: falha em carregar o quiz. Evidências: src/app/(protected-routes)/quiz/page.tsx:128-139.
  • pre_inicio: metadados carregados e quizStarted === false. Evidências: src/app/(protected-routes)/quiz/page.tsx:141-203.
  • em_execucao: QuizBackend renderizado. Evidências: src/app/(protected-routes)/quiz/page.tsx:205-210.
  • sucesso: QuizBackend muda currentStep para success. Evidências: src/components/Quiz/QuizBackend.component.tsx:165-169, src/components/Quiz/QuizBackend.component.tsx:235-258.

Endpoints envolvidos​

  • Ver OpenAPI: a feature depende da Quiz API externa consumida por quizApi.ts: /quizzes/slug/{slug}, /questions/slug/{slug}/user/{userId}/next, /answers, /answers/slug/{slug}/user/{userId}, /answers/attempt/{attemptId}/final-feedback, /questions.
  • Localmente, o ambiente expõe QUIZ_API_URL em GET /api/envs. Evidências: src/app/api/envs/route.ts:23-25.

Dados impactados​

  • Ver model.md: o documento local cobre parcialmente User e Class, mas o modelo completo de Quiz, Question, Answer e Attempt vive fora deste repositório.
  • A feature impacta também estado client-side de progresso e respostas. Evidências: src/components/Quiz/QuizBackend.component.tsx:37-46.

Pendências​

  • O schema completo da Quiz API não é versionado neste repositório.
  • O hook useQuiz centraliza parte da lógica de navegação de questões e não foi formalizado em documento próprio.