Pular para o conteúdo principal

Feature: Avaliação de Submissões

Introdução ao documento​

Documenta o fluxo de avaliação de submissões pelo facilitador (professor).

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Visão geral​

O facilitador avalia uma submissão existente: atualiza status para evaluated, atribui nota, registra comentário e opcionalmente anexa novos arquivos. O sistema notifica o participante sobre a avaliação.

Atores​

  • Facilitador (professor) — executa a avaliação via app mobile ou painel admin
  • Participante (aluno) — recebe notificação da avaliação
  • Sistema (Novu) — envia notificação submission-evaluated

Pré-condições​

  1. Submissão existente com status submitted ou submitted_external — Evidência: app/Models/DeliverableSubmission.php:15
  2. API Key válida — Evidência: app/Http/Middleware/ApiKeyMiddleware.php:15
  3. Workflow Novu submission-evaluated cadastrado na tabela novu_keys — Evidência: app/Services/NotificationService.php:23

Fluxo principal​

  1. App mobile envia POST /api/submissions/{id} com API Key + dados de avaliação
    • Evidência: routes/api.php:22, app/Http/Controllers/Api/SubmissionController.php:340
  2. Controller localiza submissão por ID
  3. Atualiza campos: status → evaluated, score, facilitator_comment, evaluated_at
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:340
  4. Se há novos arquivos, SubmissionFileService::replaceFiles() processa upload
    • Evidência: app/Services/SubmissionFileService.php:14
  5. NotificationService::sendNotification() envia submission-evaluated ao participante
    • Evidência: app/Services/NotificationService.php:23
  6. Retorna JSON da submissão atualizada (HTTP 200)

Fluxos alternativos​

  • Submissão não encontrada: Retorna HTTP 404.
  • Submissão já avaliada: Permite reavaliação (sobrescreve status/nota/comentário).
  • Falha Novu: Avaliação persiste mesmo que notificação falhe.

Regras de negócio​

  1. Status final: Avaliação muda status para evaluated e registra evaluated_at com timestamp.
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:340
  2. Score: Campo score é tinyint unsigned (0-255), default 0.
    • Evidência: app/Models/DeliverableSubmission.php:15
  3. Arquivos opcionais: Facilitador pode enviar novos arquivos durante avaliação (substituem anteriores).
    • Evidência: app/Services/SubmissionFileService.php:14

Estados possíveis​

  • submitted / submitted_external → evaluated (transição principal)
  • evaluated → evaluated (reavaliação)

Endpoints envolvidos​

  • POST /api/submissions/{id} — avaliar submissão (openapi.yaml)
  • Evidência: routes/api.php:22

Dados impactados​

  • deliverable_submissions — campos status, score, facilitator_comment, evaluated_at (model.md)
  • submission_files — novos arquivos se enviados (model.md)

Pendências​

  • ⚠️ PENDÊNCIA: Documentar se existe validação de range para score (0-100? 0-10?).
  • ⚠️ PENDÊNCIA: Verificar se reavaliação é intencional ou se deveria haver bloqueio após primeira avaliação.