Documento Norteador: Acesso — Sistema Integrado de Controle de Fluxo

Acesso permitido, identidade preservada.

1. Escopo, Objetivos e Governança

1.1 Objetivos do Sistema

O objetivo principal é gerenciar e monitorar o fluxo de entrada e saída de alunos, servidores e visitantes no campus com controle de Fluxo, registrando acessos de forma segura, disponibilizar no dashboard o número exato de pessoas presentes em cada endereço/unidade do campus sem expor dados nominais e garantir que o sistema funcione estritamente como controle de portaria (segurança), e não como ponto eletrônico de servidores ou fiscalização punitiva de assiduidade estudantil.

1.2 Diretrizes de Governança, LGPD e ECA Digital

Por se tratar de uma instituição de ensino federal que atende a menores de idade, o cuidado com os dados precisa ser rigoroso. ECA (Estatuto da Criança e do Adolescente) Digital garante que os dados de menores não podem ser expostos, comercializados ou utilizados para qualquer fim que não seja a segurança imediata e a comunicação interna com os responsáveis legais. O consentimento para o tratamento de dados de menores deve ser coletado explicitamente dos pais/responsáveis no ato da matrícula. A Lei Geral de Proteção de Dados tem o princípio da minimização que dita a regra para salvar apenas o estritamente necessário. Não coletaremos dados sensíveis desnecessários no banco de dados de tráfego.

Anonimização e Desvinculação Física: O controle de fluxo e presença é feito de forma 100% desvinculada da identidade nominal do usuário. O sistema não armazena qual pessoa está no prédio. A presença ativa é gerenciada de forma pseudônima através de uma tabela temporária (PresencaAtiva) de tokens de sentido único (hash SHA-256 gerado com base no UID do cartão e um Salt rotativo diário). O contador de presentes nas unidades baseia-se puramente em incrementos e decrementos agregados em tabelas e no agrupamento estatístico anônimo desses tokens ativos.

2. Arquitetura de Cartões e Provisionamento

2.1 Estrutura do Cartão (Mifare Classic 1K) e Resiliência Criptográfica

Os cartões Mifare Classic 1K estruturam-se em 16 setores independentes, cada um protegido por chaves de acesso próprias. Para mitigar o risco de clonagem simples através da mera cópia do número de série do cartão, o sistema não adotará o UID de fábrica como único vetor de validação.

Setor 0 (Bloqueado): Reservado pelo fabricante para armazenamento do UID (Identificador Único) e dados de fabricação. Leitura pública, porém imutável.

Setor 1 (Blocos 4 e 5 - Customizado): Destinado ao armazenamento do UUID_CAMPUS em formato hexadecimal. O acesso a este setor exige autenticação via Chave A modificada (substituindo o padrão de fábrica FFFFFFFFFFFF por uma assinatura criptográfica exclusiva do IF).

Setor 2 (NDEF Público): Contém o mesmo UUID_CAMPUS gravado em formato de registro NDEF público (sem chave de acesso). Este setor é lido pelo Modo Catraca PWA (Android/Web NFC), que não tem capacidade de autenticar setores protegidos.

A substituição da Chave A de fábrica pela assinatura criptográfica da instituição no Setor 1 do Mifare Classic é uma medida eficaz contra a vasta maioria das clonagens casuais (copiadores simples de UID). É reconhecido o fato de que a tecnologia Mifare Classic apresenta defasagem de segurança (Crypto1) perante ataques sofisticados, sendo o modelo de proteção por UUID uma balança ideal de custo-benefício para a segurança escolar atual.

Mecanismo de Validação Combinada: Ao aproximar o cartão, o leitor extrai o UID do Setor 0 e autentica-se no Setor 1 usando a chave privada da instituição para descriptografar o token interno, validando os dois dados.

2.2 Evolução do Parque de Cartões (Future-Proofing e Parque Híbrido)

Embora o Mifare Classic 1K atenda à demanda inicial com as travas citadas, o planejamento de futuras aquisições de cartões deve adotar a tecnologia MIFARE DESFire (EV2 ou EV3). Estes cartões utilizam criptografia de nível bancário (AES-128), tornando a extração de chaves e clonagem matematicamente inviáveis.

A transição de longo prazo ocorrerá de forma híbrida e transparente para o sistema web (que depende apenas do recebimento lógico do UUID_CAMPUS). Para garantir a compatibilidade dupla na portaria:

Hardware: Adoção do módulo leitor NFC PN532 (em detrimento do RC522), dada a sua compatibilidade com o protocolo ISO 14443-4 (exigido pelos cartões DESFire).

Firmware (ESP32): O código da catraca/leitor utilizará a verificação do byte SAK para identificar o modelo do cartão aproximado no instante da leitura. Caso identifique um Classic, invocará a rotina de autenticação padrão; caso identifique um DESFire, invocará a leitura via chaves AES, permitindo que alunos veteranos e calouros acessem o campus simultaneamente independentemente do cartão físico.

2.3 Emissão e Gravação de Cartões (Provisionamento)

O uso de aplicativos mobile (como NFC Tools PRO) é válido estritamente para a fase de testes e Prova de Conceito (PoC). Para a operação real escolar (emissão em massa), o processo manual é insustentável, sujeito a erros humanos e configura risco de exposição das chaves criptográficas em aplicativos de terceiros. Para a produção, o sistema contará com uma "Estação de Gravação" dedicada na secretaria:

Opção A - Gravador USB de Mesa (ACR122U): Um leitor NFC conectado via USB ao terminal de atendimento. Integrado ao sistema web, automatiza a formatação, gravação do uuid_campus e substituição da Chave A em etapa única, sem intervenção manual.

Opção B - Emissor IoT (ESP32 + PN532 - Recomendado): Um dispositivo dedicado conectado ao Wi-Fi. Ao registrar um aluno no Next.js, o backend sinaliza o Emissor. O atendente aproxima o cartão virgem; o ESP32 injeta o UUID e as chaves de forma cega, rápida e segura. Garante a padronização do hardware de leitura/gravação da instituição e facilita a futura transição para o padrão DESFire.

3. Dinâmica de Operação da Portaria (Offline-First) e Hardware

3.1 Dinâmica de Operação Baseada em Desempenho e Dispositivos

Para evitar a formação de filas nos horários de pico da instituição, o sistema adotará o princípio de validação descentralizada e envio assíncrono em lote. A liberação do fluxo ocorrerá de forma imediata na ponta (hardware), sem depender de consultas em tempo real ao servidor web através da rede Wi-Fi. Existem dois formatos de operação:

Opção A: Dispositivo Dedicado (ESP32 + RC522/PN532) - Padrão para portarias

Fluxo de Entrada Ultra Rápido: Ao aproximar o cartão, o ESP32 autentica o setor criptográfico localmente. Se o UUID_CAMPUS for válido e não constar na lista local de bloqueios, sinaliza a liberação imediatamente (< 200 ms).

Armazenamento e Envio em Lote (Buffer Local): O acesso é gravado na memória física do dispositivo. A cada 60 segundos, o ESP32 envia o lote de dados para a API e esvazia o buffer.

Sincronização de Bloqueios: A cada 60 segundos, o ESP32 consome a API para atualizar sua lista interna de cartões revogados.

Resiliência a Quedas de Rede: Caso o Wi-Fi caia, continua liberando as entradas baseado na validação local, acumulando os registros por horas ou dias, e descarregando em lote assim que a rede voltar.

Opção B: Coleta Móvel (Android / PWA) — Contingência e portarias secundárias

Implementado via Web NFC API (Chrome para Android 89+). Funciona como um PWA instalável no celular. O dispositivo Android é cadastrado no sistema como qualquer catraca, recebendo sua própria API Key.

Leitura NFC via NDEFReader: A API NDEFReader.scan() captura registros NDEF públicos do Setor 2 do cartão. Extrai o UUID_CAMPUS do registro textual.

Feedback Imediato (< 200ms): Som beep + vibração + mudança de cor de tela ao ler o cartão, antes mesmo da sincronização.

Fila Offline no IndexedDB: Cada leitura é persistida localmente no banco do navegador. Se não houver internet, os acessos acumulam e são enviados quando a rede retornar.

Sincronização Automática: A cada 60 segundos, drena a fila do IndexedDB via POST /api/hardware/sync com a API Key.

Mesmo Endpoint B2B: O PWA utiliza exatamente o mesmo endpoint do ESP32 — o servidor processa os lotes de forma idêntica.

Limitação de Segurança: A Web NFC API não permite autenticar setores protegidos por Chave A. O PWA lê apenas NDEF público, sem validação criptográfica. Um cartão com cópia do NDEF seria aceito. Por isso, é restrito a cenários de contingência com agente presente.

3.2 Resiliência de Hardware (RTC e Queda de Energia)

Para que o armazenamento offline funcione perfeitamente e mantenha a integridade cronológica da operação física, o ESP32 necessita de um módulo RTC de hardware com bateria própria (ex: módulo DS3231). Isso garante que, em caso de queda conjunta de energia elétrica e da rede Wi-Fi, o dispositivo continue registrando os acessos com o horário real (evitando a dependência do servidor NTP).

3.3 Riscos Físicos e Limites de Borda (Blind Spots da Operação Offline)

Para garantir que o sistema não possua falhas lógicas em cenários adversos severos, implementam-se as seguintes travas na operação física:

Flash Encryption (Proteção Contra Roubo): O firmware do ESP32 deve ser compilado com a encriptação de memória ativada. Isso impede que um invasor que furte o dispositivo físico consiga extrair a Chave A do Mifare ou as API Keys por meio de um dump de memória (engenharia reversa).

TTL da Lista de Revogação: Se o ESP32 operar offline por um período contínuo superior a um limite (ex: 24h), ele acionará um alerta visual/sonoro específico ("Alerta de Desatualização"). Isso avisa os vigias de que a lista de cartões revogados local pode estar defasada.

Fila Circular (Ring Buffer Overflow): O armazenamento de contingência (SPIFFS/MicroSD) operará com limite de segurança. Ao atingir 95% do armazenamento sem conseguir despachar o lote, adotará o método "First-In-First-Out com descarte", apagando os acessos mais antigos para gravar os novos, evitando travamento por Memory Overflow.

4. Arquitetura de Software, API e Banco de Dados

4.1 Stack Tecnológica e Processamento Assíncrono (Bulk Inserts)

A stack escolhida (Next.js, NextAuth, Node e Postgres) é ideal para uma aplicação escalável e segura.

A dinâmica "Offline-First" do hardware exige que o backend e o banco de dados sejam projetados para processar requisições em lote (bulk inserts). A API receberá matrizes de dados (ex: 40 registros de uma vez a cada 60 segundos). O sistema processará essa lista transacionalmente, inserindo os históricos de acesso com seus timestamps originais do RTC e disparando uma única rotina de atualização no painel de ocupação anonimizada, reduzindo drasticamente o consumo do servidor do campus.

4.2 Segurança da API (Endpoint B2B)

A comunicação de envio assíncrono em lote dos hardwares/PWAs para a API em Next.js deve utilizar autenticação obrigatória através de API Keys vinculadas ao respectivo "Controle de Acesso" (Tenant). Isso garante que conexões não autorizadas sejam rejeitadas e permite ao servidor rotear os dados físicos exatamente para o banco de dados lógico do campus correspondente.

4.3 Modelagem de Dados (PostgreSQL)

O segredo para cumprir a LGPD e a regra do "não-ponto" está em separar o registro de acessos brutos da identidade em consultas comuns de dashboard. Estrutura recomendada:

Tabela controles_acesso (Tenant): id (PK), nome.

Tabela unidades_campus: id (PK), controleacessoid (FK), nome_endereco.

Tabela membros_controle: id (PK), controleacessoid (FK), user_id (FK → User NextAuth), papel (owner, admin, viewer).

Tabelas de Apoio: categorias (Ex: Estudantes, Servidores) e grupos_refeicao (Ex: Lanche Manhã, Almoço, Lanche Tarde, Jantar). Cadastros dinâmicos gerenciados pelo administrador por Tenant.

Tabela usuarios: id (PK), controleacessoid (FK), uuidcampus (UNIQUE), categoriaid (FK), _GrupoRefeicaoToUsuarioNfc (tabela de junção many-to-many), status_cartao. Dados nominais restritos a gestores. (A coluna unidadeAtualId foi descontinuada e removida logicamente para evitar qualquer rastreamento retrospectivo).

Tabela dispositivos_hardware: id (PK), controleacessoid (FK), unidadeid (FK), nomeportaria, tipo_dispositivo ("hardware" ou "pwa"), apikeyhash (SHA-256 da API Key, nunca o valor plain), ultimo_sincronismo (timestamp).

Tabela historico_acessos: id (PK), controleacessoid (FK), uuidcampus, sentido (entrada/saida), timestampacesso (do RTC — não do servidor), dispositivo_id (FK). Gravação em lote, não usada em dashboard público e desassociada de dados nominais.

Tabela metrica_ocupacao: id (PK), unidadeid (FK), gruporefeicaoid (nullable FK), totalpresentes. Índice único em (unidadeid, gruporefeicao_id). Monitora ocupação geral e por grupos de refeição. As contagens de presentes por categoria são computadas de forma agregada a partir da tabela PresencaAtiva.

Tabela PresencaAtiva (Tabela de Presença Pseudônima): id (PK), controleacessoid (FK), tokenpresenca (UNIQUE - hash SHA-256 do UID do cartão com salt dinâmico diário), unidadeid (FK), categoriaid (FK, nullable), criadoem (timestamp). Utilizada para validação de trânsito (antipassback e sentido) sem expor identidades.

Tabela config_relatorio: id (PK), unidadeid (FK), gruporefeicaoid (nullable FK), emailsdestino (array), diassemana (array int), horariodisparo (HH:MM), ativo (bool).

4.4 Regras de Negócio e Consistência de Contagem (Tratamento de Omissões)

Para mitigar inconsistências geradas por usuários que omitem o registro na saída ou entram aglomerados, o sistema aplicará:

Sincronização Cronológica de Lotes: O processamento dos "Bulk Inserts" oriundos de múltiplas catracas que voltaram online simultaneamente deve reordenar os dados pelo timestamp_acesso original (RTC) antes de aplicar as demais lógicas, evitando falsas inconsistências geradas por atrasos de rede.

Zeramento Noturno (Cron Job): Diariamente, em horário de inatividade (ex: 03:00 AM), uma rotina agendada zera automaticamente o total_presentes na tabela metrica_ocupacao e remove permanentemente todos os registros da tabela PresencaAtiva (zerando todos os tokens de presença do dia anterior de forma definitiva).

Soft Anti-Passback Multi-Endereço (Correção de Fluxo): O sistema gera um token de presença a partir do UID do cartão lido e do Salt diário (gerarTokenPresenca(UID)). Se esse token já consta em PresencaAtiva para a mesma unidade, o sistema sinaliza a ação como uma Saída, deletando o registro do token e decrementando as métricas de ocupação. Se o token constar em uma unidade A mas a leitura ocorreu na unidade B (o usuário esqueceu de registrar a saída na unidade A), o sistema deduz a presença na unidade A, consolida os históricos lógicos e registra a entrada na unidade B de forma transparente, corrigindo o fluxo sem travar o portador.

Trava Piso Zero: O sistema ignora eventos de "saída" caso o token de presença gerado não seja localizado em nenhuma unidade ativa da tabela PresencaAtiva, garantindo que o painel de ocupação geral nunca exiba quantitativos negativos.

5. Módulos Auxiliares e Integrações

5.1 Relatórios Automatizados (Otimização de Refeitório)

O sistema conta com um módulo de envio programado de e-mails para setores estratégicos (como as cozinhas de cada unidade). Um Cron Job envia a contagem da "foto do momento" (agrupando e somando os registros da tabela PresencaAtiva por categoria no instante do disparo), consolidando o relatório por endereço e separando por grupos_refeicao. Horários de disparo, dias da semana, tipos de refeições ofertadas (ex: almoço, lanche noturno) e e-mails destinatários possuem configurações independentes por Endereço/Unidade no painel web. Isso garante que, se um anexo serve apenas lanche noturno, sua cozinha receba exclusivamente relatórios pertinentes à sua realidade, enquanto a Sede recebe múltiplos disparos diários para suas diversas refeições.

5.2 Monitoramento de Saúde da Portaria (Heartbeat / SLA)

Como o sistema opera no modo Offline-First, relatórios podem ser gerados com dados defasados caso uma catraca perca a conexão local sem aviso. Para mitigar o problema operacional, cada envio em lote atualiza a flag ultimo_sincronismo da tabela de hardwares. Se, no momento da geração do relatório da cozinha, alguma catraca registrar inatividade de comunicação superior a 5 minutos, o e-mail incluirá um "Alerta de Dispositivo Incomunicável", relatando o nome da catraca e o horário do último lote recebido, para ciência do recebedor.

5.3 Privacidade por Agrupamento (K-Anonimato)

Para respeitar a LGPD no detalhamento de categorias no e-mail, aplica-se a regra do limiar mínimo. Se um grupo_refeicao registrar menos de 5 pessoas presentes, ele não será listado isoladamente; seu valor será somado a uma categoria genérica de camuflagem ("Outros"). Caso exista apenas um grupo no relatório inteiro com menos de 5 pessoas (o que permitiria inferir a identidade subtraindo do total em "Outros"), o valor numérico desse grupo será sumariamente omitido da visualização em texto, garantindo proteção total contra identificação indutiva.

6. Arquitetura Multi-Tenant (SaaS) e Gestão de Múltiplos Campi

6.1 Isolamento Lógico (Tenants)

O sistema é desenhado como uma plataforma "Multi-Tenant", o que significa que uma única instalação do software na nuvem pode atender a múltiplos campi (ex: IFCE Limoeiro do Norte, IFCE Tabuleiro do Norte). Cada campus opera como um "Controle de Acesso" (Tenant) isolado. Os dados de um campus são invisíveis para os demais. Dentro do mesmo Tenant, o campus pode possuir múltiplos "Endereços/Unidades" interligados, permitindo que os usuários transitem livremente entre os prédios do mesmo campus com o mesmo cartão. Um aluno que visitar um campus totalmente diferente (outro Tenant) deverá receber um cartão de visitante.

6.2 Gestão de Identidade e Papéis (RBAC - Role-Based Access Control)

O acesso ao sistema web é atrelado ao e-mail institucional do servidor. Ao logar, o usuário visualiza apenas os "Controles de Acesso" aos quais foi convidado. Cada membro dentro de um Controle possui um papel restrito:

Proprietário (Owner): Criador do Controle. Possui todas as permissões do sistema. Para evitar o "Fator Ônibus" (perda de acesso definitivo caso o servidor saia da instituição), o Proprietário tem a prerrogativa de transferir a titularidade do Controle para o e-mail de outro Administrador.

Administrador (Admin): Pode convidar membros, adicionar catracas, configurar envio de relatórios e gerenciar os usuários locais.

Visualizador (Viewer): Permissão restrita à visualização de métricas e dashboards (ideal para portarias, cozinhas e telões). A visão do painel é geral para o campus inteiro (Tenant), sendo segmentada organizadamente em abas por Endereço/Unidade, permitindo acompanhar o fluxo global ou focar em um local específico.

7. Contingências de Acesso (Sem Cartão Físico)

Para garantir o fluxo contínuo e a exatidão das métricas sem prejudicar o usuário que esqueceu ou perdeu o cartão, o sistema prevê duas camadas de contingência operacional na portaria:

Emissão de Cartão Provisório (Tier 1 - Recomendado): O agente da portaria valida a identidade do usuário no painel web e vincula temporariamente um "Cartão Provisório" (pré-gravado e pertencente à reserva técnica da portaria) ao seu perfil. O usuário é instruído a devolver o cartão na saída do prédio. Operacionalmente, isso mantém a dinâmica Offline-First intacta, pois o usuário passará autonomamente pela catraca e o hardware validará a entrada e fará a contagem (mantendo 100% de precisão para métricas de refeitório e ocupação sem onerar o servidor).

Registro Manual via Web (Tier 2 - Último Recurso): Esta funcionalidade deve ser utilizada exclusivamente em cenários de falha técnica severa (ex: queda prolongada da internet impedindo a vinculação no banco, falha no gravador NFC da secretaria ou esgotamento total da reserva de cartões provisórios). O agente abre fisicamente o acesso e injeta a entrada no banco de dados via interface web. Isso garante que a instituição não impeça o acesso de uma pessoa autorizada devido a falhas na infraestrutura de TI.