Painel Administrativo ionCLASS — Especificação Funcional

O que é este documento — a especificação funcional do painel administrativo web do ionCLASS (o Inertia + React servido pelo backend Laravel), acompanhada de uma reconciliação com a implementação real (§1.4). O texto original (v1.0) é uma especificação de produto ampla; as seções seguintes foram anotadas para separar o que já existe do que é aspiracional (⚠️/🔜). Superfícies irmãs: App do Responsável, Monitor de Portaria, Painel Público.

Versão da spec original: 1.0 | Data: 2026-03-20 · Reconciliação: 2026-08-12

1. Introdução e Escopo

1.1 Propósito

O painel administrativo web é a interface central de gestão do IONCLASS. Através dele, gestores e operadores configuram escolas, gerenciam alunos e responsáveis, acompanham retiradas em tempo real e garantem conformidade com ECA e LGPD.

1.2 Componentes do Ecossistema

Componente	Descrição
Painel Admin (web)	Gestão, configuração, monitoramento, relatórios
App Móvel (responsável)	"Estou Chegando", autorizações, notificações, acompanhamento
Hardware de controle de acesso	Catracas/portões — registro de entrada e saída via biometria/cartão
Interface "Estou Chegando" (tablet/mobile)	PWA dedicada para operador na portaria — gerencia fila de retirada

1.3 Delimitação

Este documento cobre o painel admin web e a operação de portaria servida pelo backend. Para as outras superfícies e para a integração com o hardware, consultar:

App do responsável → App do Responsável
Monitor de portaria (PWA) → Monitor de Portaria
Painel público (kiosk) → Painel Público
Integração com o hardware de controle de acesso → Integração (controle de acesso)
Fluxo de retirada ponta a ponta → Ciclo de Retirada

1.4 Reconciliação com a implementação (2026-08-12)

Esta seção é a fonte da verdade sobre o que existe hoje. As seções 2–10 abaixo preservam a especificação de produto original; onde ela divergir do que está descrito aqui, vale esta seção.

O que mudou desde a spec original

⚠️ Não há mais "aprovação de responsável" como gate de acesso. O onboarding do responsável é CPF + email + confirmação por código (Fortify) — sem código de convite, sem fila de aprovação (CPF desconhecido → 422 silencioso). O admin pré-cadastra responsáveis e pode bloquear/desbloquear, mas não "aprova" o acesso deles. Toda menção a status pendente/aprovado/ajuste_solicitado/rejeitado de responsável na §4.5 é obsoleta — ver a §4.5 reescrita.
✅ O que o admin ainda aprova são as duas filas de aprovação: Pessoas Autorizadas e Liberações/Saídas Antecipadas, cada uma com approve / reject / request-changes.
⚠️ Papéis dinâmicos, não hierarquia fixa. Permissões são geridas por um grid de papéis (roles). A hierarquia Owner/Admin Grupo/Admin Site/Operador da §3 é a intenção de produto; a implementação usa papéis + permissões nomeadas (monitoramento ao vivo, sinais de chegada, configurações da escola, etc.).

Capacidades implementadas (rotas reais)

Bloco de gestão (restrito a usuários autenticados e verificados):

Módulo	Página	Notas
Grupos Escolares	Gestão de grupos	CRUD + ativar/inativar + lista de admins do grupo + logo
Escolas	Gestão de escolas	CRUD + geocodificação de endereço (com throttle) + ativar/inativar (exclusão lógica, reativável) + logo
Papéis (Roles)	Grid de permissões	Grid de permissões; o escopo do papel vem do corpo da requisição, não da URL
Usuários	Gestão de usuários	CRUD direto + reset de senha + ativar/inativar. Sem convite por email — o admin define/reseta a senha
Importações	Importação em massa	Importação CSV (alunos/responsáveis): baixar modelo, upload, acompanhamento e download de erros
Responsáveis	Gestão de responsáveis	Perfil 360º, busca, vincular/desvincular alunos, bloquear/desbloquear, veículos inline
Alunos	Gestão de alunos	CRUD + foto + busca + registro manual de evento de acesso + vincular/desvincular responsáveis
Turmas	Gestão de turmas	CRUD; turno na turma e janela de retirada customizável por dia da semana
Pessoas Autorizadas	Fila de aprovação	Fila de aprovação: approve / reject / request-changes + suspend + reenvio de sincronização (controle de acesso)
Liberações (Saída Antecipada)	Fila de aprovação	Fila de aprovação: approve / reject / request-changes + cancel
Motivos de saída antecipada	Aba Configurações da escola	Catálogo (criar/editar/desativar)
Pontos de retirada (portões)	Aba Configurações da escola	Criar/editar/desativar
Integração / API	Configurações de integração	Driver de controle de acesso + "Testar integração" (ping-pong backend→plugin→backend)
Simulador de fluxo	Simulador (dev/homolog)	Gera eventos do fluxo passo a passo; responde 404 quando o simulador está desabilitado
Audit logs	Logs de auditoria	Somente leitura (append-only): apenas listagem, sem edição/exclusão
Relatórios	Central de relatórios	Exports assíncronos XLSX/CSV: painel, enfileiramento e download (stream do storage)

Bloco de operação:

Módulo	Página	Notas
Fila do Operador	Preparar / Pronto / Confirmar retirada	Versão web da fila de portaria (mesmos dados/canal do PWA)
Walk-in	Retirada avulsa	Retirada sem "Estou Chegando" prévio (busca manual do aluno)
Monitor fullscreen	Telão de tablet	Mesmos dados + canal `school.{id}.monitor` da fila
Painel Público (token)	Aba Configurações da escola	Gerar / rotacionar / revogar token do kiosk → ver Painel Público

Tempo real e escopo

Os canais privados/públicos de tempo real são: school.{id}.monitor (Admin+Operador, requer permissão de monitoramento ao vivo + ver a escola), school.{id}.queue (presença de operadores), school.{id}.public-monitor (kiosk) e responsible.{userId}.school.{schoolId} (app). Detalhes em Tempo Real e Autenticação e Autorização.

2. Arquitetura Multi-site e Grupos Escolares

2.1 Hierarquia

Plataforma
└── Grupo Escolar
    └── Site (Escola)
        └── Entidades (alunos, turmas, responsáveis…)

2.2 Regras Estruturais

Todo site pertence obrigatoriamente a um grupo escolar (escola avulsa = grupo de 1).
Isolamento total de dados por site: operador do Site A nunca vê dados do Site B.
Admin Grupo vê dados agregados ou drill-down por site dentro do seu escopo.
Owner vê tudo na plataforma.
Configurações definidas no nível de grupo servem como padrões; cada site pode aplicar override pontual.

2.3 Seletor de Contexto

Admin Site: opera no contexto fixo do seu site.
Admin Grupo: seletor de site no header + opção "Visão consolidada do grupo".
Owner: seletor de grupo + seletor de site + opção "Visão da plataforma".

3. Modelo de Permissões e Controle de Acesso

3.1 Hierarquia de Papéis

Papel	Escopo	Descrição
Owner	Plataforma	Acesso total irrestrito. Gerencia grupos, configurações globais e outros owners.
Admin Grupo Escolar	Um ou mais grupos	Visão consolidada do grupo, drill-down por site, CRUD completo dentro do escopo atribuído.
Admin Site	Um site	Controle total do site: CRUDs, configurações, monitoramento, relatórios.
Operador	Um site	Acesso restrito conforme perfil de operador atribuído.

3.2 Sistema de Perfis de Operador

Um perfil é um conjunto nomeado de permissões reutilizável.

Perfis podem ser definidos no nível de grupo (compartilhados entre sites) ou de site (específicos).
Cada operador recebe um perfil por site em que atua.
A plataforma oferece templates pré-configurados para setup rápido (Porteiro, Secretaria, Coordenador de Turno).
Admin Grupo/Site pode criar perfis customizados.

3.3 Permissões Granulares por Domínio

Cada domínio possui ações específicas. A permissão é a combinação domínio.ação.

Domínio	Ações Possíveis
`alunos`	`ver`, `criar`, `editar`, `excluir`
`responsaveis`	`ver`, `criar`, `editar`, `excluir`, `bloquear` (⚠️ sem `aprovar`/`rejeitar` — responsável não é mais aprovado; ver §1.4 e §4.5)
`autorizados`	`ver`, `criar`, `editar`, `excluir`, `aprovar`, `rejeitar`
`liberacoes_temporarias`	`ver`, `criar`, `editar`, `excluir`, `aprovar`, `rejeitar`
`turmas`	`ver`, `criar`, `editar`, `excluir`
`agenda`	`ver`, `criar`, `editar`, `excluir`
`comunicados`	`ver`, `criar`, `editar`, `excluir`
`monitor_tempo_real`	`ver`
`estou_chegando`	`ver`, `atualizar_status`
`relatorios`	`ver`, `exportar`
`audit_logs`	`ver`
`usuarios`	`ver`, `criar`, `editar`, `excluir`
`configuracoes_site`	`ver`, `editar`

3.4 Exemplos de Perfis Pré-configurados

Porteiro:

monitor_tempo_real.ver
estou_chegando.ver, estou_chegando.atualizar_status
alunos.ver

Secretaria:

CRUD completo: alunos.*, responsaveis.*, autorizados.*, liberacoes_temporarias.*, turmas.*, agenda.*, comunicados.*
monitor_tempo_real.ver, estou_chegando.*

Coordenador de Turno:

Todas as permissões da Secretaria
relatorios.ver, relatorios.exportar
audit_logs.ver
usuarios.ver

4. CRUDs — Especificação Detalhada

Convenções: campos marcados com * são obrigatórios. Todas as entidades possuem id, created_at, updated_at e deleted_at (soft delete) implícitos.

4.1 Grupos Escolares

Permissão: Owner (CRUD completo), Admin Grupo (ver/editar o próprio grupo)

Campo	Tipo	Regras
`nome`*	string(200)	Único na plataforma
`cnpj`	string(18)	Formato XX.XXX.XXX/XXXX-XX, validação de dígito verificador
`endereco`	text	Endereço completo
`telefone`	string(20)	Formato brasileiro
`email`	email	Validação de formato
`logo`	image	JPG/PNG, max 2MB, redimensionado para 256×256
`status`*	enum	`ativo`, `inativo`

Regras de negócio:

Inativar um grupo inativa todos os sites vinculados (com confirmação).
Não é possível excluir grupo com sites ativos.

4.2 Escolas (Sites)

Permissão: Owner (CRUD completo), Admin Grupo (CRUD no escopo), Admin Site (ver/editar o próprio site)

Campo	Tipo	Regras
`nome`*	string(200)	Único dentro do grupo
`grupo_id`*	FK	Referência ao grupo escolar
`cnpj`	string(18)	Validação de dígito verificador
`endereco`*	text	Endereço completo
`telefone`	string(20)	Formato brasileiro
`timezone`*	string	Default: `America/Sao_Paulo`
`latitude`*	decimal(10,7)	Para geofencing
`longitude`*	decimal(10,7)	Para geofencing
`raio_geofencing`*	int	Em metros. Default: 500. Min: 100, Max: 5000
`modo_pickup`*	enum	`hardware`, `qr_code`, `ambos`
`logo`	image	JPG/PNG, max 2MB
`status`*	enum	`ativo`, `inativo`

4.2.1 Janelas de Retirada

Cada site define N janelas de retirada nomeadas. O monitoramento e "Estou Chegando" se ativam conforme a janela vigente.

Campo	Tipo	Regras
`nome`*	string(100)	Ex: "Saída manhã", "Saída tarde", "Saída integral"
`site_id`*	FK	Referência ao site
`hora_inicio`*	time	HH:MM
`hora_fim`*	time	HH:MM. Deve ser > `hora_inicio`
`dias_semana`*	int[]	0=dom … 6=sáb
`turmas_aplicaveis`	FK[]	Se vazio, aplica a todas
`ativo`*	boolean	Default: true

Regras de negócio:

Janelas do mesmo site não podem ter sobreposição de horário para as mesmas turmas.
Ao inativar um site, todas as janelas são automaticamente desativadas.

4.3 Perfis de Operador

Permissão: Owner (CRUD completo), Admin Grupo (CRUD escopo grupo), Admin Site (CRUD escopo site)

Campo	Tipo	Regras
`nome`*	string(100)	Único dentro do escopo
`descricao`	text	Descrição do perfil
`escopo`*	enum	`grupo`, `site`
`grupo_id`	FK	Obrigatório se escopo = `grupo`
`site_id`	FK	Obrigatório se escopo = `site`
`permissoes`*	JSON	Objeto `{ "domínio.ação": true }`
`template`	boolean	Se criado pela plataforma como template
`status`*	enum	`ativo`, `inativo`

Regras de negócio:

Perfis de grupo são visíveis/utilizáveis em todos os sites do grupo.
Perfis de site só são visíveis no site correspondente.
Não é possível inativar perfil com operadores vinculados (reatribuir antes).

4.4 Usuários (Operadores e Admins)

Permissão: Owner (CRUD completo), Admin Grupo (CRUD no escopo), Admin Site (CRUD no site)

Campo	Tipo	Regras
`nome`*	string(200)
`email`*	email	Único na plataforma, usado para login
`telefone`	string(20)	Formato brasileiro
`cpf`*	string(14)	Formato XXX.XXX.XXX-XX, validação dígito verificador, único
`papel`*	enum	`owner`, `admin_grupo`, `admin_site`, `operador`
`grupo_ids`	FK[]	Obrigatório para `admin_grupo`
`site_id`	FK	Obrigatório para `admin_site` e `operador`
`perfil_operador_id`	FK	Obrigatório para `operador`
`foto`	image	JPG/PNG, max 2MB
`status`*	enum	`ativo`, `inativo`
`ultimo_login`	datetime	Preenchido pelo sistema

Regras de negócio:

⚠️ Sem convite por email. O usuário é criado por CRUD direto e o admin define/reseta a senha — não há status convidado nem link de ativação. Ativar/inativar por ação administrativa direta.
Inativar usuário revoga sessões ativas imediatamente.
Operador sem papel/permissão atribuído não consegue operar (e não é autorizado nos canais de tempo real).

4.5 Responsáveis

⚠️ Seção reescrita (2026-08-12). A versão original descrevia um workflow de aprovação de responsável como gate de acesso — isso não existe mais. O responsável entra no app por CPF + email + confirmação por código (Fortify); o admin pré-cadastra o responsável e pode bloquear/desbloquear, mas não aprova o acesso. Ver §1.4.

Permissão: conforme responsaveis.* (ver, criar, editar, excluir, bloquear)

O admin gerencia o responsável direto: perfil 360º (dados, alunos vinculados, veículos, atividade), busca, vincular/desvincular alunos, bloquear/desbloquear e veículos inline (criar/editar/favoritar/remover, sempre no escopo do próprio responsável).

Campo	Tipo	Regras
`nome`*	string(200)
`cpf`*	string(14)	Validação dígito verificador; usado no match de onboarding (CPF + email)
`email`*	email	Usado no match de onboarding
`telefone`*	string(20)
`foto`	image	Usada para verificação na portaria (capturada no app no 1º acesso)
`tipo`*	enum	Parentesco/tipo de vínculo
`bloqueado`	boolean	Ação administrativa (bloquear/desbloquear); responsável bloqueado não acessa o app nem assina o canal de tempo real
`site_id`	FK	Vínculo N:N com escolas (o responsável pode ter mais de uma)
`alunos_vinculados`	FK[]	Vínculo com alunos (N:N); capacidades por aluno definem o que o responsável secundário pode fazer (ver App do Responsável §4.3)

Onboarding (substitui o antigo workflow de aprovação): o responsável informa CPF + email no app → o backend faz o match com o cadastro → envia código de 6 dígitos por email → confirmação via Fortify. Sem convite, sem fila de aprovação; CPF desconhecido resulta em 422 silencioso. Detalhes em Autenticação e Autorização.

4.5.1 Capacidades por aluno (não por "tipo" fixo)

O que um responsável secundário pode fazer é controlado por capacidades por aluno, resolvidas pelo backend e aplicadas no app (o titular pai/mãe tem todas implicitamente): manage_responsibles, view_temporary_permissions, create_temporary_permissions, view_activities. Ver a tabela completa em App do Responsável §4.3.

⚠️ A matriz por "tipo de responsável" (pai/resp_financeiro/resp_pedagogico) da spec original foi substituída por esse modelo de capacidades por aluno.

4.5.2 Onboarding (substitui o antigo workflow de aprovação de documentos)

⚠️ O workflow de pendente → aprovado/rejeitado/ajuste_solicitado com revisão de documentos foi removido. Não há revisão/aprovação de responsável no painel. O acesso do responsável se dá por CPF + email + código (Fortify) (ver §4.5 e Autenticação e Autorização). A única ação administrativa sobre o acesso é bloquear/desbloquear — um responsável bloqueado não acessa o app nem assina o canal de tempo real.

O que o admin ainda aprova são as filas de Pessoas Autorizadas (§4.7) e Liberações Temporárias / Saídas Antecipadas (§4.8), ambas com approve / reject / request-changes.

4.6 Alunos

Permissão: conforme alunos.*

Campo	Tipo	Regras
`nome`*	string(200)
`data_nascimento`*	date	Não pode ser futura
`foto`*	image	Obrigatória. JPG/PNG, max 5MB
`matricula`*	string(50)	Única por site
`turma_id`*	FK	Referência à turma
`turno`*	enum	`manha`, `tarde`, `integral`
`site_id`*	FK
`responsaveis_vinculados`*	FK[]	Mínimo 1 responsável aprovado
`notas_medicas`	text	Alergias, condições etc. Visível para operadores
`status`*	enum	`ativo`, `inativo`, `transferido`

Regras de negócio:

Aluno deve ter pelo menos 1 responsável com status aprovado para estar ativo.
Transferência entre sites do mesmo grupo preserva histórico; entre grupos cria novo registro.
Foto é exibida na interface "Estou Chegando" para confirmação visual.

4.7 Pessoas Autorizadas

Permissão: conforme autorizados.*

Campo	Tipo	Regras
`nome`*	string(200)
`cpf`*	string(14)	Validação dígito verificador
`telefone`*	string(20)
`email`	email
`foto`*	image	Obrigatória. JPG/PNG, max 5MB
`tipo_autorizacao`*	enum	`permanente`, `temporaria`
`validade_inicio`	date	Obrigatório se tipo = `temporaria`
`validade_fim`	date	Obrigatório se tipo = `temporaria`
`horario_inicio`	time	Intervalo de horário permitido (opcional)
`horario_fim`	time
`alunos_vinculados`*	FK[]	Alunos que esta pessoa pode retirar
`responsavel_autorizador_id`*	FK	Responsável que criou a autorização
`status`*	enum	`pendente`, `aprovado`, `rejeitado`, `expirado`, `cancelado`, `bloqueado`, `suspenso`
`motivo_bloqueio`	text	Preenchido ao bloquear/suspender
`site_id`*	FK

Diferenças entre ações administrativas:

Ação	Efeito	Reversível?
Aprovar	Pessoa pode retirar alunos vinculados	—
Rejeitar	Autorização negada. Pode ser recriada pelo responsável	—
Cancelar	Autorização encerrada definitivamente	Não (nova autorização necessária)
Bloquear	Impedimento administrativo. Registro preservado	Sim (desbloquear)
Suspender	Impedimento temporário (ex: investigação). Registro preservado	Sim (reativar)

Regras de negócio:

Autorizações temporárias expiram automaticamente (cron/scheduled job atualiza status para expirado).
Pessoa bloqueada/suspensa dispara alerta se tentar retirar aluno.
(P1) Compartilhamento: responsável pode compartilhar autorização via link/convite no app.

4.8 Liberação Temporária de Saída

Permissão: conforme liberacoes_temporarias.*

Campo	Tipo	Regras
`aluno_id`*	FK
`responsavel_id`*	FK	Responsável solicitante (deve estar `aprovado`)
`motivo`*	text	Justificativa
`data`*	date	Não pode ser passada
`hora_inicio`*	time
`hora_fim`*	time	Deve ser > `hora_inicio`
`modo_saida`*	enum	`sozinho`, `acompanhado`
`acompanhante_nome`	string(200)	Obrigatório se modo = `acompanhado`
`acompanhante_cpf`	string(14)	Obrigatório se modo = `acompanhado`
`acompanhante_foto`	image	Recomendado se modo = `acompanhado`
`status`*	enum	`pendente`, `aprovado`, `rejeitado`, `utilizado`, `expirado`, `cancelado`
`aprovado_por`	FK	Usuário admin/operador que aprovou
`site_id`*	FK

Regras de negócio:

Responsável solicita via app; admin/operador aprova ou rejeita no painel.
Status muda para utilizado quando a saída é efetivamente registrada.
Status muda para expirado se data + hora_fim passou sem uso.
Modo sozinho é um diferencial competitivo — permite saída sem acompanhante com registro formal.

4.9 Turmas

Permissão: conforme turmas.*

Campo	Tipo	Regras
`nome`*	string(100)	Único por site + ano_letivo
`serie`*	string(50)	Ex: "1º Ano", "Infantil 3"
`turno`*	enum	`manha`, `tarde`, `integral`
`site_id`*	FK
`ano_letivo`*	int	Ex: 2026
`professor`	string(200)	Nome do professor responsável
`sala`	string(50)	Identificação da sala

Regras de negócio:

Turmas são versionadas por ano_letivo. Ao iniciar novo ano, turmas podem ser clonadas.
Não é possível excluir turma com alunos vinculados (reatribuir antes).

4.10 Agenda

Permissão: conforme agenda.*

Campo	Tipo	Regras
`titulo`*	string(200)
`descricao`	text
`data`*	date
`horario`	time
`turmas_aplicaveis`	FK[]	Se vazio, aplica a todas as turmas do site
`tipo`*	enum	`evento`, `feriado`, `reuniao`, `excursao`, `outro`
`afeta_retirada`*	boolean	Default: false
`horario_retirada_alterado`	time	Obrigatório se `afeta_retirada` = true
`site_id`*	FK

Regras de negócio:

Quando afeta_retirada = true, o sistema ajusta automaticamente a janela de retirada para a data/turmas afetadas.
Notificação push enviada aos responsáveis das turmas afetadas ao criar/editar evento que afeta retirada.

4.11 Comunicados

Permissão: conforme comunicados.*

Campo	Tipo	Regras
`titulo`*	string(200)
`corpo`*	rich text	Suporta formatação, links, imagens inline
`publico_alvo`*	enum	`todos`, `turmas_especificas`, `turnos_especificos`
`turmas_ids`	FK[]	Obrigatório se público = `turmas_especificas`
`turnos`	enum[]	Obrigatório se público = `turnos_especificos`
`prioridade`*	enum	`normal`, `alta`, `urgente`
`enviar_push`*	boolean	Default: true
`anexo`	file	PDF/JPG/PNG, max 10MB
`site_id`*	FK
`autor_id`*	FK	Preenchido pelo sistema

Regras de negócio:

Prioridade urgente envia push mesmo em horário silencioso.
Comunicados são somente leitura após publicação (editar cria nova versão).

4.12 Veículos do Responsável (P1)

Permissão: responsável gerencia no app; admin pode visualizar no painel.

Campo	Tipo	Regras
`placa`*	string(10)	Formato Mercosul ou antigo
`modelo`*	string(100)
`cor`*	string(50)
`responsavel_id`*	FK
`favorito`	boolean	Default: false. Apenas 1 favorito por responsável

Uso operacional:

Ao acionar "Estou Chegando", responsável seleciona veículo e modo de transporte (caminhando / dirigindo).
Card na interface do operador exibe: veículo (modelo, cor, placa) e modo de transporte.
Facilita identificação visual do responsável na portaria.

5. Painel de Monitoramento em Tempo Real

5.1 State Machine — Estados do Aluno no Fluxo de Retirada

┌──────────────┐    Entrada      ┌───────────┐   Pai aciona    ┌────────────────────┐
│ fora_da_escola│───(hardware/QR)──►│ na_escola │──"Estou Chegando"──►│ aguardando_retirada│
└──────────────┘                 └───────────┘                 └─────────┬──────────┘
       ▲                                                                │
       │                                                     Operador "Preparar"
       │                                                                │
       │                                                                ▼
       │                          ┌──────────┐   Operador     ┌──────────────────┐
       └───────Saída registrada───│ retirado │◄──"Confirmar"──│ sendo_preparado   │
                                  └──────────┘                └───────┬──────────┘
                                       ▲                              │
                                       │                   Operador "Pronto"
                                       │                              │
                                       │                              ▼
                                       │                      ┌───────────┐
                                       └──────────────────────│  pronto   │
                                                              └───────────┘

Status	Significado	Acionado por
`fora_da_escola`	Aluno fora da escola	Estado padrão / após retirada confirmada
`na_escola`	Aluno presente na escola	Evento de entrada (hardware de controle de acesso / QR code)
`aguardando_retirada`	Responsável sinalizou "Estou Chegando"	Ação do responsável no app móvel
`sendo_preparado`	Operador está localizando/preparando o aluno	Ação do operador na interface
`pronto`	Aluno no ponto de retirada, aguardando responsável	Ação do operador
`retirado`	Aluno foi retirado da escola	Evento de saída (hardware/QR/confirmação do operador)

5.2 Layout do Painel (Kanban-style)

Barra de Resumo (topo):

Total de alunos do site
Presentes (na_escola + demais estados ativos)
Na fila (aguardando_retirada + sendo_preparado + pronto)
Retirados hoje
Alertas ativos (badge com contagem, cor #ef4444)

Colunas:

Coluna	Conteúdo do Card	Ordenação
Estou Chegando	Foto do responsável, nome, aluno(s), turma(s), timestamp, veículo (P1)	Mais antigo primeiro (FIFO)
Sendo Preparado	Foto do aluno, nome, turma, operador responsável	Mais antigo primeiro
Pronto para Retirada	Foto do aluno, nome, tempo de espera (timer), turma	Mais antigo primeiro
Retirado	Foto do aluno, nome, horário de retirada, retirado por	Mais recente primeiro (últimas N)

Filtros: turma, turno, busca por nome do aluno ou responsável.

Atualização: WebSocket/SSE — dados refletem em tempo real para todos os operadores conectados.

5.3 Alertas em Tempo Real

Nível	Alerta	Descrição
Crítico (`#ef4444`)	Retirada não autorizada	Pessoa sem autorização válida tentou retirar aluno
Alto (`#ef4444`)	Autorização expirada	Pessoa com autorização temporária vencida tentou retirar
Médio (`#f59e0b`)	Aluno não retirado	Aluno ainda na escola após encerramento da janela de retirada
Baixo (`#f59e0b`)	Timeout "Estou Chegando"	Responsável sinalizou mas não chegou dentro do tempo configurável

Comportamento:

Alertas críticos: notificação sonora + visual (banner vermelho) + push para Admin Site.
Alertas médios/altos: notificação visual no painel + badge.
Alertas baixos: apenas badge + log.

6. Interface Operacional "Estou Chegando" (Tablet/Mobile)

6.1 Contexto

Interface dedicada para uso na portaria, otimizada para tablet ou celular. Distribuída como PWA (Progressive Web App) para instalação rápida sem app store. Separada do painel admin — acesso com login do operador.

6.2 Fluxo Operacional Completo

1. Responsável aciona "Estou Chegando" no app
   └── Seleciona aluno(s) + veículo (P1) + modo transporte (P1)

2. Card aparece na tela do operador
   └── Foto do responsável, nome, aluno(s), turma(s), timestamp, veículo

3. Operador toca "Preparar Aluno"
   └── Status → sendo_preparado
   └── Comunicação interna para buscar aluno na sala

4. Aluno chega na portaria
   └── Operador toca "Aluno Pronto"
   └── Status → pronto

5. Responsável chega na portaria
   └── Operador verifica identidade (comparação visual com foto / QR code / biometria)
   └── Operador toca "Confirmar Retirada"
   └── Status → retirado

6. Registro de auditoria criado automaticamente
   └── Quem retirou, quem confirmou, horário, método de verificação

6.3 Filtros do Operador

Operador vê todos os alunos da fila por padrão (sem restrição de turma/turno).
Filtro manual disponível por turma ou turno conforme necessidade.
Sem atribuição fixa de turma/turno ao operador — flexibilidade total.

6.4 Cenários Especiais

Cenário	Comportamento
Múltiplos filhos	Mesmo card agrupa todos os filhos. Operador confirma retirada de todos de uma vez ou individualmente.
Pessoa autorizada (não responsável)	Card exibe foto e dados da pessoa autorizada + tipo e validade da autorização.
Liberação temporária "sozinho"	Card indica "saída solo". Sem verificação de acompanhante. Operador registra saída diretamente.
Pessoa não autorizada	Alerta vermelho (`#ef4444`). Retirada bloqueada. Registro no log de auditoria.
Walk-in sem "Estou Chegando"	Operador faz busca manual pelo nome do aluno → verifica autorização do acompanhante → processa retirada normalmente.
Responsável com status `bloqueado`	Alerta vermelho. Retirada bloqueada. Admin deve intervir.

6.5 Design

Touch targets: mínimo 48×48px para botões de ação.
Notificações: som + vibração ao receber novo card "Estou Chegando".
Paleta (⚠️ aspiracional — a paleta abaixo é da spec original; não há um design system publicado. A marca real do produto usa navy #043471 + azul #0277F4, ver o styleguide do backend e o App do Responsável §8):
- #ff781e (Brand Orange) — ações primárias, botão "Preparar"
- #22c55e (Safety Green) — confirmação, "Retirada Confirmada"
- #ef4444 (Alert Red) — bloqueio, alertas críticos
- #f59e0b (Alert Amber) — warnings, pendências
Tipografia: Inter, body 14px/400, labels 12px/500.
Modo escuro: suporte planejado (P1), importante para uso externo/portaria.

7. Funcionalidades Complementares

7.1 Logs de Auditoria

Permissão: audit_logs.ver

Registro imutável de todas as ações no sistema.

Campo do Log	Descrição
`timestamp`	UTC
`usuario_id`	Quem realizou a ação
`acao`	`criar`, `editar`, `excluir`, `aprovar`, `rejeitar`, `login`, `retirada`, etc.
`entidade`	Tipo da entidade afetada
`entidade_id`	ID da entidade
`dados_anteriores`	Snapshot antes da alteração (JSON)
`dados_novos`	Snapshot após a alteração (JSON)
`ip`	Endereço IP
`user_agent`	Navegador/dispositivo

Interface:

Viewer com filtros: período, usuário, tipo de ação, entidade.
Busca por texto nos dados.
Logs são imutáveis — não podem ser editados ou excluídos.
Exportação jurídica: CSV/PDF com hash de integridade (SHA-256) para validade legal.

7.2 Relatórios de Compliance (P1)

Relatórios exigidos por ECA (Estatuto da Criança e do Adolescente) e LGPD:

Frequência por período: presença/ausência por aluno, turma, turno.
Retiradas por período: quem retirou, horário, método de verificação.
Autorizações ativas: lista de pessoas autorizadas por aluno.
Conformidade legal: relatório consolidado para apresentação a órgãos competentes.

7.3 Dashboard Analítico (P1)

Tempo médio de retirada (do "Estou Chegando" à confirmação).
Horários de pico por janela de retirada.
Estatísticas por turma (tempo médio, volume).
(P2) Relatórios consolidados por grupo escolar.

7.4 Importação / Exportação

Importação (P0):

CSV para alunos e responsáveis — essencial para onboarding de escolas.
Template CSV fornecido pelo sistema com cabeçalhos e exemplos.
Validação prévia: exibe erros antes de confirmar importação.
API de importação para integração com sistemas existentes.

Exportação:

CSV/PDF de listas (alunos, responsáveis, autorizados, turmas).
CSV/PDF de logs e relatórios.
Exportação de dados pessoais para atendimento LGPD (ver 7.7).

7.5 Configurações do Site

Permissão: configuracoes_site.ver, configuracoes_site.editar

Geofencing: mapa interativo para definir centro e raio.
Janelas de retirada: CRUD conforme seção 4.2.1.
Modo pickup: hardware, QR code ou ambos.
Branding: logo, nome exibido, cores customizadas (P1).
Timeout "Estou Chegando": tempo em minutos para expirar sinalização (default: 30min).
Configurações herdadas do grupo: indicador visual mostra quais configs usam o padrão do grupo e quais têm override local.

7.6 Gestão de Notificações

Configurar quais eventos disparam push (por tipo de responsável).
Horários silenciosos (não enviar push fora do período configurado, exceto urgente).
Busca e filtro no histórico de notificações enviadas.

7.7 LGPD — Solicitações de Dados (P1)

Painel para gerenciar DSARs (Data Subject Access Requests):

Responsável solicita via app ("Quero meus dados").
Admin visualiza solicitações pendentes.
Ações: exportar dados pessoais (JSON/PDF) ou anonimizar registros.
Prazo legal: 15 dias para atendimento (timer visual no painel).
Log da solicitação e atendimento para compliance.

7.8 Webhooks (P1)

Configuração de URLs de callback para eventos: entrada, saida, estou_chegando, autorizacao_criada, autorizacao_aprovada.
Retry com backoff exponencial (3 tentativas).
Log de entregas com status (sucesso/falha).
Permite integração com sistemas externos (ERPs, ferramentas de BI).

7.9 Painel Consolidado do Grupo (P1)

Dashboard agregado para Admin Grupo Escolar:

Visão geral de todos os sites: alunos presentes, retiradas em andamento, alertas.
Comparativos entre sites (tempo médio de retirada, volume).
Drill-down para painel individual de cada site.

8. Módulos Futuros (P2 — Placeholders)

Módulos planejados para fases futuras. Não implementados no MVP.

Módulo	Descrição	Referência
Gestão de Visitantes	Cadastro, motivo da visita, check-in/check-out, crachá digital	—
Canal de Comunicação Escola-Família	Messaging bidirecional entre escola e responsáveis	ClassApp, Agenda Edu
Feed de Notícias da Escola	Publicação de conteúdo institucional, fotos, eventos	—
Controle de Frequência Automatizado	Frequência escolar a partir de eventos de entrada/saída	Secullum
Integração ERPs Educacionais	Sincronização com Sponte, WPensar, iScholar	—
API Aberta para Terceiros	Documentação pública, gestão de credenciais, rate limiting	—

9. Navegação do Painel Web

Dashboard
Monitoramento
─────────────────────
Alunos
Turmas
Responsáveis
Pessoas Autorizadas
Liberações Temporárias
─────────────────────
Agenda
Comunicados
─────────────────────
Usuários & Operadores
Perfis de Operador
─────────────────────
Relatórios
Logs de Auditoria
─────────────────────
Configurações

9.2 Adições por Papel

Papel	Adições na navegação
Admin Grupo	Seletor de site no header + item "Visão do Grupo" no dashboard + "Grupos Escolares" na sidebar
Owner	Seletor de grupo no header + "Configurações da Plataforma" + "Grupos Escolares" (CRUD completo)

10. Regras Transversais

10.1 Integridade de Dados

Soft delete em todas as entidades — campo deleted_at. Registros excluídos são ocultados da UI mas preservados para auditoria.
Timestamps armazenados em UTC. Exibição convertida para o timezone do site.
Concorrência: WebSocket/SSE para sincronização em tempo real entre múltiplos operadores simultâneos.

10.2 LGPD e Compliance

Exportação de dados pessoais sob demanda (DSAR — seção 7.7).
Anonimização de dados quando solicitado.
Consentimento explícito coletado no cadastro do responsável.
Logs de auditoria imutáveis com certificação de integridade para fins jurídicos.

10.3 Segurança

Status ativo/inativo para usuários — nunca deletar, preservar trilha de auditoria.
Sessões invalidadas imediatamente ao inativar usuário.
Autenticação: email + senha com MFA (P1).
Rate limiting em endpoints de autenticação.

10.4 Performance

Painel de monitoramento: latência máxima de 2s para atualização de status.
Importação CSV: processamento assíncrono com feedback de progresso para arquivos > 100 registros.
Paginação em todas as listagens (default: 25 itens/página).

Apêndice A — Referência Cruzada com o Backlog

ℹ️ O antigo repositório de ideias de funcionalidades foi movido para o backlog de produto. A tabela abaixo cruza as seções deste doc com o backlog.

Seção deste doc	Funcionalidades relacionadas no backlog de produto
3. Permissões	5.3 Perfis e permissões
4.5 Responsáveis	2.1–2.5 Cadastro e aprovação
4.7 Autorizados	3.1–3.5 Autorização de terceiros
4.8 Liberações	4.1–4.4 Liberação temporária
5. Monitoramento	5.1 Dashboard, 5.5 Alertas
6. Estou Chegando	1.1–1.6 Fluxo de retirada
7.1 Audit Logs	5.6 Logs de auditoria
7.2 Compliance	5.7 Relatórios
7.4 Import/Export	5.4 Importação

Apêndice B — Ver também

Superfícies irmãs: App do Responsável · Monitor de Portaria · Painel Público
Arquitetura: Ciclo de Retirada · Tempo Real · Autenticação e Autorização · Modelo de Domínio
Integração de controle de acesso: Integração (controle de acesso)
Operação: Runbook de Tempo Real
Visão geral: Visão de Produto · Personas e Superfícies · Glossário

Painel Administrativo ionCLASS — Especificação Funcional ​

1. Introdução e Escopo ​

1.1 Propósito ​

1.2 Componentes do Ecossistema ​

1.3 Delimitação ​

1.4 Reconciliação com a implementação (2026-08-12) ​

O que mudou desde a spec original ​

Capacidades implementadas (rotas reais) ​

Tempo real e escopo ​

2. Arquitetura Multi-site e Grupos Escolares ​

2.1 Hierarquia ​

2.2 Regras Estruturais ​

2.3 Seletor de Contexto ​

3. Modelo de Permissões e Controle de Acesso ​

3.1 Hierarquia de Papéis ​

3.2 Sistema de Perfis de Operador ​

3.3 Permissões Granulares por Domínio ​

3.4 Exemplos de Perfis Pré-configurados ​

4. CRUDs — Especificação Detalhada ​

4.1 Grupos Escolares ​

4.2 Escolas (Sites) ​

4.2.1 Janelas de Retirada ​

4.3 Perfis de Operador ​

4.4 Usuários (Operadores e Admins) ​

4.5 Responsáveis ​

4.5.1 Capacidades por aluno (não por "tipo" fixo) ​

4.5.2 Onboarding (substitui o antigo workflow de aprovação de documentos) ​

4.6 Alunos ​

4.7 Pessoas Autorizadas ​

4.8 Liberação Temporária de Saída ​

4.9 Turmas ​

4.10 Agenda ​

4.11 Comunicados ​

4.12 Veículos do Responsável (P1) ​

5. Painel de Monitoramento em Tempo Real ​

5.1 State Machine — Estados do Aluno no Fluxo de Retirada ​

5.2 Layout do Painel (Kanban-style) ​

5.3 Alertas em Tempo Real ​

6. Interface Operacional "Estou Chegando" (Tablet/Mobile) ​

6.1 Contexto ​

6.2 Fluxo Operacional Completo ​

6.3 Filtros do Operador ​

6.4 Cenários Especiais ​

6.5 Design ​

7. Funcionalidades Complementares ​

7.1 Logs de Auditoria ​

7.2 Relatórios de Compliance (P1) ​

7.3 Dashboard Analítico (P1) ​

7.4 Importação / Exportação ​

7.5 Configurações do Site ​

7.6 Gestão de Notificações ​

7.7 LGPD — Solicitações de Dados (P1) ​

7.8 Webhooks (P1) ​

7.9 Painel Consolidado do Grupo (P1) ​

8. Módulos Futuros (P2 — Placeholders) ​

9. Navegação do Painel Web ​

9.1 Sidebar — Admin Site ​

9.2 Adições por Papel ​

10. Regras Transversais ​

10.1 Integridade de Dados ​

10.2 LGPD e Compliance ​

10.3 Segurança ​

10.4 Performance ​

Apêndice A — Referência Cruzada com o Backlog ​

Apêndice B — Ver também ​

Painel Administrativo ionCLASS — Especificação Funcional

1. Introdução e Escopo

1.1 Propósito

1.2 Componentes do Ecossistema

1.3 Delimitação

1.4 Reconciliação com a implementação (2026-08-12)

O que mudou desde a spec original

Capacidades implementadas (rotas reais)

Tempo real e escopo

2. Arquitetura Multi-site e Grupos Escolares

2.1 Hierarquia

2.2 Regras Estruturais

2.3 Seletor de Contexto

3. Modelo de Permissões e Controle de Acesso

3.1 Hierarquia de Papéis

3.2 Sistema de Perfis de Operador

3.3 Permissões Granulares por Domínio

3.4 Exemplos de Perfis Pré-configurados

4. CRUDs — Especificação Detalhada

4.1 Grupos Escolares

4.2 Escolas (Sites)

4.2.1 Janelas de Retirada

4.3 Perfis de Operador

4.4 Usuários (Operadores e Admins)

4.5 Responsáveis

4.5.1 Capacidades por aluno (não por "tipo" fixo)

4.5.2 Onboarding (substitui o antigo workflow de aprovação de documentos)

4.6 Alunos

4.7 Pessoas Autorizadas

4.8 Liberação Temporária de Saída

4.9 Turmas

4.10 Agenda

4.11 Comunicados

4.12 Veículos do Responsável (P1)

5. Painel de Monitoramento em Tempo Real

5.1 State Machine — Estados do Aluno no Fluxo de Retirada

5.2 Layout do Painel (Kanban-style)

5.3 Alertas em Tempo Real

6. Interface Operacional "Estou Chegando" (Tablet/Mobile)

6.1 Contexto

6.2 Fluxo Operacional Completo

6.3 Filtros do Operador

6.4 Cenários Especiais

6.5 Design

7. Funcionalidades Complementares

7.1 Logs de Auditoria

7.2 Relatórios de Compliance (P1)

7.3 Dashboard Analítico (P1)

7.4 Importação / Exportação

7.5 Configurações do Site

7.6 Gestão de Notificações

7.7 LGPD — Solicitações de Dados (P1)

7.8 Webhooks (P1)

7.9 Painel Consolidado do Grupo (P1)

8. Módulos Futuros (P2 — Placeholders)

9. Navegação do Painel Web

9.1 Sidebar — Admin Site

9.2 Adições por Papel

10. Regras Transversais

10.1 Integridade de Dados

10.2 LGPD e Compliance

10.3 Segurança

10.4 Performance

Apêndice A — Referência Cruzada com o Backlog

Apêndice B — Ver também