Consistência de Dados

Para preservar a integridade das informações pedagógicas, administrativas e operacionais da plataforma Lumen ERP, 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; as marcadas como "somente interface web" tratam de cadastros que a API não altera. Na API, a recusa retorna 422 Unprocessable Entity (ou 409 Conflict, quando indicado) com uma mensagem em português e, quando a regra tem um código, o campo code (por exemplo, {"success": false, "code": "HAS_ENROLLMENTS", "message": "…"}).

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 (API): 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).

Somente interface web: a API apenas consulta os tipos de período.

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.

Somente interface web: a API apenas consulta as séries.

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.

Código (API): IN_USE_BY_CLASSROOM

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 nela, em qualquer status (inclusive canceladas ou transferidas). A presença de professores vinculados não bloqueia a remoção: se a turma não tem matrículas, 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.

Na API: PUT /v1/partners/school/{cnpj}/classroom/{id} com teacher_subjects responde 422, sem code.

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 ela não tenha matrículas. Remova ou limpe as avaliações antes de excluir a turma.

Código (API): HAS_SCORES

14

Reativação de matrícula com matrícula ativa existente

Não é possível reativar uma matrícula de um aluno que já possui outra matrícula ativa. Consideram-se matrículas ativas aquelas com status MATRICULADO, APROVADO, REPROVADO ou REMANEJADA. A solicitação de reativação deve ser feita somente após encerrar ou remover a matrícula em andamento. Esta validação retorna 409 Conflict. A reativação é feita pela interface web; a API de parceiros não a expõe.

15

Disciplina vinculada a séries ou professores

Não é possível excluir uma disciplina (Subject) enquanto ela estiver vinculada a uma série ou atribuída a um professor em alguma turma. Desfaça esses vínculos antes. Esta validação retorna 409 Conflict.

Códigos (API): IN_USE_GRADE, IN_USE_TEACHER

16

Desvincular disciplina de uma série

Não é possível desvincular uma disciplina de uma série (GradeSubject) enquanto houver carga horária configurada para essa disciplina na série (GradeSubjectWorkload) ou enquanto ela estiver atribuída a um professor em alguma turma da série. Remova antes a carga horária e as atribuições. Esta validação retorna 409 Conflict, sem code; a mensagem diz qual dos dois vínculos impede a operação.

Na API: DELETE /v1/partners/school/{cnpj}/grade/{gradeId}/subject/{subjectId}.

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 422 e 409 exibindo a mensagem retornada ao usuário; use code, quando presente, para decidir o que fazer no seu código.
  • 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.