485 lines
19 KiB
Markdown
485 lines
19 KiB
Markdown
# 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:**
|
|
```javascript
|
|
{
|
|
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:**
|
|
|
|
```javascript
|
|
// 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:**
|
|
```javascript
|
|
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:**
|
|
```javascript
|
|
const inProgressAttempt = attempts.find(a => a.status === "in_progress");
|
|
if (inProgressAttempt) {
|
|
return "Continuar prova em andamento";
|
|
}
|
|
```
|
|
|
|
3. **Verifica Máximo de Tentativas:**
|
|
```javascript
|
|
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:**
|
|
```javascript
|
|
{
|
|
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:**
|
|
```javascript
|
|
// 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.
|