Modelo de Domínio

O que é este documento — o catálogo das entidades do ionCLASS e como elas se ligam: quem é o aluno central, o que é um responsável sem conta, como um terceiro vira autorizado, e quais tipos governam os estados. É a referência de o que existe no domínio e por quê, para não sair adivinhando relação.

1. Convenções que valem para tudo

Identificadores UUID. Cada registro é identificado por um UUID (identificador único global), não por número sequencial.
Responsável sem conta. O responsável pode existir antes de ter uma conta no app — ele nasce na importação e a conta só é materializada no primeiro cadastro.
Exclusão reversível nas entidades de cadastro (rede, escola, turma, aluno, responsável, liberação antecipada), preservando o histórico.
Controle de gravação. Quais campos podem ser gravados é decidido nas ações de negócio e nas regras de validação de entrada, não numa lista fixa por entidade.

2. Entidades centrais

Entidade	Propósito	Relações-chave
Rede escolar	A rede (grupo escolar / mantenedora). Topo da hierarquia; tem um status (ativa/inativa).	contém escolas; administradores vinculados
Escola	Uma escola da rede; status ativa/inativa. Unidade de escopo (tenant) de quase tudo.	pertence a uma rede; tem pontos de retirada; responsáveis vinculados (N:N)
Turma	A turma. Única na escola por (nome, turno) — o turno vive aqui, não no aluno. Janela de saída customizável por dia da semana.	pertence à escola; alunos (N:N); janelas de retirada por dia
Janela de retirada	A janela de retirada de um dia da turma. Dia da semana (0=Dom … 6=Sáb), no máximo uma linha por (turma, dia); horário de início/fim pode diferir por dia.	pertence à turma
Ponto de retirada	O ponto de retirada (portão). Toda escola tem ao menos um; um deles é o "Portão principal" padrão. Pode ser desativado preservando o histórico.	pertence à escola
Conta de usuário	A conta (staff ou app). Tem um papel e um status; o vínculo direto a uma escola só existe para o operador.	pode ter um responsável associado; tokens de push, preferências, consentimentos; administra redes
Responsável	O responsável. ⚠️ Pode existir sem conta — é criado na importação e a conta nasce só no cadastro. Guarda CPF, nome, email (opcional) e telefone (opcional).	pode ter conta; vinculado a várias escolas (N:N, com status); vinculado a alunos; terceiros autorizados, liberações, veículos
Aluno	A entidade central do domínio. A matrícula é a chave externa do controle de acesso (matrícula ↔ hardware). Carrega o estado vivo de retirada, a versão do estado (lock otimista) e quando ele mudou, além do ponto de retirada atual.	pertence à escola; turmas (N:N); responsáveis (N:N); retiradas, liberações; sinais de chegada, terceiros autorizados; atividades de controle de acesso
Vínculo aluno ↔ responsável	O vínculo com regras. Tipo de parentesco; permissões (capacidades); status; janela de validade (permanente = sem datas).	vínculo entre aluno e responsável
Terceiro autorizado	O terceiro autorizado a retirar (avô, motorista, babá…). Status; permissões copiadas ao vínculo na aprovação; janela de validade; marca de sincronização de hardware pendente.	escola; responsável autorizador/autorizado; alunos; quem aprovou
Liberação antecipada	A liberação antecipada (saída fora do horário), one-shot. Exatamente um motivo do catálogo ou um motivo livre; modo de saída solo/acompanhado; status.	escola, aluno, responsável, motivo, quem aprovou
Catálogo de motivos	O catálogo de motivos de liberação antecipada por escola (ativo).	escola; quem criou
Sinal de chegada	O toque "Estou Chegando" do responsável. Criado quando o geofence passa; encerrado ao confirmar retirada ou por timeout (com fim e motivo). Origem, verificação de identidade, coordenadas reportadas.	escola, usuário responsável, veículo, ponto de retirada; alunos
Retirada	O registro imutável da retirada (evento consumado). Método (fonte vencedora); a chave de idempotência deduplica a corrida entre fontes numa janela de 5 min; quando foi confirmada e quando o hardware confirmou.	escola, aluno, sinal de chegada; pessoa que retirou/confirmou
Veículo do responsável	O veículo do responsável na retirada. Só um favorito por responsável.	pertence ao responsável
Configuração de integração	A config do hardware por escola (uma por escola). Tipo de integração; chaves HMAC encriptadas por direção (a chave de eventos verifica o FLUXO A, a chave de comandos assina o FLUXO B); endereço base; ativo.	escola
Evento de controle de acesso	O evento inbound do controle de acesso (`entry`/`exit`) persistido antes de processar. Deduplicado por (integração + id do evento); o aluno é resolvido a partir de `student_external_id`; guarda o conteúdo cru e o status de processamento.	escola, aluno
Comando outbound	A chamada outbound para o hardware (FLUXO B). Ação, entidade alvo, conteúdo, status, contagem de tentativas, próxima tentativa. A linha evolui em lugar; o histórico vai para a auditoria.	escola
Registro de consentimento	O consentimento LGPD de uma versão. Termos e Biometria são separados; só a revogação muda depois. Bump de versão não re-bloqueia usuários.	usuário
Token de push	O token de push (FCM) de um aparelho. Plataforma, token, último uso.	usuário
Preferência de notificação	O opt-in/opt-out por tipo de notificação (ex.: retirada pronta). Default: push=true, email=false.	usuário
Configuração de trabalho do operador	A config de trabalho do operador no monitor: quais turmas, turnos e pontos de retirada ele cobre. Uma por operador; o board fica desabilitado enquanto vazia.	usuário, escola
Token do painel público	O token do painel público/kiosk por escola. Rótulo, expiração, revogação, último uso.	escola; quem criou
Trilha de auditoria	A trilha de auditoria append-only. Imutabilidade garantida no banco + guarda na aplicação. Estado antes/depois, identificador de correlação, carimbo de tempo imutável.	usuário, escola (opcional)
Papel	O papel (pacote de permissões finas) com atributos do ionCLASS: escopo, rede, escola, descrição, se é template.	rede, escola

Vínculos de apoio: responsável ↔ escola (com status), sinal de chegada ↔ aluno, terceiro autorizado ↔ aluno. Processos de importação/relatório existem à parte do núcleo de retirada.

3. Esboço entidade-relação (núcleo)

   Rede escolar
        │ 1─N
        ▼
     Escola ──1─N──▶ Turma ──1─N──▶ Janela de retirada (por dia)
        │ │  \              ▲
        │ │   \             │ N:N (turma ↔ aluno)
        │ │    \────────────┴──────────┐
        │ │                            │
        │ │ 1─N                        │
        │ ▼                            ▼
        │ Ponto de retirada      ┌──────────────┐
        │ (portão)               │    Aluno     │  ← matrícula = chave do controle de acesso
        │                        │ estado vivo  │    versão do estado (lock otimista)
        │                        └──┬────┬────┬─┘
        │ N:N (responsável↔escola)  │    │    │
        ▼                           │    │    │ 1─N
   Responsável ◀── N:N ─────────────┘    │    └────────▶ Retirada (registro imutável)
   (pode não ter conta)  vínculo         │                  método vencedor
                         (tipo, permissões,                  chave de idempotência
                          status, validade)  │ N:N
        │ 1─N                                └───────▶ Sinal de chegada ("Estou Chegando")
        ├──▶ Terceiro autorizado ──N:N──▶ Aluno
        ├──▶ Liberação antecipada (one-shot)
        └──▶ Veículo do responsável

Leituras do esboço:

O aluno é o hub. Tudo do momento da retirada gira em torno dele: o estado vivo (e sua versão), os sinais de chegada, as liberações e o registro final da retirada.
Aluno ↔ responsável é N:N, e esse vínculo carrega regras (tipo de parentesco, capacidades, status de aprovação e validade) — não é um vínculo "burro".

4. Escopo de escola: N:N do responsável × 1 do operador

Duas formas de pertencer a uma escola, e é isso que explica o header X-School-Id:

⚠️ Responsável → N:N. Um responsável liga-se a várias escolas (com um status por escola). Por isso o mobile precisa dizer qual escola está ativa enviando X-School-Id a cada request.
Operador → 1 escola. Um operador pertence a exatamente uma escola. O monitor não envia header — o backend resolve a escola pelo token.

Detalhe dos dois fluxos de auth no documento de autenticação e autorização.

5. Estados e tipos de domínio

Conjunto	Valores (em produto)	Onde importa
Tipo de usuário (papel/persona)	dono da plataforma, admin de rede, admin de escola, operador, responsável, terceiro autorizado	audiências de auth → autenticação e autorização
Estado de retirada	fora da escola, na escola, aguardando retirada, em preparação, pronto, retirado	estado vivo do aluno → ciclo de retirada, tempo real
Método de retirada	visual (operador), visual na hora (busca no balcão), hardware (controle de acesso), liberação solo aprovada	fonte vencedora da retirada → ciclo de retirada
Turno	manhã, tarde, noite, integral	vive na turma
Status do vínculo responsável ↔ escola	ativo, bloqueado	vínculo responsável ↔ escola
Status do terceiro autorizado	pendente, aprovado, rejeitado, mudanças solicitadas, suspenso, cancelado, expirado	ciclo de aprovação do terceiro autorizado
Status da liberação antecipada	pendente, aprovado, rejeitado, mudanças solicitadas, usado, cancelado, expirado	ciclo da liberação antecipada
Status do vínculo aluno ↔ responsável	pendente, aprovado, rejeitado	vínculo aluno ↔ responsável → autenticação e autorização
Tipo de parentesco	pai/mãe, avô/avó, tio/tia, irmão/irmã, padrasto/madrasta, guardião legal, babá, motorista, amigo da família, vizinho, outro	tipo do vínculo
Capacidades por vínculo	gerenciar responsáveis, ver permissões temporárias, criar permissões temporárias, ver atividades	capacidades por vínculo → autenticação e autorização
Tipo de consentimento	termos, biometria	LGPD — dois consentimentos separados
Origem do sinal de chegada	app, facial	origem do sinal de chegada
Tipo de integração de hardware	simulação (mock), controle de acesso	seleção do driver de hardware → integração com o hardware

Tipos auxiliares de status de cadastro: status de rede (ativa/inativa), status de escola (ativa/inativa), status de usuário (convidado/ativo/inativo).

⚠️ O modo de saída de uma liberação antecipada (solo ou acompanhado) é apenas um campo validado na entrada, não um tipo fixo. Aparece na tabela de entidades como tal.

6. Ligações para aprofundar

Quero entender…	Documento
As transições de estado e o método vencedor da retirada	Ciclo de retirada
Como o estado é transmitido em tempo real	Tempo real
Papéis, status de vínculo e capacidades	Autenticação e autorização
A visão de alto nível e o contrato REST	Visão arquitetural
A integração com o hardware de controle de acesso	Integração com o hardware (visão geral · inbound · outbound)
Glossário dos termos de domínio	Glossário

Modelo de Domínio ​

1. Convenções que valem para tudo ​

2. Entidades centrais ​

3. Esboço entidade-relação (núcleo) ​

4. Escopo de escola: N:N do responsável × 1 do operador ​

5. Estados e tipos de domínio ​