Pular para o conteúdo principal

Feature: Submissão de Atividades

Introdução ao documento​

Documenta o fluxo de submissão de atividades entregáveis pelo participante (aluno) via aplicativo mobile.

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 participante (aluno) submete uma atividade entregável junto com arquivos anexos. O sistema persiste a submissão, armazena os arquivos no S3/local e envia notificações ao próprio participante e ao facilitador responsável.

Atores​

  • Participante (aluno) — author da submissão, autenticado via JWT
  • Facilitador (professor) — destinatário da notificação de nova submissão
  • Sistema (Novu) — envia notificações

Pré-condições​

  1. O app mobile possui uma API Key válida — Evidência: app/Http/Middleware/ApiKeyMiddleware.php:15
  2. O participante obteve JWT via GET /api/submissions/token — Evidência: app/Http/Controllers/Api/SubmissionController.php:755
  3. O workflow Novu send-submission e submission-received existem na tabela novu_keys — Evidência: app/Services/NotificationService.php:23

Fluxo principal​

  1. App mobile envia GET /api/submissions/token com API Key → recebe JWT (validade 1h)
    • Evidência: routes/api.php:15, app/Http/Controllers/Api/SubmissionController.php:755
  2. App mobile envia POST /api/submissions com JWT + dados + arquivos multipart
    • Evidência: routes/api.php:34, app/Http/Controllers/Api/SubmissionController.php:187
  3. Controller valida campos obrigatórios via DeliverableSubmissionRequest
    • Evidência: app/Http/Requests/DeliverableSubmissionRequest.php
  4. Sistema verifica unicidade (participant_id, class_id, activity_id, cycle_id)
    • Evidência: database/migrations/2025_07_28_132021_add_unique_submission_constraint_to_deliverable_submissions.php:16
  5. SubmissionFileService::replaceFiles() faz upload dos arquivos para S3/local
    • Evidência: app/Services/SubmissionFileService.php:14
  6. Submissão é criada com status submitted
    • Evidência: app/Models/DeliverableSubmission.php:15
  7. NotificationService::sendNotification() envia notificação send-submission ao participante
    • Evidência: app/Services/NotificationService.php:23
  8. NotificationService::sendNotification() envia notificação submission-received ao facilitador
    • Evidência: app/Services/NotificationService.php:23
  9. Retorna JSON da submissão criada (HTTP 201)

Fluxos alternativos​

  • Submissão duplicada: Se já existe submissão ativa para (participant_id, class_id, activity_id, cycle_id), retorna HTTP 422 (unique constraint violation).
  • MIME type inválido: Se arquivo não está na lista de tipos permitidos, retorna HTTP 422.
    • Evidência: app/Helpers/MimeTypes.php:7
  • JWT expirado: Retorna HTTP 401. Participante deve obter novo token.
    • Evidência: app/Http/Middleware/JwtAuthenticate.php:13
  • Falha Novu: Submissão é criada mesmo que notificação falhe (fire-and-forget). Erro é registrado em logs.
    • Evidência: app/Services/NotificationService.php:23

Regras de negócio​

  1. Unicidade: Uma submissão por participante/atividade/turma/ciclo (soft delete considerado).
    • Evidência: database/migrations/2025_07_28_132021_add_unique_submission_constraint_to_deliverable_submissions.php:16
  2. Status inicial: Submissões criadas via JWT recebem status submitted.
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:187
  3. MIME types: Apenas tipos listados em MimeTypes::allowed() são aceitos (imagens, vídeos, áudios, documentos Office/PDF).
    • Evidência: app/Helpers/MimeTypes.php:7
  4. Notificação dupla: Duas notificações são enviadas: uma para participante (send-submission) e outra para facilitador (submission-received).
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:187

Estados possíveis​

EstadoDescrição
pendingAguardando submissão (criada externamente)
submittedSubmetida pelo participante via JWT
submitted_externalSubmetida externamente via API Key
evaluatedAvaliada pelo facilitador
  • Evidência: database/migrations/2025_06_10_000000_update_status_enum_in_deliverable_submissions_table.php:12

Endpoints envolvidos​

  • GET /api/submissions/token — obter JWT (openapi.yaml)
  • POST /api/submissions — criar submissão (openapi.yaml)
  • Evidência: routes/api.php:15,34

Dados impactados​

  • deliverable_submissions — novo registro criado (model.md)
  • submission_files — novos registros de arquivos (model.md)
  • Storage S3/local — arquivos físicos na pasta submissions/

Pendências​

  • ⚠️ PENDÊNCIA: Validar tamanho máximo de arquivo permitido (não encontrada configuração explícita no código).
  • ⚠️ PENDÊNCIA: Documentar comportamento de retry em caso de falha de upload S3.