Pular para o conteúdo principal

Feature: Participação

Introdução ao documento​

Este documento descreve a feature de participação e turmas: listagem de estudantes, marcação de atividades/presença, navegação como participante e solicitação de cancelamento de matrícula. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:16-57, src/components/Participacao/Participacao.component.tsx:43-109, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:148-205.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem a página /participacao/[id], ParticipacaoTable, /api/presence* ou a solicitação de cancelamento de matrícula. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:16-57, src/app/api/presence/route.ts:6-40, src/app/api/presence/recovery/route.ts:6-39, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:177-205.

Referencial teórico​

O fluxo foi derivado da página protegida de participação, do componente Participacao, da tabela desktop e do BFF de presença. Evidências: src/components/Participacao/Participacao.component.tsx:43-109, src/app/services/bff/ClassService.ts:47-99.

Visão geral​

  • A tela exibe a turma corrente, lista de participantes e seus status por atividade. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:24-57, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:285-320.
  • Em desktop, a feature usa ParticipacaoTable; em mobile, usa ActivitiesSlider. Evidências: src/components/Participacao/Participacao.component.tsx:71-97.
  • A feature também concentra navegação como participante, cancelamento e uso de WhatsApp para contato. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:6-21, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:172-205.

Atores​

  • Facilitador/supervisor gerindo a participação da turma. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:16-57.
  • Participante listado na turma. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:313-320.
  • Backend de presença, turma e matrícula. Evidências: src/app/services/bff/ClassService.ts:47-99, src/app/services/bff/ClassService.ts:123-129.

Pré-condições​

  • Sessão válida. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:18-22.
  • classId e classesData carregados. Evidências: src/components/Participacao/Participacao.component.tsx:44-52.
  • A turma precisa ter participantes; caso contrário, a UI avisa que não há participantes. Evidências: src/components/Participacao/Participacao.component.tsx:55-63.

Fluxo principal​

  1. O usuário autenticado abre /participacao/{classId}. Evidências: src/app/(protected-routes)/participacao/[id]/page.tsx:18-22.
  2. O componente Participacao busca a lista de alunos via hook useStudents(classId, token). Evidências: src/components/Participacao/Participacao.component.tsx:48-52.
  3. A UI renderiza tabela desktop ou slider mobile com os estudantes e suas atividades. Evidências: src/components/Participacao/Participacao.component.tsx:71-97.
  4. A tabela permite navegar, solicitar cancelamento e interagir com atividades conforme o período e o perfil. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:159-205.

Fluxos alternativos​

  • Se não houver participantes, a UI mostra NotifyModal e permite voltar. Evidências: src/components/Participacao/Participacao.component.tsx:55-63.
  • Se o hook falhar e students não vier, a UI mostra erro genérico. Evidências: src/components/Participacao/Participacao.component.tsx:101-108.
  • Se o usuário clicar em cancelamento de matrícula, o modal confirma e a tabela refaz a busca após sucesso. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:172-205.

Regras de negócio​

  • O total de colunas de atividade soma atividades do ciclo e 2 acessos extras quando enable_certificacao_progressiva está ativo. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:161, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:217-258, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:282-283.
  • O título de cada coluna prioriza activity_titles, depois collective_meetings, e usa fallback especial Cartão de Visitas no curso focodelas na última atividade. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:88-115.
  • A solicitação de cancelamento usa enrollment_id do aluno selecionado. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:177-183, src/app/services/bff/ClassService.ts:123-129.
  • A marcação de presença normal usa class_id, student_id e activity_id. Evidências: src/app/services/bff/ClassService.ts:61-71, src/app/api/presence/route.ts:21-29.
  • A presença de recuperação exige class_id, activity e reason. Evidências: src/app/services/bff/ClassService.ts:85-99, src/app/api/presence/recovery/route.ts:21-29.

Estados possíveis​

  • sem_participantes: modal de aviso. Evidências: src/components/Participacao/Participacao.component.tsx:55-63.
  • carregado_desktop: ParticipacaoTable renderizada. Evidências: src/components/Participacao/Participacao.component.tsx:73-84.
  • carregado_mobile: ActivitiesSlider renderizado. Evidências: src/components/Participacao/Participacao.component.tsx:85-96.
  • cancelamento_em_andamento: isSubmitting ativo. Evidências: src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:168-170, src/components/ParticipacaoTable/ParticipacaoTable.component.tsx:177-198.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/presence/{id}, POST /api/presence, POST /api/presence/recovery, GET /api/reasons, POST /api/enrollment/{enrollment_id}/request-cancellation, POST /api/participant-mode-log.

Evidências: src/app/services/bff/ClassService.ts:47-99, src/app/api/presence/route.ts:6-40, src/app/api/presence/recovery/route.ts:6-39, src/app/api/reasons/route.ts:5-21, src/app/api/participant-mode-log/route.ts:6-50.

Dados impactados​

  • Ver model.md: Student, Class, Enrollment, presença e motivo de recuperação.
  • O fluxo de navegação como participante também interage com participantModeStorage em outras partes da aplicação, mas esse contrato não está centralizado neste documento.

Pendências​

  • O hook useStudents concentra parte da regra de enriquecimento dos alunos e não está formalizado em documentação funcional.
  • A política exata de edição por período depende de helpers de data, não de um contrato externo versionado.