Mapeamento Completo de Funcionalidades e Capacidades Técnicas — Sistema Acesso

Slogan: "Acesso permitido, identidade preservada."

Objetivo deste documento: Apresentar uma lista abrangente e exaustiva de todas as capacidades operacionais, administrativas, de hardware, privacidade e segurança desenvolvidas no software Acesso para apreciação da gestão e registro de propriedade intelectual.

1. Gestão do Controle de Acesso (Multi-Tenant & Instâncias Institucionais)

Criar e gerenciar múltiplos Controles de Acesso (Tenants): Permite isolar os dados de diferentes campi, instituições ou unidades de ensino em instâncias independentes.

Personalização Institucional: Permite nomear cada controle de acesso de acordo com o campus ou unidade correspondente (ex: IFCE - Campus Fortaleza, Campus Crato).

Gestão de Membros e Permissões: Suporta a atribuição de papéis de acesso ao painel web (Proprietário / Owner, Administrador / Admin e Visualizador / Viewer).

Convite de Gestores por E-mail: Permite adicionar novos servidores e administradores ao painel web diretamente pelo seu e-mail institucional.

Alteração Dinâmica de Papéis: Permite promover visualizadores a administradores ou alterar privilégios de gestão instantaneamente.

Remoção de Membros: Permite revogar o acesso de gestores ao painel de controle a qualquer momento.

2. Gestão de Unidades Físicas e Prédios do Campus

Cadastrar Múltiplas Unidades Físicas: Permite cadastrar endereços, blocos e prédios distintos dentro do mesmo campus (ex: Bloco Didático A, Refeitório Central, Biblioteca, Auditório).

Renomear Unidades: Permite atualizar os nomes das unidades sem afetar os históricos de ocupação anteriores.

Remoção Segura de Unidades: Impede a exclusão acidental de unidades que possuam catracas ou leitores vinculados.

Controle de Ocupação em Tempo Real por Unidade: Mantém a contagem de pessoas presentes atualizada instantaneamente a cada passagem de entrada ou saída.

3. Gestão de Categorias de Usuários e Grupos de Refeição

Categorização Flexível de Usuários: Permite criar categorias personalizadas para organização do público (ex: Estudantes, Servidores, Terceirizados, Visitantes).

Grupos de Refeição Customizados: Permite cadastrar horários e grupos de refeição associados ao restaurante acadêmico (ex: Lanche Manhã, Almoço, Lanche Tarde, Jantar).

Atribuição Multi-Refeição: Suporta que um mesmo estudante ou usuário tenha direito a múltiplos grupos de refeição simultaneamente.

Contadores de Ocupação por Refeição: Mantém contadores separados de presença por grupo de refeição em tempo real.

4. Gestão de Usuários NFC e Identificadores Institucionais

Cadastro Manual de Usuários: Permite cadastrar individualmente alunos, servidores e visitantes informando nome, categoria e refeições autorizadas.

Suporte a Identificadores Institucionais Adaptativos:

Alunos: Campo e rótulo dinâmico para Matrícula.

Servidores: Campo e rótulo dinâmico para SIAPE.

Visitantes / Terceirizados: Campo e rótulo dinâmico para CPF ou Documento de Identificação.

Geração Automática de UUID do Campus: Gera um código único identificador de 36 caracteres (uuidCampus) para gravação no cartão físico NFC.

Busca e Filtro Avançado de Usuários: Permite pesquisar instantaneamente por nome, matrícula, SIAPE, CPF ou código UUID do cartão.

Filtro por Categoria e Status: Permite filtrar a lista de usuários por categoria ou por status do cartão (Ativo, Provisório, Bloqueado, Revogado).

Bloqueio Instantâneo de Cartões: Permite alterar o status do cartão para Bloqueado impedindo a liberação da catraca imediatamente.

Revogação de Acesso: Permite revogar cartões de alunos desligados ou formados.

Edição de Perfis: Permite atualizar nomes, categorias, identificadores e permissões de refeição de usuários já cadastrados.

5. Integração Automatizada com o SUAP (Importação & Sync Semestral)

Importação Nativa de Planilhas do SUAP: Suporta a leitura direta de arquivos exportados do SUAP nos formatos .xls, .xlsx e .csv.

Detecção Automática de Tipo de Listagem: Identifica automaticamente se o arquivo importado é uma listagem de Alunos (cabeçalhos #, Nome, Matrícula, Curso...) ou de Servidores (#, Matrícula, Nome, Cargo...).

Extração Automática de Dados: Lê e valida os campos essenciais de Nome e Matrícula / SIAPE sem necessidade de digitação manual.

Pré-visualização de Dados: Exibe uma tabela de pré-visualização com os registros encontrados antes de confirmar a gravação no banco de dados.

Opção de Atualização de Existentes: Permite atualizar automaticamente os nomes e reativar cadastros de alunos que já possuem registro prévio.

Sincronização Semestral Automatizada (Revogação de Ausentes):

Identifica alunos/servidores previamente cadastrados naquela categoria que não constam na nova lista do SUAP.

Alteração automática do status desses usuários ausentes para Revogado.

Limpeza Automática de Presença: Se um usuário ausente da nova lista estiver marcado como presente no campus no momento da importação, o sistema remove sua presença ativa e ajusta a ocupação do prédio na hora.

Preservação de Histórico: Garante que nenhum histórico de acesso passado seja excluído ou perdido na revogação.

Reativação Automática: Se um aluno que estava revogado voltar em uma nova lista do SUAP, seu status é automaticamente restaurado para Ativo.

Resumo Estatístico pós-Importação: Exibe um painel explicativo com o total de Novos Cadastrados, Atualizados / Reativados, Mantidos Inalterados e Revogados (Ausentes).

6. Controle de Gravação Física de Cartões NFC (PWA Web NFC)

Indicador Universal do Status da Gravação: Exibe uma badge destacada na tabela e nos perfis para diferenciar:

🟡 Pendente de Gravação: Usuários cadastrados/importados que ainda não gravaram o cartão no balcão.

🟢 Cartão Gravado / Entregue: Usuários com o cartão NFC físico já gravado e entregue.

Filtro de Atendimento de Balcão: Permite filtrar a lista com 1 clique para ver Somente Pendentes (saber exatamente quem precisa vir gravar o cartão) ou Somente Gravados.

Gravação via PWA no Celular (Web NFC): Permite encostar o cartão NFC na traseira de um smartphone Android para gravar o UUID do campus diretamente no Setor 1 do cartão Mifare.

Confirmação Auditiva e Tátil: Emite bip sonoro e vibração no smartphone ao concluir a gravação NFC com sucesso.

Atualização Automática no Banco ao Gravar: Ao concluir a gravação NFC no celular, o sistema salva automaticamente a data/hora e altera o status para Cartão Gravado.

Marcação Manual de Gravação: Disponibiliza o botão [ Marcar como Gravado ] / [ Marcar como Pendente ] no perfil do usuário para secretarias que utilizam gravadores de mesa no computador.

Alerta e Confirmação Dupla no Reuso de Cartões (Dupla Confirmação em 2 Passos):

Detecta se um cartão NFC encostado no balcão já pertence a outro usuário ativo.

Exibe um card de alerta destacado em amarelo/laranja informando o nome e status do antigo proprietário.

Exige confirmação em 2 passos (Passo 1: Marcar a caixa de seleção de ciente; Passo 2: Clicar no botão de confirmação) para transferir o cartão.

Limpeza Automática do Cartão Antigo: Ao confirmar a reatribuição, o sistema revoga automaticamente o cartão do usuário anterior, limpa suas presenças ativas e vincula o cartão ao novo proprietário com segurança.

7. Operação de Hardware, Catracas Embarcadas ESP32 e Modo PWA Móvel

Suporte a Hardware Embarcado (ESP32 / Catracas Físicas): Integração via API REST B2B segura com microcontroladores ESP32 e leitores NFC de catracas.

Modo Catraca Móvel em Celulares (PWA): Transforma qualquer smartphone Android com NFC em uma catraca de mão móvel para uso em portarias temporárias, ônibus intercampus ou eventos.

Autenticação de Dispositivos por API Key Criptografada: Cada catraca/celular possui uma chave única criptografada com hash SHA-256 no banco (apiKeyHash).

Monitoramento de Comunicação e Status Offline: Rastreia a data e hora da última sincronização de cada leitor/catraca (ultimoSincronismo), alertando gestores se um leitor ficar sem comunicação por mais de 5 minutos.

Retorno Amigável no Leitor: Retorna nomes genéricos/categoria no visor da catraca ou aplicativo para confirmação rápida da portaria.

8. Motor de Privacidade por Design (Privacy by Design), LGPD & ECA

Nenhum Dado Pessoal no Visor do Operador: O operador da catraca não visualiza CPF, matrícula ou dados sensíveis durante a liberação da catraca.

Conformidade com o Estatuto da Criança e do Adolescente (ECA): Proteção integral aos dados de alunos menores de idade, eliminando rastros de rotina física.

Anonimização no Histórico de Passagens: A tabela HistoricoAcesso registra apenas evento estatístico (entrada/saída), categoria (Estudante), grupo de refeição (Almoço), data/hora e catraca. O UUID do cartão e a referência ao usuário físico são completamente omitidos/nulos no histórico.

Máscara de K-Anonimato ($< 5$): Em todas as telas, APIs e relatórios, qualquer contagem de presença ou ocupação inferior a 5 pessoas é automaticamente mascarada.

Linguagem Humanizada de Privacidade nos E-mails: Em vez de usar símbolos matemáticos frios (< 5), os e-mails exibem a badge explicativa 🟡 Menos de 5 pessoas e incluem nota explicativa no rodapé:

"Nota de Privacidade (LGPD & K-Anonimato): Ocupações inferiores a 5 pessoas são indicadas como 'Menos de 5 pessoas' para preservar a identidade individual."

9. Segurança Criptográfica & In-Memory Ephemeral Secret (Proteção contra DBA)

Segredo Epêmero em Memória RAM (RAM Ephemeral Secret):* A chave criptográfica utilizada para calcular os hashes de presença ativa é gerada aleatoriamente na memória RAM do Node.js (crypto.randomBytes(32)) na inicialização do servidor.

Proteção Absoluta contra Acesso Direto ao Banco (DBA Proof): Mesmo que um administrador de banco de dados (DBA) ou hacker tenha acesso total às tabelas do PostgreSQL e aos arquivos .env, é impossível descobrir quem são os usuários presentes, pois a chave criptográfica não existe em disco.

Rotação Automática de Chaves: Reiniciar o servidor ou virar o dia regenera a chave epêmera, tornando hashes antigos totalmente indecifráveis.

Reset Noturno Noturno Automático (03:00 AM): Um agendador interno em segundo plano limpa diariamente às 03h00 da madrugada todos os tokens de presença ativa, garantindo que o banco inicie zerado a cada dia.

10. Sincronização Offline, Resiliência de Hardware e Lotes de Acesso

Suporte a Filas Offline no Hardware/PWA: Permite que leitores e catracas acumulem registros de acesso na memória interna quando a internet cair e enviem em lote quando a conexão voltar.

Deduplicação de Acessos Rápidos (<15 segundos): Filtra aproximações acidentais ou repetidas do mesmo cartão no leitor em um intervalo inferior a 15 segundos.

Resiliência a Conflitos de Banco de Dados (P2002 / P2025): Caso um evento offline traga uma entrada duplicada ou tentativa de saída de alguém já removido, a API trata a exceção graciosamente sem derrubar a transação ou retornar erro HTTP 500 para a catraca.

Trava Antiestouro de Contadores (GREATEST em PostgreSQL): O sistema utiliza comandos SQL atômicos que impedem que contadores de ocupação fiquem negativos mesmo sob estresse.

11. Agendamento de Relatórios por E-mail & Motor Catch-Up (Tolerância a Falhas)

Agendamento Flexível por E-mail: Permite cadastrar e-mails institucionais para receber relatórios automáticos de ocupação.

Seleção Múltipla de Unidades: Permite selecionar uma, várias ou todas as unidades do campus para serem consolidadas no mesmo e-mail.

Seleção Múltipla de Grupos de Refeição: Permite escolher um, vários ou todos os grupos de refeição (ex: Almoço, Jantar) para compor o relatório.

Filtros por Dias da Semana e Horário: Permite marcar os dias específicos (ex: Seg, Ter, Qua, Qui, Sex) e a hora exata do disparo (ex: 07:00).

Ativação e Desativação de Agendamentos: Permite pausar ou reativar agendamentos com 1 clique sem precisar excluí-los.

E-mail Consolidado com Design Premium: Renderiza um e-mail em HTML responsivo com cartões visuais para cada unidade, alertas de dispositivos offline e totalizadores de ocupação.

Motor de Recuperação Automática de E-mails (Catch-Up / Fault Tolerance):

Registra no banco a data/hora do último envio bem-sucedido (ultimoDisparoEm).

Se o servidor ou a conexão oscilarem no horário exato do agendamento (ex: caiu das 06:58 às 07:12), assim que o sistema religar (às 07:13), o robô identifica o e-mail pendente do dia e efetua o disparo atrasado imediatamente.

Previne múltiplos disparos no mesmo dia.

12. Exportação de Dados e Histórico Estatístico de Ocupação

Consulta de Histórico de Ocupação: Permite visualizar no painel os registros estatísticos de ocupação coletados a cada 5 minutos.

Filtros por Período e Unidade: Permite selecionar datas de início e fim e filtrar por unidade específica.

Exportação para CSV / Excel: Permite baixar os dados de ocupação em formato .csv estruturado com suporte a caracteres acentuados no Microsoft Excel (UTF-8 BOM).

K-Anonimato na Persistência: Valores de ocupação de 5 minutos inferiores a 5 pessoas são gravados como 0 na persistência do banco de dados para impedir inferência temporal por canal lateral.

13. Painel de Ocupação em Telões (Modo Kiosk & Códigos sem Senha)

Visualização Pública/Portaria sem Necessidade de Login: Permite abrir o painel de ocupação em monitores de portaria, guaritas ou telões.

Autenticação por Código de Acesso Kiosk: Gera códigos alfanuméricos curtos de acesso direto ao painel sem expor credenciais de administradores.

Atualização em Tempo Real via Polling: O painel atualiza os indicadores de ocupação e gráficos automaticamente a cada poucos segundos.

Modo Dark / Alta Visibilidade: Layout projetado com alto contraste e estética moderna para visualização à distância.

14. Administração Central da Plataforma e Estatísticas Globais

Painel Super Admin (/admin): Tela restrita para acompanhamento global da plataforma.

Métricas Globais da Plataforma: Exibe o total de usuários cadastrados, sessões ativas, controles de acesso criados, unidades físicas e dispositivos de hardware conectados.

Contagem de Acessos Diários e Mensais: Exibe o total consolidado de acessos processados no dia e no mês.

Alerta Global de Dispositivos Offline: Lista todos os leitores e catracas de qualquer campus que estejam sem comunicação com o servidor.

🟢 Conclusão

O Acesso é um sistema completo, pronto para produção, que une alto desempenho na gestão de fluxo de pessoas à garantia absoluta de conformidade com a LGPD e o ECA por meio de inovações criptográficas e arquiteturais inéditas.