Pular para o conteúdo principal

Feature: Troca de Turma

Introdução ao documento​

Este documento descreve a feature de troca de turma: seleção de ciclo, filtro por ano e definição da turma corrente no navegador e no contexto da aplicação. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:9-55, src/components/ChangeCycle/ChangeCycle.component.tsx:80-202.

Versionamento​

  • Documento criado em 2026-03-20.
  • Revisar quando mudarem trocar-turma/page.tsx, ChangeCycle, /api/cycles/* ou o helper de persistência de class_id. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:18-35, src/components/ChangeCycle/ChangeCycle.component.tsx:109-202, src/app/services/bff/ClassService.ts:54-59.

Referencial teórico​

O fluxo foi derivado da página protegida de troca de turma, do componente ChangeCycle e dos BFFs de ciclo/turma. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:24-35, src/components/ChangeCycle/ChangeCycle.component.tsx:109-202.

Visão geral​

  • A página carrega os ciclos disponíveis para o usuário e renderiza ChangeCycle. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:24-40.
  • O componente filtra ciclos pelo curso da turma atual e pode trocar o ano quando o papel é supervisor. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:109-132, src/components/ChangeCycle/ChangeCycle.component.tsx:215-224.
  • Após a escolha da turma, class_id é persistido em localStorage com expiração de 24 horas. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:190-199.

Atores​

  • Facilitador e supervisor trocando a turma corrente. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:31-36, src/components/ChangeCycle/ChangeCycle.component.tsx:215-224.
  • Backend de ciclos e turmas. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:109-149, src/app/services/bff/ClassService.ts:54-59.

Pré-condições​

  • Sessão válida. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:18-22.
  • classId e classesData carregados no contexto. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:94-95, src/components/ChangeCycle/ChangeCycle.component.tsx:175-177.
  • Existência de ciclos retornados por getCycles(token). Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:24-40.

Fluxo principal​

  1. A página busca ciclos do usuário autenticado. Evidências: src/app/(protected-routes)/trocar-turma/page.tsx:24-25.
  2. O componente filtra os ciclos pelo curso da turma atual. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:113-119, src/components/ChangeCycle/ChangeCycle.component.tsx:125-132.
  3. Ao clicar em um ciclo, a UI busca as turmas daquele ciclo e as organiza por turno. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:139-164.
  4. Ao escolher a turma, a aplicação grava class_id, atualiza o contexto e redireciona. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:179-202.

Fluxos alternativos​

  • Se cycles vier vazio, a UI mostra Não há ciclos disponíveis.. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:227-246.
  • Se os dados da turma clicada não existirem em classesData, o fluxo tenta abrir NotifyModal. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:179-188.
  • Se a busca por ciclos/turmas estiver carregando, a tela exibe Loader. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:175-177, src/components/ChangeCycle/ChangeCycle.component.tsx:206.

Regras de negócio​

  • O dropdown de ano só aparece para role === 'supervisor'. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:215-224.
  • Os anos oferecidos no dropdown são os 3 últimos anos contando do ano corrente. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:170-173.
  • A turma é organizada em diurno, vespertino, noturno e unica pelo campo turno.value. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:157-164.
  • class_id ganha expiração de 24 horas em class_id_expiration. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:190-195.

Estados possíveis​

  • carregando: isLoading ativo ou contexto ausente. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:96, src/components/ChangeCycle/ChangeCycle.component.tsx:175-177, src/components/ChangeCycle/ChangeCycle.component.tsx:206.
  • sem_ciclos: lista vazia. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:242-245.
  • ciclo_selecionado: currentCycle definido e classes carregadas. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:145-148, src/components/ChangeCycle/ChangeCycle.component.tsx:254-320.
  • turma_trocada: class_id persistido e navegação executada. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:193-202.

Endpoints envolvidos​

  • Ver OpenAPI: GET /api/cycles/{id}, GET /api/cycles/by-year/{year}, GET /api/class/{id}, GET /api/classes.

Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:109-149, src/app/services/bff/ClassService.ts:24-59.

Dados impactados​

  • Ver model.md: Class, Cycle, curso da turma ativa e seleção corrente.
  • O fluxo persiste class_id e class_id_expiration no navegador. Evidências: src/components/ChangeCycle/ChangeCycle.component.tsx:193-195.

Pendências​

  • O retorno visual quando classesData não contém a turma selecionada não está corretamente encadeado ao render da página; o código retorna NotifyModal dentro do handler.
  • A expiração de 24 horas do class_id não está documentada em outro lugar do produto.