Home - ifpebj-ti/controle-acesso-veiculos GitHub Wiki

🚗 Controle de Acesso de Veículos

📍 Bem-vindo(a) à Wiki do Projeto Integrador — Controle de Acesso de Veículos

Sobre o projeto

Sistema para registrar, acompanhar e auditar o acesso de veículos ao IFPE, apoiando:

  • o setor de transporte,
  • os porteiros,
  • os guardas da instituição

na organização dos registros e na segurança do campus.

Esta wiki centraliza toda a documentação do projeto integrador: visão, requisitos, arquitetura, segurança, operação, testes e status das sprints.

Estado em 13/10/2026: o MVP técnico está integrado na main, com frontend, API .NET 10, PostgreSQL, 16 migrations e fluxos autenticados para acesso geral, frota, motoristas, eventos, resumo diário, contas e auditoria. A autenticação possui access token curto, renovação por cookie protegido, rotação, revogação, CSRF e logout. O ciclo de contas agora gera credenciais temporárias aleatórias, expiráveis e de uso único, obriga o titular a criar sua senha permanente antes das operações e permite redefinição administrativa auditada com revogação das sessões anteriores. A matriz de perfis continua aplicada no servidor: somente o Administrador mantém autorizações de eventos, enquanto os quatro perfis preservam a consulta necessária. O encerramento excepcional permite regularizar uma saída não registrada sem inventar horário e mantém motivo, responsável e auditoria. A sessão do tablet é encerrada após 15 minutos sem atividade humana ou ao atingir o limite absoluto de 12 horas; eventos técnicos em segundo plano não prolongam o acesso. O key ring que protege cookies e tokens antifalsificação persiste em armazenamento compartilhável, é criptografado com certificado X.509 externo e sobrevive à substituição da API; o provisionamento definitivo desse armazenamento e dos segredos na OCI permanece pendente. A suíte validada na integração reúne 262 testes de backend e 495 de frontend em 48 arquivos, além das verificações de acessibilidade e dos checks de CI. O frontend possui um contrato de tokens semânticos com regressões automatizadas de contraste para valores claros e escuros. Os valores escuros são apenas uma fundação técnica: nenhum seletor de tema está ativo. As páginas autenticadas passaram a ser carregadas sob demanda, reduzindo o JavaScript inicial sem elevar o limite de aviso do Vite. A modernização visual foi incorporada nas superfícies de autenticação, navegação, operação, supervisão e administração pelos PRs #419, #420 e #426. Ela preserva contratos, permissões e fluxos existentes, utiliza componentes e tokens semânticos compartilhados e mantém acessibilidade automatizada. O tema escuro ainda não foi ativado e a aceitação institucional continua separada da integração técnica. O resumo administrativo usa apenas agregados reais fornecidos pela API: fluxo horário, categorias de acesso, tipos de veículo e série de 14 dias. Respostas vazias permanecem vazias, sem números fictícios, nomes, placas ou documentos. Para desenvolvimento e QA, a API também publica o contrato em /openapi/v1.json e a interface Swagger em /swagger, ambos restritos ao ambiente Development; essa exploração manual não substitui testes automatizados, autorização no servidor ou homologação institucional. O ensaio local de recuperação gera manifesto SHA-256 para cada dump, verifica sua integridade antes da restauração isolada e rejeita cópias adulteradas na CI. O PR #313 definiu cinco anos para registros e papel, 90 dias para logs, 35 dias para backups, RPO-alvo de uma hora e RTO-alvo de quatro horas. Object Storage privado, Vault, instance principal e separação IAM estão aprovados no desenho. O PR #381 incorporou uma baseline Terraform revisável e um publicador por instance principal, com bucket privado, criptografia gerenciada, retenção, papéis IAM separados e alerta de ausência. Esses recursos ainda não foram provisionados nem exercitados na tenancy institucional. A ADR 0004, incorporada pelo PR #392, propõe para o primeiro piloto uma implantação reversível de nó único, com somente HTTPS público e administração temporária e auditável. PostgreSQL, backend, Docker e interfaces internas não serão publicados. Nenhum recurso foi criado: saldo, validade, região, capacidade, DNS, custos e responsáveis ainda precisam ser conferidos no preflight da Issue #382. Arm e benefícios gratuitos são candidatos sujeitos à conta e à região, não garantias de disponibilidade ou custo zero. O preflight da homologação OCI, incorporado pelo PR #395, organiza a consulta somente leitura e separa explicitamente essa verificação de terraform plan e terraform apply. O roteiro prevê os resultados “apto para planejar”, “bloqueado” ou “revisar arquitetura”, mas ainda não foi executado; nenhum recurso ou custo foi criado por essa documentação.

A cadeia de entrega constrói e analisa imagens de backend e frontend para linux/amd64 e linux/arm64, publica manifestos no GHCR e registra proveniência e SBOMs assinados no GitHub Artifact Attestations. A release técnica v0.3.0 foi publicada a partir do commit be49b67, com tags semânticas verificadas no GHCR, smoke test integrado e baseline passiva do OWASP ZAP aprovados na execução 36647783284. Pushes comuns na main continuam sendo validados, mas somente tags de release revisadas publicam novas imagens nos packages principais. Desde a Issue #325, as atestações não são duplicadas como versões OCI sha256-... no GHCR. Caches efêmeros de Pull Requests encerrados são removidos automaticamente, e os builds consultam as imagens-base atuais antes de reutilizar cache. O backend também aplica correções OpenSSL já publicadas quando a base oficial ainda não foi reconstruída, mantendo o bloqueio do Trivy para falhas altas corrigíveis. O ZAP cobre somente a superfície pública e não substitui teste autenticado ou pentest. Por decisão arquitetural registrada na Issue #219, o projeto usa GitHub Code Quality e os controles nativos existentes, sem depender do SonarQube Cloud.

Integração técnica não significa aprovação institucional ou prontidão para produção. A recuperação de acesso do MVP foi definida na Issue #220: dois Administradores funcionais entregam diretamente ao titular a credencial temporária gerada pelo servidor. A homologação observada desse procedimento e dos quatro perfis permanece na Issue #162. A Issue #30 continua aberta para a revisão arquivística, backup externo, PITR e exercício de contingência; as implementações estão rastreadas nas Issues #311 e #312. O protocolo de piloto acompanhado, incorporado pelo PR #389, separa treinamento com usuários reais, observação em paralelo, piloto operacional controlado e produção. Ele não autoriza dados reais nem substituição das planilhas: o avanço depende dos gates das Issues #30, #162, #311, #382 e #388. HTTPS, segredos, monitoramento operado e deploy institucional também continuam pendentes. Consulte o Status do Projeto para distinguir entregas concluídas, hipóteses em validação e itens planejados.

A matriz de evidências da Unidade 1 relaciona cada entrega acadêmica ao documento, código ou workflow que permite verificá-la.

👥 Equipe do projeto

Nome Função Responsabilidades
Raíssa Beatriz Front-end / UX/UI e DevOps / Infra / QA Desenvolvimento da interface, organização da experiência do usuário, apoio na infraestrutura, automação de processos, testes e validação das entregas.
José Ernandes Back-end / DB e DevOps / Infra / QA Desenvolvimento da API, modelagem e integração com o banco de dados, apoio na infraestrutura, automação de processos, testes e validação das entregas.

📄 Documentação

Projeto

Produto

Arquitetura

Segurança

Operação

Qualidade