herrmartins/course-plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Rafael Dias Martins
2026-08-31 14:10:20 -03:00
commit 8fcb5aac66
454 changed files with 60207 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
EXAM_FLOW.md
+484
View File
@@ -0,0 +1,484 @@
# 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.