Consistência de Dados

Para preservar a integridade das informações pedagógicas, administrativas e operacionais da plataforma To Aqui Escola, certas operações de remoção ou alteração são bloqueadas quando existem dados dependentes em uso. As regras abaixo se aplicam tanto à interface web quanto à API de parceiros, e retornam respostas HTTP com status 422 Unprocessable Entity quando a operação é negada.

Essas validações existem porque a remoção indiscriminada de entidades como turmas, grades, séries, ano letivo, professores e responsáveis poderia gerar dados órfãos, inconsistências em históricos escolares, perda de registros de frequência e quebra de quadros de horários já planejados.

1

Portões com sessões de acesso em andamento

Não é possível excluir um portão (SchoolEntrance) enquanto existir uma sessão de acesso (SchoolAccessSession) com status ONGOING.

Código: HAS_ONGOING_SESSION

2

Tipos de período em uso no quadro de horários

Não é possível remover um tipo de período (ClassPeriodType) enquanto algum período (ClassroomSchedulePeriod) associado a ele estiver sendo utilizado em entradas do quadro de horários (ClassroomTimetableEntry).

3

Séries em uso e reordenação bloqueada

Não é possível remover uma série (Grade) enquanto existir uma turma com quadro de horários montado utilizando essa série. Da mesma forma, a reordenação de séries é bloqueada quando alguma das turmas afetadas já possui entradas no quadro de horários — pois isso poderia comprometer a estrutura pedagógica vigente.

4

Carga horária em uso pelo quadro de horários

A carga horária (GradeWorkload) associa disciplinas a uma série. Não é possível remover ou esvaziar a carga horária de uma disciplina enquanto turmas dessa série tiverem entradas no quadro de horários.

Código (API): IN_USE_BY_TIMETABLE

5

Plano de curso (Curriculum Plan)

Um plano de curso (CurriculumPlan) não pode ser excluído enquanto a disciplina vinculada a ele estiver sendo utilizada no quadro de horários de ao menos uma turma. A exclusão é permitida quando não há entradas de quadro de horários (ClassroomTimetableEntry) associadas à disciplina do plano para turmas da mesma escola.

Código (API): IN_USE_BY_TIMETABLE

6

Quadro de horários (Timetable)

Entradas do quadro de horários (ClassroomTimetableEntry) só podem ser modificadas pelos fluxos próprios. Alterações em entidades dependentes (turmas, séries, professores, disciplinas, períodos) são bloqueadas se afetarem horários já montados.

7

Forma de avaliação em uso

Não é possível excluir uma forma de avaliação (FormOfEvaluation) enquanto houver turmas (Classroom) referenciando-a.

8

Ano letivo em uso por turmas

O ano letivo (SchoolYear) não pode ser excluído enquanto houver turmas vinculadas a ele, mesmo que essas turmas não tenham matrículas.

Código (API): IN_USE_BY_CLASSROOM

9

Aluno com matrícula ativa

Não é possível excluir um aluno (Student) enquanto possuir matrícula com status MATRICULADO. Alunos com matrículas em outros estados (cancelada, transferida, etc.) podem ser removidos, porém recomenda-se manter o registro para fins históricos.

Código (API): HAS_ENROLLMENTS

10

Responsável com alunos vinculados

Não é possível excluir um responsável (Responsible) enquanto houver alunos vinculados a ele. Remova ou transfira primeiro os vínculos antes de apagar o responsável.

Código (API): HAS_STUDENTS

11

Turma com alunos matriculados

Não é possível excluir uma turma (Classroom) enquanto houver matrículas ativas. A presença de professores vinculados não bloqueia a remoção: se a turma não tem alunos matriculados, ela pode ser excluída e seus vínculos com professores serão removidos automaticamente.

Código (API): HAS_ENROLLMENTS

12

Remoção de disciplina de professor em uso

Não é possível remover uma associação (professor, disciplina) de uma turma quando essa combinação estiver sendo utilizada em uma entrada do quadro de horários (ClassroomTimetableEntry) da própria turma. Para realizar essa remoção, é necessário antes desfazer a entrada correspondente no quadro de horários.

13

Turma com avaliações registradas

Não é possível excluir uma turma (Classroom) enquanto houver notas (StudentScore) registradas para alunos nessa turma, mesmo que não haja matrículas ativas. Remova ou limpe as avaliações antes de excluir a turma.

Código (API): HAS_SCORES

Boas práticas para integrações

  • Antes de remover uma entidade, verifique seus vínculos através dos endpoints de listagem disponíveis.
  • Trate as respostas com status 422 exibindo a mensagem retornada ao usuário.
  • Considere usar os webhooks para acompanhar criações, atualizações e remoções de turmas e matrículas.
  • Em fluxos de migração, finalize matrículas e quadros de horários do ano anterior antes de remover séries ou anos letivos.