Manual do Usuário — Acesso

Sistema Integrado de Controle de Fluxo por Cartão NFC

Acesso permitido, identidade preservada.

Sumário

1. O que é o Acesso

O Acesso é um sistema de controle de fluxo de pessoas por cartão NFC desenvolvido para instituições de ensino (Acesso permitido, identidade preservada.). Ele permite:

O sistema não é ponto eletrônico de servidores e não serve para fiscalizar assiduidade. Seu único propósito é a segurança patrimonial e humana.

2. Primeiro Acesso — Login

Acesse o endereço do sistema pelo navegador. Você verá a tela de login:

Opção A — Login com Google (recomendado)

Opção B — Login com Magic Link (E-mail)

Opção C — Login com Código de Portaria / Painel (Modo Kiosk)

Esta opção é ideal para dispositivos impessoais da portaria (como celulares PWA fixados para leitura ou tablets que exibem o painel operacional de ocupação). Ela permite login rápido e dispensa o uso de contas de e-mail pessoais nas trocas de turno de porteiros.

⚠ Restrição de Segurança: Sessões iniciadas por código possuem privilégios restritos (Modo Kiosk). O operador não poderá acessar o painel de gerenciamento do campus, visualizar listas de usuários ou alterar qualquer configuração. Tentativas de desviar das páginas designadas serão bloqueadas automaticamente.

Nenhuma senha é criada ou armazenada — o acesso é sempre feito via Google ou link por e-mail.

3. Configuração Inicial — Onboarding

Na primeira vez que você faz login, o sistema solicitará a criação do seu Controle de Acesso:

Passo 1 — Nome da instituição ou campus

Digite o nome do campus que será gerenciado por este controle.

Exemplo: IFCE Limoeiro do Norte

Passo 2 — Primeira unidade / endereço

Cada campus pode ter múltiplas unidades (Sede, Anexo, Quadra, etc.). Comece pela principal.

Exemplo: Sede Principal

Clique em "Criar controle de acesso". Você será redirecionado ao dashboard.

Você pode adicionar mais unidades depois em Configurações → Unidades.

4. Dashboard Principal

O dashboard é a tela central de cada campus. Acesse clicando em "Acesso" no cabeçalho.

Métricas de visão geral

Ocupação por unidade

Abaixo das métricas, cada prédio é exibido com seu total de presentes. Se houver grupos de refeição configurados, o breakdown aparece dentro do card.

Alerta de dispositivo offline

Se uma catraca ficar mais de 5 minutos sem enviar dados, um alerta em vermelho aparece no topo do dashboard com o nome da portaria afetada.

Últimos acessos

Tabela com os 10 registros mais recentes: UUID do cartão, unidade, sentido (entrada/saída) e horário.

Botões de navegação

5. Gerenciar Usuários NFC

Acesse pelo dashboard → "Usuários NFC".

5.1 Listar e filtrar usuários

5.2 Cadastrar novo usuário

Um usuário pode pertencer a múltiplos grupos de refeição simultaneamente. Por exemplo: um aluno interno com direito a Lanche da Manhã + Almoço + Lanche da Tarde terá os três selecionados. O sistema conta cada grupo separadamente no painel e nos relatórios, garantindo que a cozinha saiba exatamente quantos alunos terão cada refeição.

5.3 Perfil do usuário

Clique em "Ver" na tabela de usuários para abrir o perfil. Você encontrará:

Editar perfil

Status do cartão

Cartões com status Bloqueado ou Revogado são rejeitados pelos dispositivos na próxima sincronização da lista de revogações (a cada 60 segundos).

5.4 Gravação de Cartão NFC via Celular (PWA)

O sistema permite gravar o Código único (UUID) do usuário diretamente no cartão físico utilizando a antena NFC de um celular Android compatível com o PWA.

⚠ Atenção: Celulares gravam o UUID no Setor 2 (NDEF Público) do cartão Mifare. Esse formato é ideal para a Fase 1 (onde as estações e catracas dedicadas ainda não estão instaladas), mas não possui a validação criptográfica por Chave A do Setor 1.

Há duas formas de iniciar a gravação do cartão pelo celular:

Método A — Durante o Cadastro do Usuário (Recomendado)

Método B — A qualquer momento pelo Perfil do Usuário

Se você pulou a gravação durante o cadastro ou precisa refazer a gravação de um cartão:

6. Gerenciar Dispositivos (Catracas / Leitores)

Acesse pelo dashboard → "Dispositivos".

6.1 Tipos de dispositivo

O sistema suporta dois tipos de dispositivo:

6.2 Registrar novo dispositivo

⚠ Importante: Após o cadastro, a API Key será exibida uma única vez. Copie-a imediatamente. Caso perca a chave, é possível gerar uma nova na página do dispositivo.

Para dispositivos Android/PWA, após copiar a chave, clique em "Ativar Modo Catraca →" para abrir a interface de leitura NFC no celular.

6.3 Monitorar dispositivos

Cada card de dispositivo exibe:

6.4 Gerenciar um dispositivo

Clique em "Gerenciar / Rotacionar Key" no dispositivo para editar suas configurações:

6.5 Remover um dispositivo

Clique em "Remover" e confirme. O dispositivo deixará de ser reconhecido imediatamente.

6.6 Endpoint de sincronização

POST /api/hardware/sync
Header: X-API-Key: <chave do dispositivo>
Body: { "acessos": [{ "uuidCampus": "...", "sentido": "entrada", "timestampAcesso": "2026-07-04T08:00:00Z" }] }

Este endpoint é usado tanto pelo ESP32 quanto pelo PWA Android.

7. Modo Catraca PWA (Android)

O Modo Catraca transforma um celular Android com Chrome em uma catraca funcional usando a Web NFC API. Indicado para contingências e portarias secundárias.

Requisitos:

7.1 Configurar o Modo Catraca pela primeira vez

A chave é salva localmente no navegador. Não será solicitada novamente neste dispositivo.

7.2 Interface do Modo Catraca

7.3 Como usar na portaria

7.4 Funcionamento offline

Se a internet cair durante o uso:

7.5 Limitação de segurança

⚠ O PWA lê apenas o registro NDEF público do cartão (Setor 2). Ele não valida a Chave A criptográfica do Setor 1. Um cartão clonado com cópia do NDEF público seria aceito. Por isso, este modo é indicado apenas para contingências com agente presente, que pode verificar a identidade visualmente.

7.6 Solução de Problemas NFC (Erros Comuns)

1. Erro: "Web NFC não suportado..." ou "O Web NFC exige uma conexão segura (HTTPS)..."

Esse erro ocorre principalmente se você acessar o sistema usando uma conexão não criptografada (HTTP), como ao testar localmente na rede Wi-Fi (http://192.168.x.x:3000). O Chrome bloqueia recursos de hardware de segurança, como Web NFC, fora de contextos seguros.

Dica: Você também pode usar uma ferramenta de túnel reverso como ngrok para obter um endereço público HTTPS direcionado ao seu servidor local.

2. Erro: "O NFC está desativado nas configurações do seu celular..."

3. Erro: "A permissão para acessar o NFC foi negada..."

8. Configurações do Controle de Acesso

Acesse pelo dashboard → "Configurações". Disponível apenas para Proprietários e Administradores.

A página possui 4 abas:

Aba Geral

Permite alterar as configurações fundamentais do campus:

Aba Unidades

Gerencia os prédios/endereços do campus.

Adicionar unidade:

Renomear: clique em "Renomear" ao lado da unidade, edite e salve.

Remover: clique em "Remover". Só é possível remover uma unidade que não tenha dispositivos vinculados. Remova os dispositivos dela primeiro.

Aba Membros

Gerencia quem tem acesso ao painel web.

Adicionar membro:

Alterar papel: use o seletor ao lado do nome do membro.

Remover: clique em "Remover". O Proprietário não pode ser removido.

Para transferir a titularidade (papel de Proprietário), entre em contato com o administrador do sistema.

Aba Relatórios

Configura o envio automático de e-mails para cozinhas e setores.

Criar novo agendamento:

Clique em "Criar agendamento".

Ativar / desativar: clique no botão de status ao lado da configuração.

Remover: clique em "Remover" e confirme.

Os relatórios são enviados com o número de presentes no momento exato do disparo, com proteção de anonimato: grupos com menos de 5 pessoas são agrupados em "Outros" para respeitar a LGPD e o ECA.

9. Painel Operacional (Portaria / Cozinha / Telão)

Acesse pelo dashboard → "Painel Operacional", ou diretamente em /painel/[id-do-campus].

Este painel é projetado para telas grandes, tablets e monitores nas portarias e refeitórios.

O que é exibido

Atualização automática

O painel se atualiza a cada 30 segundos automaticamente. Não é necessário recarregar a página.

Alertas operacionais

Se uma catraca perder comunicação por mais de 5 minutos, uma faixa de alerta vermelha aparece abaixo do cabeçalho informando o nome da portaria e o horário do último contato.

Nota de privacidade: O painel não exibe nenhum nome ou dado pessoal — apenas contagens numéricas agregadas.

10. Painel Administrativo do Sistema

Disponível apenas para Administradores do Sistema (definidos na variável ADMIN_EMAILS do servidor). Acesse em /admin ou pelo link "Admin" no cabeçalho.

O que é exibido

11. Procedimentos de Contingência

Usuário sem cartão — Tier 1 (Recomendado): Cartão Provisório

Usuário sem cartão — Tier 2 (Último recurso): Registro Manual

Use apenas em caso de falha técnica severa (queda prolongada de internet, falha no gravador de cartões ou esgotamento da reserva provisória):

Catraca offline

Se uma catraca perder conexão:

Queda de energia elétrica

O módulo RTC (relógio com bateria) do dispositivo garante que os horários registrados offline permaneçam corretos mesmo sem energia elétrica.

12. Integração com Hardware (ESP32)

Esta seção é destinada à equipe técnica responsável pela configuração dos dispositivos.

Fluxo de operação

Cartão aproximado → ESP32 autentica localmente (< 200ms) → libera acesso
                                    ↓ (a cada 60s)
                         Envia lote para /api/hardware/sync
                         Atualiza lista de cartões revogados

Configuração do firmware

Após registrar o dispositivo no sistema e copiar a API Key:

const char* API_KEY   = "sua_api_key_aqui";
const char* SYNC_URL  = "https://seu-dominio.com/api/hardware/sync";

Formato do lote de sincronização

{
  "acessos": [
    {
      "uuidCampus": "550e8400-e29b-41d4-a716-446655440000",
      "sentido": "entrada",
      "timestampAcesso": "2026-07-04T08:23:15Z"
    },
    {
      "uuidCampus": "550e8400-e29b-41d4-a716-446655440001",
      "sentido": "saida",
      "timestampAcesso": "2026-07-04T08:24:02Z"
    }
  ]
}

Campos:

Cartão Mifare Classic 1K

A Chave A padrão (FFFFFFFFFFFF) deve ser substituída pela assinatura criptográfica da instituição durante a gravação do cartão.

13. Papéis e Permissões

O Visualizador é o papel ideal para agentes de portaria, funcionários da cozinha e telões — acesso de leitura sem risco de alterações acidentais.

14. Perguntas Frequentes

Qual a diferença entre o ESP32 e o Modo Catraca PWA?

O ESP32 autentica a Chave A criptográfica do Setor 1 do cartão Mifare, tornando a clonagem muito difícil. O PWA lê apenas o registro NDEF público (Setor 2), sem validação de chave — aceita qualquer cópia do UUID. Use o ESP32 nas portarias permanentes e o PWA apenas como contingência com agente presente.

O sistema registra horário de entrada e saída de cada aluno individualmente?

Sim, o histórico de acessos está disponível no perfil de cada usuário NFC. O acesso a esses dados é restrito a Administradores e Proprietários.

O painel da portaria mostra o nome dos alunos?

Não. O painel operacional exibe apenas contagens numéricas, sem nenhum dado nominal.

O que acontece se um cartão for clonado?

Os cartões Mifare Classic com Chave A personalizada bloqueiam a grande maioria das clonagens simples por aplicativo. Para segurança adicional, cartões Mifare DESFire são compatíveis com o sistema via leitores PN532.

Um aluno pode usar o cartão em outro campus?

Não. Cada campus é um "Controle de Acesso" independente. Um visitante de outro campus deve receber um cartão provisório.

Os dados de alunos menores de idade ficam protegidos?

Sim. O sistema segue as diretrizes do ECA Digital e da LGPD: dados nominais são acessíveis apenas a gestores autorizados, o painel público exibe apenas números, e relatórios com grupos pequenos aplicam mascaramento automático.

Como renovar a API Key de uma catraca?

Acesse Dispositivos → [nome da portaria] → Gerenciar → "Gerar nova API Key". A chave antiga é invalidada imediatamente. Atualize o firmware do ESP32 com a nova chave.

Posso ter múltiplos campi no mesmo sistema?

Sim. Cada usuário pode ser membro de múltiplos Controles de Acesso. Ao fazer login, o sistema direciona automaticamente para o primeiro campus. Futuramente, um seletor de campus estará disponível no cabeçalho.

O relatório não chegou no horário configurado. O que fazer?

Verifique: (1) se o agendamento está Ativo na aba Relatórios; (2) se o dia da semana atual está selecionado; (3) se as configurações de e-mail (EMAIL_SERVER_*) estão corretas no servidor; (4) se o serviço de cron está ativo (Vercel Cron ou equivalente).

15. Guia de Badges e Indicadores Visuais

O sistema utiliza diversos indicadores visuais (badges coloridos) para facilitar o monitoramento do status de usuários, dispositivos, papéis administrativos e conexão. A seguir, detalhamos todos eles:

15.1 Status do Cartão do Usuário

Exibidos nas listas de usuários e na tela de perfil, indicam a situação operacional do cartão NFC de cada pessoa:

15.2 Status de Conexão das Unidades (Prédios)

Exibidos no topo direito de cada card de unidade no Painel Operacional e no Dashboard Principal:

15.3 Status e Tipo dos Dispositivos (Catracas / Leitores)

Exibidos no gerenciamento de dispositivos (Dashboard → Dispositivos):

15.4 Níveis de Acesso de Membros (Papéis)

Exibidos no gerenciamento de membros (Dashboard → Configurações → Membros):

Acesso — Acesso permitido, identidade preservada. Versão 1.0.0 · 2026