Pular para o conteúdo principal

Feature: Atividades Estratégicas

Introdução ao documento​

Este documento descreve o fluxo de envio de atividades estratégicas e de recuperação: listagem de atividades, upload de arquivos, uso de templates e registro de submissão. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:15-37, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:81-223, src/components/EnvioDeAtividades/components/Upload.component.tsx:136-232.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem a página /atividades-estrategicas, StrategicActivitiesSlider, Upload.component.tsx ou /api/submissions e /api/activity-template. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:15-37, src/app/api/submissions/route.ts:4-91, src/app/api/activity-template/route.ts:3-200.

Referencial teórico​

O fluxo foi derivado da página protegida de atividades, do slider de submissões, do upload de arquivos e do hook de templates. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:24-36, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:81-223, src/hooks/useActivityTemplates.ts:25-134.

Visão geral​

  • A página aceita query params para recuperação (recoveryIndex, recoveryName, recoveryMode). Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:7-36.
  • O slider carrega submissões da turma e preenche posições vazias para atividades ainda não enviadas. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:86-145.
  • O upload monta FormData com dados do participante, curso, turma, ciclo, facilitador, arquivos e status=submitted. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:149-182.

Atores​

  • Participante enviando atividades. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:18-36, src/components/EnvioDeAtividades/components/Upload.component.tsx:146-182.
  • Facilitador que recebe e avalia submissões. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:166-176.
  • Serviço externo de submissões e storage de arquivos. Evidências: src/app/api/submissions/route.ts:12-31, src/app/api/submissions/files/[...path]/route.ts:17-60.

Pré-condições​

  • Sessão válida e classId/classesData no contexto. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:18-22, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:71-79.
  • courseId, cycleId e classId válidos para buscar templates. Evidências: src/hooks/useActivityTemplates.ts:34-45, src/hooks/useActivityTemplates.ts:60-72.
  • Arquivos selecionados com MIME type permitido. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:206-221.

Fluxo principal​

  1. A página calcula o modo normal ou de recuperação a partir da query string. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:24-36.
  2. O slider busca submissões com filtros participant_id, course_id e class_id. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:85-93.
  3. A UI monta a sequência de atividades enviadas e vazias, ou reduz para uma única atividade em recuperação. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:96-145.
  4. O upload valida tipos de arquivo, monta FormData e chama createSubmission. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:136-203, src/components/EnvioDeAtividades/components/Upload.component.tsx:206-231.
  5. Em sucesso, o fluxo registra log Enviou ATIVIDADE ESTRATEGICA X e atualiza o contexto de submissões. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:184-193, src/components/EnvioDeAtividades/components/Upload.component.tsx:121-128.

Fluxos alternativos​

  • Em modo de recuperação, a tela mostra apenas a atividade alvo e cria um placeholder sent: false quando ainda não existe submissão. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:96-115.
  • Se a busca de submissões falhar, a UI abre NotifyModal. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:147-149, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:216-223.
  • Se o arquivo tiver tipo inválido, o upload marca erro imediatamente. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:211-221.

Regras de negócio​

  • O índice de recuperação recebido na URL é convertido para zero-based antes de alimentar o slider. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:24-26.
  • No modo normal, a quantidade final de slides é o máximo entre strategic_activities_number e o maior activity_id já submetido. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:117-145.
  • Apenas tipos de arquivo presentes em allowedSubmitionTypes são aceitos. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:20, src/components/EnvioDeAtividades/components/Upload.component.tsx:211-221.
  • O upload sempre envia status=submitted. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:177.
  • A API de templates exige class_id, course_id e cycle_id para GET, e também activity_id para DELETE. Evidências: src/app/api/activity-template/route.ts:78-89, src/app/api/activity-template/route.ts:147-159.

Estados possíveis​

  • nao_enviada: placeholder sent: false. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:108-113, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:138-141.
  • enviada: submissão existente transformada para o slider. Evidências: src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:93-105.
  • erro_upload: erro mostrado por NotifyModal. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:193-200.
  • modo_recuperacao: renderização de uma única atividade. Evidências: src/app/(protected-routes)/atividades-estrategicas/page.tsx:27-35, src/components/StrategicActivitiesSlider/StrategicActivitiesSlider.component.tsx:96-115.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/submissions, POST /api/submissions, GET /api/submissions/api-token, GET /api/submissions/files/{path}, GET /api/activity-template, POST /api/activity-template, DELETE /api/activity-template, POST /api/logs.

Evidências: src/app/services/bff/SubmissionService.ts:17-99, src/app/api/submissions/route.ts:4-91, src/app/api/submissions/files/[...path]/route.ts:3-68, src/hooks/useActivityTemplates.ts:34-118, src/app/api/logs/route.ts:20-40.

Dados impactados​

  • Ver model.md: Submission, ActivityTemplate, Class, Course, Cycle e log de ação.
  • O fluxo também gera blobs temporários com URL.createObjectURL no navegador. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:223-229.

Pendências​

  • O schema completo do retorno de templates não está formalizado além do tipo local ActivityTemplate.
  • O código comenta uma regra de bloqueio por atividade anterior, mas ela está desativada. Evidências: src/components/EnvioDeAtividades/components/Upload.component.tsx:136-140.