Documentação · Presença Geo

Como funciona, em 30 segundos

A plataforma substitui a chamada manual por uma validação espacial automatizada. O docente cria uma sessão, configura o ponto central da sala e um raio de tolerância em metros. O sistema gera um QR Code com validade limitada. O aluno escaneia o QR Code e a página que abre solicita três coisas: nome, matrícula e consentimento para capturar localização e identificadores técnicos do dispositivo. Após o envio, três validações independentes acontecem no servidor:

A distância em linha reta entre o aluno e o ponto central da sala é calculada pela fórmula de Haversine. Se exceder o raio, a presença é rejeitada.
Uma impressão digital do dispositivo (combinação de userAgent, hardware, tela, fuso horário e renderização canvas) é confrontada com o banco. Se o mesmo dispositivo já registrou outra matrícula nesta sessão, a presença é rejeitada.
A matrícula é verificada. Se já consta como presente, a presença é rejeitada.

Passando nas três validações, a presença é registrada, aparece em tempo real no painel do docente (lista e mapa 3D) e fica disponível para exportação em planilha pronta para o SIGAA.

Fluxo do docente

1Abra o painel

Acesse a página inicial. Você verá um cabeçalho com a métrica de sessões ativas, sessões registradas, presenças contabilizadas e sessões encerradas. As abas Ativas e Histórico separam o que está acontecendo agora do que já foi encerrado.

2Crie uma nova sessão

Clique em Abrir nova sessão. Preencha:

Turma — nome ou código que identifica a aula no painel.
Latitude e longitude da sala. Use o botão “Usar minha localização” dentro da sala para capturar via GPS, ou digite manualmente as coordenadas se já souber.
Raio (m) — distância máxima aceita. Padrão 50 m. Para salas pequenas, 30 m é suficiente; para auditórios grandes, 80–100 m.
Validade (min) — quanto tempo o QR Code permanece aceitando presenças. Padrão 5 min. Recomendado manter curto para evitar compartilhamento do link.
Docente (opcional) — texto livre para identificar a sessão no histórico.

3Projete o QR Code

Após criar a sessão, o painel exibe o QR Code, o link completo, dois botões e a lista ao vivo. Projete o QR Code na TV/projetor da sala. Não compartilhe o link por mensagem — o token presente na URL é o que dá acesso à página de presença.

4Acompanhe a presença em tempo real

À medida que os alunos escaneiam e validam, dois componentes atualizam imediatamente:

A lista de presença ganha uma nova linha com nome, matrícula, distância apurada e horário.
O mapa de densidade 3D faz surgir hexágonos cuja altura é proporcional ao número de alunos em cada microrregião. Cores variam do creme ao vermelho profundo conforme a concentração aumenta.

Tentativas rejeitadas aparecem em um sub-painel com a razão (fora do raio, dispositivo duplicado, etc.).

5Encerre a sessão

Quando o tempo terminar, a sessão é encerrada automaticamente. Você também pode encerrar manualmente clicando em Encerrar sessão. Após encerrada, nenhuma nova presença é aceita; tentativas retornam 410 CLOSED e ficam registradas como tentativa de fraude.

6Exporte para o SIGAA

Com pelo menos uma presença registrada, dois botões ficam disponíveis:

Exportar SIGAA — planilha enxuta (4 colunas) no formato exato exigido pelo módulo “Lançar Frequência em Planilha”.
Relatório completo — auditoria com 13 colunas incluindo coordenadas, IP, fingerprint e timestamps. Para registro interno do docente, nunca para o SIGAA.

7Consulte o histórico

Sessões expiradas ou encerradas migram automaticamente para a aba Histórico no painel. Você pode entrar, ver a lista final e baixar os CSVs a qualquer momento, inclusive dias depois.

Fluxo do aluno

1Escaneie o QR Code

Use a câmera do celular ou um leitor de QR. O navegador abrirá em uma página com o nome da turma, o raio configurado e o horário de expiração.

2Leia o termo de consentimento

O termo cita explicitamente quais dados são coletados: geolocalização (GPS/Wi-Fi), precisão do sinal, identificador técnico do aparelho (canvas/WebGL/hardware), user agent e IP de origem. A base legal é a LGPD, art. 6º (necessidade e minimização). Sem a marcação do checkbox, o envio é bloqueado.

3Permita acesso à localização

O navegador exibirá um pop-up nativo solicitando permissão. Toque em Permitir. Sem isso, o servidor responde com GEO_DENIED e a presença não pode ser registrada — o aluno teria que abrir o link no celular, liberar a permissão no menu do navegador e tentar de novo.

4Aguarde o resultado

Em até dois segundos, o cartão de resultado mostra:

“Presença confirmada” + distância apurada em metros.
Ou um cartão de erro com instrução para corrigir.

Não precisa fazer mais nada — a confirmação aparece instantaneamente no painel do docente.

Regras de validação

As cinco regras abaixo são cumulativas. A presença só é aceita se todas forem satisfeitas. Qualquer falha gera um registro na trilha de auditoria.

Regra 1 · Geofence (Haversine)

Severidade alta

PermitidoO aluno está a distância ≤ ao raio configurado da sessão.

BloqueadoO aluno está fora do raio. A distância em linha reta entre as coordenadas do aluno e o centro da sala excede o raio.

Detalhe técnico — Distância calculada pela fórmula de Haversine no servidor, com raio da Terra de 6.371.000 m. O cliente envia lat/lon, mas o servidor sempre recalcula — nunca confia no que o aluno diz da posição dele.

Regra 2 · Impressão digital única por sessão

Severidade alta

PermitidoO dispositivo do aluno nunca foi usado nesta sessão para registrar outra matrícula.

BloqueadoEste dispositivo já foi usado para registrar uma matrícula diferente. Um dispositivo, uma presença.

Detalhe técnico — A impressão digital é uma chave SHA-256 (64 caracteres hex) gerada a partir de userAgent, número de núcleos lógicos, memória do dispositivo, resolução, fuso horário, idioma e da imagem renderizada por um canvas HTML5. A unicidade é garantida no banco pela constraint @@unique([sessionId, fingerprintHash]).

Regra 3 · Matrícula única por sessão

Severidade alta

PermitidoEsta matrícula ainda não foi registrada como presente.

BloqueadoEsta matrícula já foi registrada nesta sessão (em outro dispositivo, em outro horário). Não há como marcar presença duas vezes.

Detalhe técnico — Garantida pela constraint @@unique([sessionId, matricula]). Esta regra protege contra o caso em que dois dispositivos diferentes tentariam enviar a mesma matrícula (por exemplo, se um aluno reaproveitasse o tablet de outro).

Regra 4 · Validade do QR Code

Severidade média

PermitidoA submissão ocorreu dentro da janela de validade configurada (por padrão, 5 minutos).

BloqueadoO QR Code já expirou. Mesmo com link válido, presença não é mais aceita.

Detalhe técnico — O servidor compara session.expiresAt com o relógio do próprio servidor. O cliente não pode estender a janela. Janelas curtas dificultam o repasse do link por WhatsApp.

Regra 5 · Token íntegro

Severidade alta

PermitidoO token na URL foi assinado pelo servidor e não foi adulterado.

BloqueadoO token foi modificado em qualquer caractere. Verificação HMAC falha.

Detalhe técnico — O token tem formato nonce.assinatura. A assinatura é um HMAC-SHA256 do nonce com um segredo do servidor (variável de ambiente ATTENDANCE_SECRET). Mesmo conhecendo a estrutura, um atacante não consegue forjar um token sem o segredo. O banco armazena apenas o SHA-256 do token bruto, então um vazamento do banco também não revela tokens utilizáveis.

Códigos de rejeição

Quando alguma regra falha, o servidor responde com um código HTTP específico e grava um RejectedAttempt com o motivo. Use esta tabela para identificar a causa.

HTTP	Motivo	Significado	Ação corretiva
401	INVALID_TOKEN	Token adulterado ou assinatura HMAC inválida.	Solicitar novo QR Code ao docente.
409	DUPLICATE_FINGERPRINT	Este dispositivo já registrou outra matrícula na sessão.	Cada aluno marca presença no próprio celular.
409	DUPLICATE_MATRICULA	Esta matrícula já consta como presente.	Conferir se a matrícula foi digitada corretamente.
410	EXPIRED	QR Code passou da validade.	Solicitar novo QR Code ao docente.
410	CLOSED	Sessão foi encerrada manualmente pelo docente.	Não é mais possível marcar nesta sessão.
422	OUT_OF_RANGE	Posição GPS fora do raio configurado.	Aproximar-se do ponto central da sala.
—	GEO_DENIED	Permissão de localização foi negada no navegador.	Liberar a permissão nas configurações e tentar novamente.

Antifraude — explicação técnica

Por que três regras independentes?

Cada regra cobre uma classe diferente de fraude. Combinadas, bloqueiam todas as fraudes triviais de chamada acadêmica.

Cenário A · Aluno em casa, pede para colega marcar

Tentativa — Aluno ausente compartilha o link com o colega presente. Colega tenta marcar a matrícula do ausente do próprio celular.

Defesa — Bloqueado pela Regra 2. O celular do colega já registrou a própria presença → DUPLICATE_FINGERPRINT.

Cenário B · Aluno em casa, próprio celular

Tentativa — Aluno em casa abre o link compartilhado por WhatsApp e tenta marcar do próprio celular.

Defesa — Bloqueado pela Regra 1. GPS retorna coordenadas distantes da sala → OUT_OF_RANGE.

Cenário C · VPN ou spoofing de IP

Tentativa — Aluno tenta mascarar a localização via VPN ou alterar o IP.

Defesa — Indiferente. A validação espacial nunca usa o IP — usa coordenadas GPS reais do hardware do celular. O IP só entra na trilha forense.

Cenário D · Mesmo aparelho, abas anônimas

Tentativa — Aluno presente tenta marcar três matrículas usando o navegador anônimo e a câmera privada.

Defesa — Bloqueado pela Regra 2. A impressão digital ignora cookies e localStorage; ela depende do hardware e da renderização canvas, que não mudam entre modos. Após a primeira presença, qualquer tentativa do mesmo aparelho cai em DUPLICATE_FINGERPRINT.

Cenário E · Adulteração do token no link

Tentativa — Aluno tenta gerar um token válido modificando a URL.

Defesa — Bloqueado pela Regra 5. A assinatura HMAC falha sem conhecimento do segredo do servidor → INVALID_TOKEN.

Cenário F · Coordenadas fabricadas via DevTools

Tentativa — Aluno usa o emulador de Sensors do Chrome para enviar coordenadas falsas dentro do raio.

Defesa — Mitigação parcial. A plataforma pode aceitar a presença porque a posição informada está dentro do raio. Contramedida: as coordenadas ficam gravadas no Relatório completo, e divergências grosseiras (latitude com 1 casa decimal exata, sem variação entre alunos) ficam evidentes na auditoria. Em ambiente móvel real, esse ataque exige privilégios de root/jailbreak.

Como a impressão digital é construída

A impressão digital combina sinais passivos do hardware/software do dispositivo. Nenhuma permissão extra é solicitada — todos os vetores estão disponíveis pelo padrão da web.

navigator.userAgent · versão do navegador, OS, arquitetura.
navigator.hardwareConcurrency · número de núcleos lógicos.
navigator.deviceMemory · RAM aproximada.
screen.width × screen.height · resolução física.
screen.colorDepth · profundidade de cor.
Intl.DateTimeFormat().resolvedOptions().timeZone · fuso horário.
navigator.language · idioma preferencial.
Hash canvas · uma string desenhada em um <canvas> invisível e convertida para Base64. Pequenas diferenças entre GPUs, drivers e fontes instaladas produzem bytes finais distintos.

Todos os vetores são concatenados com | e passados por crypto.subtle.digest("SHA-256", ...). O resultado tem 64 caracteres hexadecimais. O hash é gravado no banco; os vetores brutos não são.

Privacidade e LGPD

A plataforma opera sob Lei nº 13.709/2018 (LGPD), art. 6º — princípios de necessidade e minimização. Toda coleta é episódica e justificada por finalidade clara.

O que é coletado

Nome completo (declarado pelo aluno)
Matrícula (declarada pelo aluno)
Latitude e longitude
Precisão do GPS
Impressão digital do dispositivo (hash SHA-256)
User agent
Endereço IP (bruto e hash salgado)

O que NÃO é coletado

Histórico de localização (apenas o ponto único)
Lista de contatos, fotos, microfone, câmera
Cookies de terceiros / publicidade
Identificadores de Apple/Google (IDFA/AAID)
Biometria facial ou digital do aluno
Acesso ao Wi-Fi / Bluetooth nominal

Finalidade

Validar presença em uma única aula. Nenhuma análise de comportamento, perfil, ou cruzamento com outras bases.

Base legal

Consentimento explícito (LGPD art. 7º, I) + execução de política institucional acadêmica (art. 7º, IV).

Retenção

Coleta episódica. Coordenadas e IP bruto devem ser anonimizados após a exportação da sessão. Apenas o bit presente/ausente é necessário a longo prazo.

Um dispositivo, uma presença

Este princípio é a única razão pela qual a plataforma coleta um identificador técnico do dispositivo. Sem ele, qualquer aluno presente poderia marcar a presença de terceiros ausentes. O identificador é session-scoped — nunca é usado para reconhecer o aluno entre disciplinas, entre semestres ou entre instituições.

Exportação SIGAA

Dois formatos de CSV são oferecidos no botão de download da sessão. Use cada um conforme a necessidade.

Formato SIGAA

Padrão

Importar diretamente no módulo Diário Eletrônico → Lançar Frequência em Planilha.

Colunas

MatriculaNome_DiscenteFaltasAssinatura

Padrão técnico — UTF-8 com BOM · delimitador ; (ponto-e-vírgula, convenção pt-BR) · quebra de linha CRLF · células com aspas, ponto-e-vírgula ou quebras de linha são automaticamente escapadas conforme RFC 4180.

Atenção — O SIGAA rejeita o arquivo se a contagem de colunas, o delimitador ou a codificação divergirem. Não edite o CSV no Excel antes de importar — algumas versões removem o BOM ao salvar.

Relatório completo

Auditoria

Registro forense interno do docente. Não importar no SIGAA — o arquivo tem mais colunas do que o SIGAA aceita.

Colunas

MatriculaNome_DiscenteData_AssinaturaHora_AssinaturaRegistrado_Em_ISODistancia_MetrosPrecisao_GPS_MetrosLatitudeLongitudeIP_DispositivoUser_AgentFingerprint_SHA256ID_Registro

Padrão técnico — Mesma codificação e delimitador da planilha SIGAA. Números decimais com vírgula (convenção pt-BR). Coordenadas com 6 casas (~0,1 m de precisão). Datas no padrão dd/mm/aaaa.

Atenção — Mantenha este arquivo em local seguro. Ele contém dados pessoais (IP, fingerprint) que devem ser tratados como confidenciais.

Passo a passo da importação no SIGAA

Baixe o CSV no formato SIGAA.
Acesse o Portal do Docente → Diário Eletrônico.
Menu “Lançar Frequência em Planilha” ou “Importação de Dados”.
Selecione a turma e a aula correspondente.
Faça upload do arquivo CSV exatamente como baixado.
Confirme os dados na visualização prévia.
Clique em Salvar.

Boas práticas

Capture a localização dentro da sala

No momento de criar a sessão, use o botão Usar minha localização posicionado próximo ao centro físico da sala. Coordenadas capturadas no corredor ou na entrada podem deixar alunos legítimos fora do raio.

Calibre o raio segundo a sala

Salas até 60 m² → 30 m. Salas maiores ou laboratórios em L → 50 m. Auditórios → 80–100 m. Raios muito grandes (>150 m) facilitam fraude em corredores e prédios vizinhos.

Use janelas curtas (5 minutos)

Quanto menor a janela, mais difícil o aluno presente repassar o link para colega ausente em tempo hábil. Em aulas longas, é mais seguro abrir uma segunda sessão no meio do encontro do que estender uma única.

Projete o QR Code, não envie o link

O link inclui o token que valida a sessão. Compartilhar o link no grupo da turma anula parte da proteção espacial — embora a Regra 1 ainda bloqueie quem estiver fora da sala. Projetar é a única forma de garantir que a posse do link foi adquirida fisicamente.

Exporte e confira antes de fechar o sistema

Baixe ambos os CSVs ao final da aula. O SIGAA pode ficar indisponível em horários de pico — ter o arquivo local evita retrabalho. O relatório completo é sua trilha de auditoria caso alguma presença seja contestada.

Verifique o histórico periodicamente

Sessões encerradas seguem disponíveis na aba Histórico. Use o painel para acompanhar a evolução da frequência ao longo do semestre.

Limitações conhecidas

Não há autenticação de docente no protótipo

Qualquer pessoa com o id de uma sessão pode encerrá-la via API. Aceitável para apresentação acadêmica; obrigatório resolver antes de uso institucional. Versão futura usará SSO/CAS da UFPE.

Navegadores de privacidade afetam a impressão digital

Brave Shields e Firefox com resistFingerprinting habilitado randomizam o canvas a cada visita. Isso anula a regra do dispositivo único, mas a Regra 3 (matrícula única) continua protegendo. O aluno verá Permissão de localização funcionando normalmente.

GPS indoor tem precisão limitada

Em prédios sem visada para o céu, o sinal de GPS é fraco. O navegador combina com Wi-Fi e torres de celular, mas a precisão pode cair para 20–40 m. Em prédios densos, considere aumentar o raio em 10–20 m.

Job automatizado de purga LGPD não está implementado

A política de descarte está definida no termo de consentimento, mas a anonimização das coordenadas e do IP após a exportação ainda é manual. O job automatizado é o próximo passo no roadmap.

Sem suporte multi-instância em produção

A entrega de eventos em tempo real (SSE) usa um EventEmitter em memória. Para escalar com múltiplos processos Node, será necessário trocar por Redis pub/sub ou similar.

Coordenadas falsificadas via DevTools

Um aluno com conhecimento técnico pode usar as ferramentas de desenvolvedor do Chrome para informar coordenadas fabricadas dentro do raio. Em celulares reais, isso exige privilégios de root. As coordenadas brutas ficam no relatório completo para auditoria posterior.

Dúvidas frequentes

O aluno pode marcar presença pelo navegador do desktop?

Tecnicamente sim, desde que a página seja servida em HTTPS e o desktop forneça coordenadas via GPS/Wi-Fi do dispositivo. Na prática, recomenda-se o uso do celular — a precisão é maior e o aluno está fisicamente próximo do QR Code.

O que acontece se o aluno fechar o navegador antes de ver o resultado?

A submissão ao servidor já terá ocorrido. A presença será registrada se passou nas regras. O aluno pode reabrir o link para conferir, mas a tentativa subsequente cairá em DUPLICATE_FINGERPRINT — comportamento esperado, presença já foi gravada.

O aluno pode marcar presença duas vezes na mesma aula?

Não. As regras 2 e 3 bloqueiam: a impressão digital do aparelho fica vinculada à matrícula na primeira submissão, e a matrícula fica vinculada à sessão. Qualquer nova tentativa retorna erro.

O que acontece se a permissão de localização for negada?

O servidor não recebe coordenadas e registra um RejectedAttempt com motivo GEO_DENIED. O aluno precisa reativar a permissão de localização nas configurações do navegador (no celular: ícone do cadeado na barra de endereço) e tentar novamente.

O sistema funciona offline?

Não. A submissão exige conexão para validar Haversine e gravar no banco. O aluno precisa estar em uma rede (Wi-Fi institucional ou dados móveis) no momento da marcação.

Quanto tempo o QR Code dura?

O padrão é 5 minutos, configurável de 1 a 180 minutos no momento de criação da sessão. Após o tempo, qualquer submissão retorna EXPIRED, mesmo se o link for compartilhado depois.

Posso exportar a planilha depois que a sessão for encerrada?

Sim. Sessões encerradas ou expiradas permanecem disponíveis na aba Histórico do painel. Os dois botões de exportação continuam funcionando indefinidamente — não há data de validade para o download.

O servidor armazena meu token do QR Code?

Não. O servidor armazena apenas o SHA-256 do token. O token bruto vive somente na URL e na sua tela durante a sessão. Mesmo um vazamento completo do banco de dados não permitiria a um atacante reconstruir tokens válidos.

Por que a Regra 1 não usa o IP do aluno?

Geolocalização por IP é trivialmente burlável com VPN ou proxy, e a precisão chega no máximo ao nível de cidade. Para validar presença em uma sala específica, é necessária a coordenada real do hardware, obtida via API de Geolocation do navegador.

O sistema considera atrasos como faltas?

Não. A coluna Faltas do CSV é sempre 0 para alunos presentes. Aluno que tentou marcar depois da expiração simplesmente não aparece na planilha SIGAA — o docente lança a falta manualmente conforme política da disciplina.

← Voltar ao painel Abrir nova sessão