herrmartins/course-plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
course-plat/EXAM_FLOW.md
T
Rafael Dias Martins 8fcb5aac66 Initial commit
2026-08-31 14:10:20 -03:00

19 KiB
Raw Permalink Blame History

Fluxo de Provas - Course Platform

Este documento explica como funciona o fluxo completo de provas no sistema, desde a criação até a realização e repetição.

Visão Geral

O sistema de provas funciona em 4 etapas principais:

  1. Criação de Templates - Professor/Admin cria modelos de prova reutilizáveis
  2. Atribuição de Prova - Professor/Admin atribui um template a uma turma
  3. Realização pelo Aluno - Aluno faz a prova dentro do período designado
  4. Correção e Resultados - Professor corrige e aluno vê os resultados

1. Criação de Templates de Prova

Quem pode criar: Professor ou Admin

Local: /admin/dashboard/exam-templates ou /dashboard/teacher/exam-templates

O que é um Template:

  • Um modelo de prova reutilizável com questões
  • Pode ser usado em múltiplas turmas
  • Contém:
    • Título da prova
    • Descrição
    • Instruções
    • Lista de questões (múltipla escolha ou texto)
    • Pontuação por questão
    • Tempo limite (opcional)

Campos do Template:

{
  title: "Prova de Inglês - Unidade 1",
  description: "Avaliação sobre verbos e vocabulário",
  instructions: "Leia atentamente cada questão antes de responder",
  questions: [
    {
      questionText: "Qual é o passado de 'go'?",
      questionType: "multiple_choice",
      options: [
        { optionText: "goed", isCorrect: false },
        { optionText: "went", isCorrect: true },
        { optionText: "gone", isCorrect: false }
      ],
      points: 10,
      order: 1
    }
  ],
  timeLimit: 30, // em minutos
  totalPoints: 100
}

2. Atribuição de Prova

Quem pode atribuir: Professor ou Admin

Local: /admin/dashboard/assignments ou /dashboard/teacher/assignments

O que é uma Atribuição (Assignment):

  • Vincula um template de prova a uma turma específica
  • Define quando e como a prova pode ser realizada
  • Configura regras de tentativas e repetição

Campos da Atribuição:

Campo Descrição Exemplo
classId Turma que receberá a prova ID da turma
examTemplateId Template de prova a ser usado ID do template
title Título da prova (pode ser diferente do template) "Prova 1 - Turma A"
description Descrição adicional "Avaliação mensal"
instructions Instruções específicas "Sem consulta"
startDate Data/hora de início da disponibilidade 2025-02-01T08:00
endDate Data/hora de fim da disponibilidade 2025-02-01T18:00
timeLimit Tempo limite para fazer a prova (minutos) 30
allowRetakes Permite refazer a prova true/false
maxAttempts Número máximo de tentativas 3
showResultsAfterGrading Mostra resultados após correção true/false
status Status da prova "active", "draft", "archived"
useCustomQuestions Usa questões customizadas (não do template) true/false
customQuestions Lista de questões customizadas [...]

Configurações de Tentativas e Repetição

allowRetakes (Permitir Refazer):

  • true: Aluno pode fazer a prova mais de uma vez
  • false: Aluno só pode fazer uma vez

maxAttempts (Máximo de Tentativas):

  • Define quantas vezes o aluno pode tentar
  • Exemplo: 3 = aluno pode tentar até 3 vezes
  • Se allowRetakes for false, deve ser 1

Exemplo de Configuração:

// Prova com 3 tentativas permitidas
{
  allowRetakes: true,
  maxAttempts: 3,
  timeLimit: 30,
  startDate: "2025-02-01T08:00:00",
  endDate: "2025-02-01T18:00:00"
}

Fluxo com Repetição:

  1. Aluno faz a 1ª tentativa → Envia → Resultado: 60/100
  2. Aluno clica em "Fazer Prova" novamente
  3. Sistema verifica: tentativas < maxAttempts? → Sim
  4. Sistema cria 2ª tentativa → Aluno faz → Envia → Resultado: 80/100
  5. Aluno clica em "Fazer Prova" novamente
  6. Sistema verifica: tentativas < maxAttempts? → Sim
  7. Sistema cria 3ª tentativa → Aluno faz → Envia → Resultado: 90/100
  8. Aluno clica em "Fazer Prova" novamente
  9. Sistema verifica: tentativas < maxAttempts? → Não (3 = 3)
  10. Sistema bloqueia: "Maximum attempts (3) reached"

3. Visualização pelo Aluno

Local: /dashboard/student/class/[classId]

Status da Prova:

Status Descrição Cor
upcoming Prova ainda não começou Azul
available Prova está disponível para fazer Verde
expired Prova já encerrou Vermelho

Status da Tentativa:

Status Descrição
not_started Aluno ainda não iniciou nenhuma tentativa
in_progress Aluno está fazendo a prova agora
completed Aluno completou a prova

O que o aluno vê:

┌─────────────────────────────────────────┐
│ Prova de Inglês - Unidade 1        │
│ [Disponível]                          │
│                                         │
│ Início: 01/02/2025 08:00           │
│ Fim: 01/02/2025 18:00             │
│ Tempo: 30 min                          │
│ Questões: 10                          │
│ Pontos: 100                           │
│                                         │
│ Melhor nota: 90/100 (90%)            │
│                                         │
│ [Fazer Prova]  [Ver Resultados]       │
└─────────────────────────────────────────┘

4. Início da Prova

Ação: Aluno clica em "Fazer Prova"

Verificações do Sistema:

  1. Verifica Período de Disponibilidade:

    const now = new Date();
if (now < assignment.startDate) {
  return "Prova ainda não começou";
}
if (now > assignment.endDate) {
  return "Prova já encerrou";
}

  2. Verifica Tentativas em Andamento:

    const inProgressAttempt = attempts.find(a => a.status === "in_progress");
if (inProgressAttempt) {
  return "Continuar prova em andamento";
}

  3. Verifica Máximo de Tentativas:

    const existingAttempts = await ExamAttempt.countDocuments({
  assignmentId: assignmentId,
  studentId: studentId,
});

if (existingAttempts >= assignment.maxAttempts) {
  return `Maximum attempts (${assignment.maxAttempts}) reached`;
}

Se todas as verificações passarem:

  • Sistema cria uma nova ExamAttempt
  • Status: "in_progress"
  • attemptNumber: existingAttempts + 1
  • startedAt: Data/hora atual
  • Redireciona para a página de realização da prova

5. Realização da Prova

Local: /dashboard/student/assignments/[assignmentId]/take

O que acontece:

  1. Carregamento das Questões:

    • Se useCustomQuestions for true: usa assignment.customQuestions
    • Se useCustomQuestions for false: usa template.questions

  2. Contador de Tempo:

    • Se timeLimit estiver definido, inicia contador
    • Atualiza a cada segundo
    • Se tempo acabar, envia automaticamente

  3. Respostas do Aluno:

    • Sistema salva as respostas temporariamente
    • Aluno pode mudar as respostas antes de enviar
    • Não há salvamento automático (deve ser implementado)

Estrutura das Respostas:

{
  questionId1: { type: "mc", value: "optionId1" },
  questionId2: { type: "text", value: "Resposta do aluno" },
  questionId3: { type: "mc", value: null } // não respondida
}

6. Envio da Prova

Ação: Aluno clica em "Enviar" ou tempo acaba

Validações:

  1. Confirmação do aluno (se não for auto-submit)
  2. Validação das respostas

Processo de Envio:

// 1. Usa as mesmas questões que foram exibidas
const examQuestions = assignment.useCustomQuestions
  ? assignment.customQuestions
  : template.questions;

// 2. Mapeia as respostas do aluno
const answers = examQuestions.map((q) => {
  const answer = currentAnswers[q._id] || { type: "mc", value: null };
  return {
    questionId: q._id,
    selectedOptionId: answer.type === "mc" ? answer.value : null,
    textAnswer: answer.type === "text" ? answer.value : null,
  };
});

// 3. Envia para o servidor
const result = await submitExamAttempt(attempt._id, answers);

Após Envio:

  • Status da tentativa: "submitted"
  • Redireciona para /dashboard/student/assignments/[assignmentId]/results

7. Visualização de Resultados

Local: /dashboard/student/assignments/[assignmentId]/results

O que o aluno vê:

  1. Se showResultsAfterGrading for true:

    • Mostra todas as tentativas
    • Mostra a nota de cada tentativa
    • Mostra a melhor nota
    • Mostra as respostas corretas

  2. Se showResultsAfterGrading for false:

    • Mostra mensagem: "Sua prova foi enviada e aguarda correção pelo professor"
    • Botão para refazer (se permitido)

Exemplo de Visualização:

┌─────────────────────────────────────────┐
│ Prova de Inglês - Unidade 1        │
│                                         │
│ Suas Tentativas:                       │
│                                         │
│ 1. 60/100 (60%) - 01/02/2025      │
│ 2. 80/100 (80%) - 01/02/2025      │
│ 3. 90/100 (90%) - 01/02/2025      │
│                                         │
│ Melhor nota: 90/100 (90%)            │
│                                         │
│ [Fazer Prova Novamente]                │
└─────────────────────────────────────────┘

8. Correção pelo Professor

Local: /dashboard/teacher/assignments/[assignmentId]/results

O que o professor vê:

  • Lista de todos os alunos da turma
  • Tentativas de cada aluno
  • Respostas de cada tentativa
  • Botão para corrigir manualmente

Processo de Correção:

  1. Professor clica em "Corrigir" em uma tentativa
  2. Sistema abre modal com as questões e respostas
  3. Professor atribui nota manualmente
  4. Sistema salva a nota
  5. Aluno pode ver os resultados

Fluxo Completo com Repetição

Cenário: Prova com 3 tentativas permitidas

┌─────────────────────────────────────────────────────────────────┐
│ 1. CRIAÇÃO DO TEMPLATE                                   │
│    Professor cria "Prova de Inglês - Unidade 1"          │
│    com 10 questões, 100 pontos, 30 minutos               │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. ATRIBUIÇÃO DA PROVA                                   │
│    Professor atribui à "Turma A"                          │
│    - allowRetakes: true                                    │
│    - maxAttempts: 3                                        │
│    - startDate: 01/02/2025 08:00                        │
│    - endDate: 01/02/2025 18:00                          │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. ALUNO VÊ A PROVA                                      │
│    Status: "Disponível"                                   │
│    Botão: "Fazer Prova"                                   │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. 1ª TENTATIVA                                          │
│    Aluno clica em "Fazer Prova"                           │
│    Sistema verifica:                                          │
│      ✓ Dentro do período? SIM                               │
│      ✓ Tentativas < 3? SIM (0 < 3)                        │
│    Sistema cria tentativa #1                                   │
│    Aluno faz a prova (30 min)                               │
│    Aluno envia                                              │
│    Resultado: 60/100 (60%)                                 │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. ALUNO VÊ RESULTADOS                                    │
│    Melhor nota: 60/100 (60%)                             │
│    Botão: "Fazer Prova Novamente"                           │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. 2ª TENTATIVA                                          │
│    Aluno clica em "Fazer Prova Novamente"                   │
│    Sistema verifica:                                          │
│      ✓ Dentro do período? SIM                               │
│      ✓ Tentativas < 3? SIM (1 < 3)                        │
│    Sistema cria tentativa #2                                   │
│    Aluno faz a prova (30 min)                               │
│    Aluno envia                                              │
│    Resultado: 80/100 (80%)                                 │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 7. ALUNO VÊ RESULTADOS                                    │
│    Melhor nota: 80/100 (80%)                             │
│    Botão: "Fazer Prova Novamente"                           │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 8. 3ª TENTATIVA                                          │
│    Aluno clica em "Fazer Prova Novamente"                   │
│    Sistema verifica:                                          │
│      ✓ Dentro do período? SIM                               │
│      ✓ Tentativas < 3? SIM (2 < 3)                        │
│    Sistema cria tentativa #3                                   │
│    Aluno faz a prova (30 min)                               │
│    Aluno envia                                              │
│    Resultado: 90/100 (90%)                                 │
└─────────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────────┐
│ 9. ALUNO TENTA NOVAMENTE                                  │
│    Aluno clica em "Fazer Prova Novamente"                   │
│    Sistema verifica:                                          │
│      ✓ Dentro do período? SIM                               │
│      ✗ Tentativas < 3? NÃO (3 = 3)                        │
│    Sistema bloqueia:                                         │
│      "Maximum attempts (3) reached"                          │
│    Botão "Fazer Prova" desabilitado                          │
└─────────────────────────────────────────────────────────────────┘

Regras Importantes

1. Período de Disponibilidade

  • Aluno só pode fazer a prova entre startDate e endDate
  • Se tentar antes: "Prova ainda não começou"
  • Se tentar depois: "Prova já encerrou"

2. Tentativas em Andamento

  • Se aluno tiver uma tentativa com status "in_progress", não pode criar outra
  • Sistema deve permitir continuar a tentativa existente

3. Máximo de Tentativas

  • Aluno não pode exceder maxAttempts
  • Se allowRetakes for false, maxAttempts deve ser 1

4. Tempo Limite

  • Se timeLimit estiver definido, prova é enviada automaticamente quando acabar
  • Contador é atualizado a cada segundo

5. Resultados

  • Se showResultsAfterGrading for true, aluno vê resultados imediatamente
  • Se for false, aluno vê mensagem aguardando correção

Melhorias Sugeridas

  1. Salvamento Automático:

    • Salvar respostas periodicamente (ex: a cada 30 segundos)
    • Permitir continuar de onde parou em caso de desconexão

  2. Notificações:

    • Avisar aluno quando prova estiver prestes a encerrar
    • Avisar professor quando aluno enviar prova

  3. Histórico de Tentativas:

    • Mostrar data/hora de cada tentativa
    • Mostrar tempo gasto em cada tentativa

  4. Estatísticas:

    • Média da turma
    • Comparação com outros alunos (opcional)

  5. Feedback Imediato:

    • Mostrar quais questões o aluno acertou/errou (opcional)
    • Permitir revisão da prova após correção

Conclusão

O sistema de provas é flexível e permite:

✅ Criação de templates reutilizáveis ✅ Atribuição com configurações personalizadas ✅ Controle de tentativas e repetições ✅ Período de disponibilidade configurável ✅ Tempo limite opcional ✅ Resultados configuráveis (imediatos ou após correção) ✅ Histórico completo de tentativas

Para dúvidas ou sugestões de melhoria, consulte a equipe de desenvolvimento.

Reference in New Issue View Git Blame Copy Permalink