Pular para o conteúdo principal

Feature: Gestão de Atividades

Introdução ao documento​

Este documento cobre a visão do facilitador para acompanhar, baixar, marcar e avaliar atividades da turma, incluindo modo de recuperação e templates por atividade. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:11-45, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:61-145, src/components/ActivityManagement/ActivityManagement.component.tsx:100-359.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem ActivityManagement, ActivityEvaluationSlider, hooks de submissão ou /api/activity-template e /api/submissions/*. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:100-359, src/components/ActivityEvaluationSlider/ActivityEvaluationSlider.component.tsx:82-223, src/app/api/activity-template/route.ts:3-200.

Referencial teórico​

O fluxo foi derivado das páginas de gestão, do componente ActivityManagement, da avaliação individual e do BFF de submissões. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:17-40, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:61-145, src/app/services/bff/SubmissionService.ts:17-197.

Visão geral​

  • A página principal mostra a turma corrente e abre a tela de gestão com filtros, resumo e ações. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:19-40.
  • A página /gestao-de-atividades/[id] foca na avaliação individual de um participante e usa sessionStorage para recuperar contexto. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:44-59, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:101-145.
  • A gestão suporta download de lote, atualização para plataforma externa e upload/remoção de templates por atividade. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:179-208, src/components/ActivityManagement/ActivityManagement.component.tsx:248-289.

Atores​

  • Facilitador/supervisor gerindo e avaliando atividades. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:11-45.
  • Participante avaliado, identificado por selectedParticipant. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:35-43, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:94-145.
  • Serviço externo de submissões/templates. Evidências: src/app/services/bff/SubmissionService.ts:17-197, src/hooks/useActivityTemplates.ts:34-118.

Pré-condições​

  • Sessão válida na página protegida. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:11-15.
  • classId e classesData carregados no contexto. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:122-142.
  • Para avaliação individual, selectedParticipant e selectedActivity devem existir em sessionStorage. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:44-59, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:94-99.

Fluxo principal​

  1. O facilitador entra em /gestao-de-atividades; a tela renderiza troca de turma e ActivityManagement. Evidências: src/app/(protected-routes)/gestao-de-atividades/page.tsx:17-40.
  2. O hook de submissões carrega a turma e seus estudantes/atividades. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:124-138.
  3. O usuário pode filtrar participantes, baixar atividades recebidas, marcar envio externo ou abrir a avaliação individual. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:179-208, src/components/ActivityManagement/ActivityManagement.component.tsx:227-246, src/components/ActivityManagement/ActivityManagement.component.tsx:315-359.
  4. Ao abrir a avaliação individual, a página recupera o participante do sessionStorage e busca todas as submissões do participante para montar o slider. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:44-59, src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:61-85.

Fluxos alternativos​

  • Se classId ou classesData não estiverem prontos, a tela fica em Loader. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:140-142.
  • Em modo de recuperação, o label da atividade usa collective_meetings em vez de nª atividade. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:144-158.
  • Se a turma individual não puder ser carregada na avaliação, ActivityEvaluationSlider mostra NotifyModal. Evidências: src/components/ActivityEvaluationSlider/ActivityEvaluationSlider.component.tsx:126-140.

Regras de negócio​

  • Os status canônicos de atividade observados são avaliada, recebida, não recebida e enviada por outra plataforma. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:34-38.
  • O modo de recuperação é ativado quando enable_strategic_activities está desligado e is_recovery_enabled está ligado. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:145-148.
  • Downloads em lote só aparecem quando a data atual está dentro do limite de edição da turma. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:315-321.
  • Upload de template exige course_id, activity_id, cycle_id, class_id e arquivo. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:248-265, src/app/api/activity-template/route.ts:22-32.
  • A soma de atividades avaliáveis na tela individual considera tanto configuração da turma quanto o maior activity_id encontrado nas submissões. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:69-84.

Estados possíveis​

  • recebida, avaliada, nao_recebida, externa: estados observados na grade da gestão. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:34-38.
  • loading: carregamento da turma ou da avaliação individual. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:140-142, src/components/ActivityEvaluationSlider/ActivityEvaluationSlider.component.tsx:126-128.
  • sem_participante_selecionado: página individual mantém Loader. Evidências: src/app/(protected-routes)/gestao-de-atividades/[id]/page.tsx:94-99.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/submissions, GET /api/submissions/status-sumary, GET /api/submissions/download, GET /api/submissions/class/{id}, PUT /api/submissions/{id}, DELETE /api/submissions/{id}, GET /api/activity-template, POST /api/activity-template, DELETE /api/activity-template.

Evidências: src/app/services/bff/SubmissionService.ts:17-197, src/hooks/useActivityTemplates.ts:34-118, src/app/api/submissions/status-sumary/route.ts:6-49.

Dados impactados​

  • Ver model.md: Submission, ActivityTemplate, Class, Student e estados de atividade.
  • A navegação para avaliação individual também grava selectedParticipant e selectedActivity em sessionStorage. Evidências: src/components/ActivityManagement/ActivityManagement.component.tsx:235-245.

Pendências​

  • O contrato da utilidade updateActivityToExternalUtil não está documentado fora do código.
  • A feature de avaliação depende de ActivityEvaluation.component, mas parte do comportamento de score/comentário está fora dos arquivos inspecionados neste inventário.