Features de provas

[rafael-pf]

Pull Request - Teaching Assistant

📝 Descrição

O que foi feito:

Implementação completa do sistema de gerenciamento de provas, incluindo todas as funcionalidades necessárias para o ciclo completo de criação, aplicação e correção de provas:

1. Criação e Manutenção de Questões

• CRUD completo de questões (abertas e fechadas)
• Validação de questões abertas (requerem resposta esperada)
• Validação de questões fechadas (requerem opções com marcação de corretas)
• Busca e filtragem de questões por tópico
• Endpoints: GET /api/questions, POST /api/questions, PUT /api/questions/:id, DELETE /api/questions/:id

2. Criação e Manutenção de Provas

• Criação de provas vinculadas a turmas
• Configuração de quantidade de questões abertas e fechadas
• Seleção de questões do banco de questões
• Validação de provas (pelo menos uma questão, questões existentes, quantidades válidas)
• Atualização e exclusão de provas
• Controle de status da prova (isValid para abrir/fechar)
• Endpoints: GET /api/exams, POST /api/exams, PUT /api/exams/:examId, DELETE /api/exams/:examId

3. Geração de Provas para Estudantes

• Geração automática de provas individuais para cada estudante matriculado
• Randomização de questões (cada estudante recebe um conjunto diferente)
• Seleção aleatória dentro do pool de questões disponíveis
• Preservação de provas já geradas (não regenera para estudantes que já possuem)
• Endpoint: POST /api/exams/:examId/generate?classId=:classId

4. Geração de PDFs

• Geração de PDFs de provas em lote (ZIP)
• Geração de gabaritos correspondentes
• Múltiplas versões da mesma prova (randomização de questões e opções)
• Formatação profissional com cabeçalho institucional
• Numeração de versões nas provas
• Suporte a questões abertas e fechadas
• Endpoint: GET /api/exams/:id/zip?classId=:classId&quantity=:quantity&date=:date

5. Submissão de Respostas de Provas

• Submissão de respostas pelos estudantes
• Validação de autenticação e autorização (apenas estudantes podem submeter)
• Validação de provas fechadas/expiradas
• Validação de respostas incompletas (todas as questões devem ser respondidas)
• Prevenção de submissões duplicadas
• Normalização de CPF (remove pontos e traços)
• Persistência de respostas em responses.json
• Endpoints: POST /api/exams/:examId/responses, GET /api/exams/:examId/responses

6. Correção de Provas

• Correção Automática de Questões Fechadas: Cálculo automático de notas baseado em respostas corretas
• Correção por IA de Questões Abertas: Integração com serviços de IA (Gemini) para correção de questões discursivas
• Sistema de fila para correção em lote (QStash)
• Atualização de notas por questão e nota final
• Visualização de correções e notas
• Endpoints: POST /api/correct/:examId, POST /api/trigger-ai-correction, POST /api/question-ai-correction

Por que foi feito:

Este conjunto de funcionalidades forma o núcleo do sistema de avaliação, permitindo que professores criem e gerenciem provas de forma eficiente, que estudantes respondam provas de forma segura, e que o sistema realize correções automáticas e assistidas por IA. A implementação garante integridade dos dados, segurança através de autenticação/autorização, e validações que previnem erros comuns.

📌 Observações

Impacto:

• 🔴 Alto - Mudanças críticas ou estruturais

Riscos identificados:

• A geração de PDFs utiliza biblioteca pdfkit e pode ter limitações com textos muito longos
• A correção por IA depende de serviços externos (Gemini) e pode estar sujeita a rate limits

Decisões técnicas:

• Uso de examsManager e questionsManager para gerenciamento centralizado de dados
• Persistência em arquivos JSON (exams.json, questions.json, responses.json, exam-generations.json)
• Geração de provas individuais armazena apenas referências às questões, não duplica dados
• Sistema de versões de provas permite rastreamento de diferentes gerações de PDFs

📦 Área afetada

Frontend (Client - React):

• 🖥️ Componentes React
• 🔌 Services/API
• 📝 Types/Interfaces TypeScript
• 🎨 Estilos e UI

Backend (Server - Express/Node.js):

• 🔌 API Routes/Endpoints
• 📊 Models e lógica de negócio
• 💾 Persistência de dados

Funcionalidades:

• 🎓 Gerenciamento de Estudantes
• 📋 Gerenciamento de Turmas
• 📝 Gerenciamento de Matrículas
• 📈 Gerenciamento de Avaliações
• 📄 Importação de dados
• Provas
• Flashcards

Infraestrutura:

• 🔧 Configurações (tsconfig, jest.config, cucumber.js)
• 📦 Dependências (package.json)
• 🚀 Scripts de build/deploy
• 📝 Documentação (README, guias)

🔧 Tipo de mudança

• 🐛 Correção de bug (fix)
• ✨ Nova funcionalidade (feature)
• ♻️ Refatoração de código
• 📚 Atualização de documentação
• ✅ Adição/atualização de testes
• 🎨 Melhorias de UI/UX
• 🔒 Correção de segurança
• ⚡ Melhoria de performance

🧪 Testes

Testes automatizados

Por nível de teste:

• 🔬 Testes Unitários (Jest) - Classes e funções isoladas
  • Dependências: versões antigas, stubs e drivers
• 🔗 Testes de Integração - Interação entre componentes/serviços
  • Dependências: novas versões evoluídas por outros desenvolvedores
• 🎯 Testes End-to-End (Cucumber) - Fluxos completos da aplicação
  • Dependências: todas as dependências envolvidas
• 🌐 Testes de Sistema - Ambiente completo de produção
  • Dependências: ambiente de produção com dependências externas reais

Por área testada:

• 🖥️ Testes de GUI (interface do usuário)
• 📊 Testes de Classes/Models (lógica de negócio)
• 🔌 Testes de Services/API (comunicação e endpoints)

Cobertura:

• Cobertura de testes mantida/aumentada
• Casos de erro e edge cases cobertos

Testes implementados:

🔬 Testes Unitários (Jest)

1. Modelo de Questões (server/tests/unit/questions.model.test.ts):

   • ✅ Adição de questões abertas com trim de texto e IDs sequenciais
   • ✅ Validação de questões fechadas (deve ter pelo menos uma opção correta)
   • ✅ Conversão de questão fechada para aberta (limpa opções)

2. Classe Exams (server/tests/unit/exam.class.test.ts):

   • ✅ Gerenciamento de estado interno da classe
   • ✅ Inicialização, leitura, escrita e mutação de dados
   • ✅ Serialização de dados (toJSON)
   • ✅ Busca de provas por ID e classId
   • ✅ Gerenciamento de provas de estudantes

3. Funções Auxiliares (server/tests/unit/getOpenQuestionsForExam.test.ts):

   • ✅ Retorno de apenas questões abertas de um exame
   • ✅ Retorno de array vazio quando exame não existe

4. Geração de Provas (server/tests/unit/dataService.generation.test.ts):

   • ✅ Lógica de geração de provas individuais

5. Atualização de Notas (server/tests/unit/updateResponseAnswerScore.test.ts):

   • ✅ Atualização de notas de respostas

6. Serviços de IA (server/tests/unit/AIServiceFactory.test.ts, server/tests/unit/aiCorrectionHelpers.test.ts):

   • ✅ Factory de serviços de IA
   • ✅ Helpers de correção por IA

7. Algoritmos (server/tests/unit/algorithms.test.ts):

   • ✅ Algoritmos auxiliares do sistema

🔗 Testes de Integração

1. Submissão de Respostas (server/tests/integration/responses.integration.test.ts):

   • ✅ Submissão válida de respostas
   • ✅ Prevenção de submissões duplicadas (409 Conflict)
   • ✅ Validação de respostas incompletas (400 Bad Request)
   • ✅ Validação de provas fechadas/expiradas (410 Gone)

2. Provas (server/tests/integration/provas.test.ts):

   • ✅ Criação de provas via API
   • ✅ Validação de dados de entrada
   • ✅ Geração de provas para estudantes
   • ✅ Integração com Cucumber (provas-individuais-backend.feature)

3. Questões (server/tests/integration/questions.integration.test.ts):

   • ✅ Criação de questões abertas e fechadas via API
   • ✅ Validação de dados de entrada
   • ✅ Atualização e exclusão de questões

4. Correção Automática (server/tests/integration/autocorrection-closed.test.ts):

   • ✅ Correção de questões fechadas

5. Correção por IA (server/tests/integration/question-ai-correction.test.ts, server/tests/integration/trigger-ai-correction.test.ts):

   • ✅ Correção de questões abertas por IA
   • ✅ Trigger de correção em lote

6. Geração de PDFs (server/tests/integration/pdfContent.test.ts):

   • ✅ Validação de conteúdo de PDFs gerados

7. Versões de Provas (server/tests/integration/examVersion.test.ts):

   • ✅ Gerenciamento de versões de provas

8. Fluxo Completo de Provas (server/tests/integration/examFlow.test.ts):

   • ✅ Fluxo end-to-end de criação e geração de provas

🔌 Testes de Serviço (Rotas)

1. Rotas de Respostas (server/tests/services/responses.routes.test.ts):

   • ✅ Validação de autenticação (401 Unauthorized)
   • ✅ Validação de autorização por role (403 Forbidden para professores)
   • ✅ Validação de prova não encontrada (404 Not Found)
   • ✅ Validação de prova expirada (410 Gone)
   • ✅ Validação de payload inválido (400 Bad Request)
   • ✅ Validação de respostas vazias (400 Bad Request)
   • ✅ Submissão bem-sucedida (201 Created)
   • ✅ Tratamento de submissão duplicada (409 Conflict)

2. Rotas de Questões (server/tests/services/questions.routes.test.ts, server/tests/services/questions.validation.test.ts):

   • ✅ Validação de criação de questões
   • ✅ Validação de atualização de questões

3. Rotas de Provas (server/tests/services/exams.routes.test.ts):

   • ✅ Validação de criação de provas
   • ✅ Validação de geração de provas

4. Geração (server/tests/services/generation.test.ts):

   • ✅ Lógica de geração de provas individuais

🎯 Testes de Aceitação (Cucumber)

Frontend (GUI):

1. Gerenciamento de Provas (client/src/features/provas-individuais-gui.feature):

   • ✅ Registro de provas via interface
   • ✅ Registro de provas sem questões (validação)
   • ✅ Exclusão de provas
   • ✅ Listagem de provas de uma turma
   • ✅ Abertura de popup de criação

2. Gerenciamento de Questões (client/src/features/question-management.feature):

   • ✅ Criação de questões abertas
   • ✅ Criação de questões fechadas
   • ✅ Exclusão de questões

3. Geração de PDFs (client/src/features/pdf-generation.feature):

   • ✅ Geração de PDFs de provas e gabaritos
   • ✅ Validação de parâmetros de geração

4. Correção Automática (client/src/features/autocorrection.feature):

   • ✅ Correção de questões fechadas via interface
   • ✅ Visualização de correções
   • ✅ Tratamento de provas sem respostas
   • ✅ Tratamento de provas não corrigidas

5. Correção por IA (client/src/features/ai-correction.feature):

   • ✅ Iniciação de correção por IA com seleção de modelo
   • ✅ Validação de seleção de modelo
   • ✅ Tratamento de provas sem respostas

Backend (API):

1. Criação de Provas (server/tests/features/create-exam-unit.feature):

   • ✅ Criação de prova com dados válidos
   • ✅ Falha por campo obrigatório ausente
   • ✅ Falha por turma inexistente

2. Registro de Respostas (server/tests/features/examresponseregistration.feature):

   • ✅ Registro bem-sucedido de respostas
   • ✅ Tentativa de submissão incompleta
   • ✅ Tentativa de submissão após prova fechada
   • ✅ Chamada de API para submissão

3. Provas Individuais (server/tests/features/provas-individuais-backend.feature):

   • ✅ Registro de provas
   • ✅ Geração de versões individuais

4. Geração de PDFs (server/tests/features/pdf-generation/success.feature, server/tests/features/pdf-generation/validation.feature):

   • ✅ Geração bem-sucedida de PDFs
   • ✅ Validação de parâmetros

5. Correção Automática (server/tests/features/autocorrection-closed-service.feature):

   • ✅ Correção de questões fechadas via serviço

6. Trigger de Correção por IA (server/tests/features/trigger-ai-correction.feature):

   • ✅ Trigger de correção em lote por IA

Como revisar e testar

Configuração do Ambiente:

1. Estrutura do arquivo .env do servidor (server/.env):

# Configuração do Servidor
API_BASE_URL=http://localhost:3005

# Configuração do Gemini (Google AI) - Obrigatória para correção por IA
GEMINI_API_KEY=sua_chave_api_gemini_aqui

# Configuração do QStash - Opcional (pode usar processamento local)
QSTASH_TOKEN=seu_token_qstash_aqui
QSTASH_BASE_URL=http://localhost:8000  # Para desenvolvimento local com QStash CLI
QSTASH_QUEUE_NAME=questions
QSTASH_WEBHOOK_URL=http://localhost:3005/api/question-ai-correction

Notas sobre as variáveis:

• API_BASE_URL: URL base da API (padrão: http://localhost:3005)
• GEMINI_API_KEY: Obrigatória apenas em produção. Em desenvolvimento, o sistema funciona sem ela (com avisos).
• QSTASH_TOKEN: Opcional. Se não configurado, o sistema usa processamento local.
• QSTASH_BASE_URL: Para desenvolvimento local, configure como http://localhost:8000 quando usar o QStash CLI.
• QSTASH_QUEUE_NAME: Nome da fila no QStash (padrão: questions)
• QSTASH_WEBHOOK_URL: URL do webhook que receberá as correções (padrão: ${API_BASE_URL}/api/question-ai-correction)

Variáveis opcionais com valores padrão:

• PORT: Porta do servidor (padrão: 3005)
• NODE_ENV: Ambiente de execução (padrão: development)
• GEMINI_TIMEOUT: Timeout para requisições ao Gemini em ms (padrão: 120000)
• GEMINI_MAX_RETRIES: Número máximo de tentativas (padrão: 3)

2. Rodando QStash localmente (para desenvolvimento):

# Em um terminal separado, execute o QStash CLI em modo desenvolvimento
npx @upstash/qstash-cli@latest dev

Isso iniciará o QStash localmente na porta 8000 (padrão), permitindo testar a funcionalidade de correção por IA em fila sem depender do serviço cloud da Upstash.

Testes Unitários (Server):

cd server
npm install
npm test                    # Executar testes
npm run test:watch          # Modo watch
npm run test:coverage       # Com cobertura

Testes E2E (Client):

cd client
npm install
npm start                   # Terminal 1: iniciar app
npm run test:cucumber       # Terminal 2: executar testes

Testar manualmente:

1. Criação de Questões:

# Criar questão aberta
curl -X POST http://localhost:3005/api/questions \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Explique o conceito de TDD",
    "topic": "Testes",
    "type": "open",
    "answer": "TDD é Test-Driven Development..."
  }'

# Criar questão fechada
curl -X POST http://localhost:3005/api/questions \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Qual é a melhor prática?",
    "topic": "Boas Práticas",
    "type": "closed",
    "options": [
      {"option": "Opção A", "isCorrect": true},
      {"option": "Opção B", "isCorrect": false}
    ]
  }'

2. Criação de Provas:

curl -X POST http://localhost:3005/api/exams \
  -H "Content-Type: application/json" \
  -d '{
    "nomeProva": "Prova 1",
    "classId": "cls-1",
    "quantidadeAberta": 2,
    "quantidadeFechada": 3,
    "questionIds": [1, 2, 3, 4, 5]
  }'

3. Geração de Provas para Estudantes:

curl -X POST "http://localhost:3005/api/exams/1/generate?classId=cls-1"

4. Geração de PDFs:

curl -X GET "http://localhost:3005/api/exams/1/zip?classId=cls-1&quantity=5&date=2025-01-15" \
  --output provas.zip

5. Submissão de Respostas (Estudante):

curl -X POST http://localhost:3005/api/exams/1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "studentCpf": "123.456.789-00",
    "answers": [
      {"questionId": 1, "answer": "Resposta da questão 1"},
      {"questionId": 2, "answer": "Resposta da questão 2"}
    ]
  }'

6. Visualizar Respostas (Professor):

curl -X GET http://localhost:3005/api/exams/1/responses \

7. Correção de Questões Fechadas:

curl -X POST http://localhost:3005/api/correct/1

8. Correção por IA de Questões Abertas:

curl -X POST http://localhost:3005/api/trigger-ai-correction \
  -H "Content-Type: application/json" \
  -d '{
    "examId": 1,
    "model": "GEMINI_2_5_FLASH"
  }'

Cenários de erro a testar:

• Criação de prova sem questões (deve retornar 400)

• Criação de prova com questões inexistentes (deve retornar 400)

• Submissão para prova inexistente (deve retornar 404)

• Submissão para prova fechada (deve retornar 410)

• Submissão com respostas incompletas (deve retornar 400)

• Submissão duplicada (deve retornar 409)

• Geração de PDF sem questões (deve retornar 400)

• Servidor: http://localhost:3005

• Cliente: http://localhost:3004

📸 Screenshots/GIFs

N/A - Esta PR inclui funcionalidades de backend e frontend. Screenshots podem ser adicionados em PRs futuras focadas em UI/UX.

✅ Checklist

• Código segue os padrões do projeto
• Realizei self-review do código
• Comentei código em áreas complexas
• Atualizei a documentação (se necessário)
• Mudanças não geram warnings
• Adicionei testes que provam que a correção/feature funciona
• Testes novos e existentes passam localmente
• Mudanças dependentes foram merged e publicadas

🔗 Issues relacionadas

• Closes #
• Relacionado a #