Status do Projeto - ifpebj-ti/controle-acesso-veiculos GitHub Wiki
Status do Projeto
Versão do documento: 1.14
Data de referência: 13 de outubro de 2026
Baseline de código: tag anotada v0.3.0 no commit be49b67
Situação: MVP técnico integrado; homologação institucional e implantação em produção permanecem pendentes
Esta página é a referência canônica do estado atual. Os documentos detalhados
preservam decisões e evolução acadêmica, mas, quando um trecho histórico divergir
do estado implementado, prevalecem esta página, o código da main, as migrations
versionadas e os checks do GitHub Actions.
Resumo executivo
O projeto digitaliza o controle de acesso de veículos do IFPE Campus Belo Jardim. O MVP técnico possui frontend React, API ASP.NET Core em .NET 10, PostgreSQL 16, Entity Framework Core, containers e integração contínua.
Estão integrados os fluxos autenticados de entrada e saída geral, acessos em aberto, histórico, correção descritiva, encerramento excepcional auditado, frota, motoristas autorizados, utilizações institucionais, autorizações de eventos, resumo diário, administração de contas e consulta restrita da auditoria.
As superfícies de autenticação, navegação, operação, supervisão e administração usam o sistema visual semântico modernizado. O painel administrativo apresenta somente agregados reais da API — fluxo horário, categorias de acesso, tipos de veículo e série de 14 dias — sem fabricar valores quando não há registros. A ativação de tema escuro e a aceitação institucional do desenho permanecem etapas separadas.
A autenticação usa access token curto e renovação no servidor por cookie protegido, com rotação, revogação, proteção CSRF, logout, credencial temporária expirável e troca obrigatória no primeiro acesso. A autorização é aplicada pela API; esconder um botão no frontend não concede nem remove permissão.
As chaves que protegem cookies e tokens antifalsificação persistem em um key ring durável compartilhável, criptografado com certificado X.509 externo. A substituição do contêiner foi validada tecnicamente; a infraestrutura equivalente na OCI ainda não foi provisionada.
No dispositivo compartilhado da portaria, somente interação humana válida renova a atividade local. A interface encerra a sessão após 15 minutos de inatividade e o servidor mantém o limite absoluto de 12 horas, sem permitir que polling, renovação em segundo plano ou sincronização entre abas prolonguem o uso.
A aplicação ainda não está liberada para produção institucional. A homologação observada dos quatro perfis, as regras finais de identidade, o provisionamento do backup externo, o exercício de contingência, o HTTPS e a operação monitorada continuam registrados como pendências. Retenção, papéis e metas de continuidade já possuem direção operacional no PR #313. O PR #389 acrescentou um protocolo versionado para treinamento, observação paralela e piloto controlado, sem autorizar dados reais ou substituição das planilhas.
A ADR 0004, incorporada pelo PR #392, propõe uma topologia econômica e
reversível para a primeira homologação na OCI: um nó, entrada pública somente
por HTTPS e serviços internos não publicados. Ela não representa deploy. A
Issue #382 ainda exige conferir a tenancy, revisar custos, DNS, capacidade,
permissões e responsáveis antes de qualquer terraform plan conectado ou
apply autorizado.
O preflight da homologação OCI,
incorporado pelo PR #395, tornou essa verificação reproduzível e sanitizada. Ele
separa consulta somente leitura, revisão do terraform plan e autorização de
terraform apply, com três resultados possíveis: apto para planejar, bloqueado
ou necessidade de revisar a arquitetura. O roteiro ainda não foi executado e
não comprova capacidade, custo ou provisionamento.
Estado confirmado na main
| Área | Evidência atual | Situação |
|---|---|---|
| Backend | .NET 10, Clean Architecture adaptada e 262 testes automatizados | Implementado e validado na CI |
| Frontend | React, TypeScript, Vite, sistema visual semântico, carregamento sob demanda por rota, acessibilidade automatizada e 495 testes em 48 arquivos | Modernização das superfícies integrada e validada na CI; seletor de tema e aceitação institucional permanecem pendentes |
| Banco | PostgreSQL 16, 13 entidades e 16 migrations versionadas | Implementado; produção pendente |
| Segurança | STRIDE, autenticação renovável, key ring persistente protegido por X.509, RBAC no servidor, auditoria, rate limiting, CodeQL, Dependency Review, Trivy, SBOM, proveniência, ZAP passivo, Push Protection e correções automáticas do Dependabot | Controles técnicos implementados; provisionamento de produção e risco operacional residual documentados |
| Governança do repositório | SECURITY.md, CONTRIBUTING.md, CODEOWNERS para roteamento por área, revisão obrigatória por pares, invalidação de aprovação obsoleta, resolução de conversas e actions fixadas por SHA |
Implementado; não substitui governança operacional do ambiente institucional |
| Recuperação de dados | Dump custom, manifesto SHA-256, restauração isolada, rejeição de adulteração e baseline Terraform para bucket privado, Vault, IAM e alerta | Ensaio e configuração reproduzível implementados; recursos OCI e restauração externa ainda não comprovados |
| Continuidade | Cinco anos para registros/papel, 90 dias para logs, 35 dias para backups, RPO-alvo de 1 hora e RTO-alvo de 4 horas | Direção aprovada; OCI, PITR e exercício pendentes nas Issues #311 e #312 |
| Containers | Imagens de backend e frontend para AMD64 e ARM64, smoke test e publicação no GHCR | Cadeia técnica implementada |
| Execução versionada | Compose de produção consome imagens versionadas do GHCR sem recompilar no servidor | Implementado; ainda não implantado institucionalmente |
| Topologia OCI | ADR 0004 propõe nó único; o preflight define a verificação anterior ao plano | Direção e roteiro versionados; execução do preflight, provisionamento e custos pendentes na Issue #382 |
| Documentação da API | OpenAPI nativo e Swagger UI com Bearer JWT, identificadores, resumos e agrupamentos verificados, restritos a Development |
Implementado para desenvolvimento e QA; indisponível em produção |
| Release | v0.3.0 com imagens AMD64/ARM64 no GHCR e SBOM/proveniência verificáveis no GitHub Artifact Attestations |
Release técnica, não produção |
| Homologação e piloto | Roteiro dos quatro perfis e protocolo acompanhado disponíveis | Sessão observada, infraestrutura OCI e autorização de cada fase permanecem pendentes nas Issues #162, #382 e #388 |
Fluxos do MVP
Acesso geral
- busca ou cadastro mínimo de pessoa e veículo;
- registro de entrada com placa, condutor, categoria e objetivo;
- vínculo opcional com autorização de evento;
- consulta de acessos em aberto e registro normal de saída;
- histórico filtrado e correção descritiva auditada;
- encerramento excepcional com motivo e observação quando a saída não foi registrada no momento correto;
- horário observado opcional: quando não há fonte confiável, o sistema registra “horário desconhecido” e nunca cria uma estimativa.
Frota institucional
- manutenção controlada de veículos e motoristas autorizados;
- registro de saída e retorno, itinerário e quilometragem;
- consultas de utilizações abertas e históricas;
- separação entre cadastro de pessoa e autorização para conduzir.
Apoio e supervisão
- autorizações de eventos com período, regras e cotas protegidas contra consumo concorrente;
- resumo operacional diário sem exposição desnecessária de pessoas;
- administração de contas e credenciais temporárias;
- auditoria consultável somente por perfil autorizado.
Perfis atuais
| Perfil | Responsabilidade vigente no MVP |
|---|---|
| Porteiro | Opera os fluxos gerais e institucionais da portaria e consulta as informações necessárias ao atendimento |
| Vigilante | Possui o mesmo fluxo operacional do Porteiro quando o substitui |
| Setor de Transporte | Supervisiona, consulta históricos, corrige objetivo, categoria e observação com justificativa e auditoria e mantém frota e motoristas; não registra entrada, saída ou encerramento excepcional |
| Administrador | Gerencia contas, autorizações de eventos e operações técnicas excepcionais permitidas pela API |
A matriz continua revisável durante a homologação. O Administrador não deve ser usado como conta compartilhada da operação cotidiana.
Classificação das informações
| Classe | Significado neste projeto | Exemplos |
|---|---|---|
| Implementado | Existe na main e possui evidência técnica |
fluxos do MVP, autenticação, migrations, CI e containers |
| Confirmado institucionalmente | Decisão registrada a partir das conversas com os responsáveis | foco inicial em veículos; Vigilante substitui o Porteiro; Transporte supervisiona o processo |
| Hipótese em validação | Solução reversível levada ao usuário para avaliação | nomes de categorias, opções rápidas e organização de algumas telas |
| Pendente institucional | Exige responsável, regra ou infraestrutura do IFPE | identidade institucional, retenção, backup externo, contingência e ambiente final |
| Futuro | Não pertence ao MVP atual | pedestres, bicicletas, câmera, LPR, catraca e automação física |
Documentos canônicos
Esta é a única tabela de versões vigente. Se um rodapé histórico mencionar uma versão anterior, ele registra a evolução e não substitui esta relação.
| Documento | Versão vigente | Situação |
|---|---|---|
| Visão do Projeto | 0.2 | Visão consolidada; regras detalhadas continuam revisáveis |
| Processo Atual da Portaria | 0.5 | Levantamento dos formulários e do trabalho atual |
| Requisitos e Backlog | 0.4 | Requisitos sincronizados com o MVP; backlog vivo permanece nas Issues |
| MVP e Fluxo Digital | 0.1 | Recorte inicial preservado como baseline de produto |
| Regras de Negócio | 0.2 | Regras preliminares e rastreáveis |
| Análise de Concorrência | 0.4 | Pesquisa revisada; não cria requisito sem validação |
| Arquitetura de Software — arc42 | 2.4 | Arquitetura implementada, fundação técnica do frontend e topologia de homologação documentadas; produção pendente |
| Modelo de Dados | 1.2 | Modelo físico e histórico conceitual separados |
| Decisão de Stack Tecnológica | 0.5 | Stack implementada; implantação institucional pendente |
| Matriz de Ferramentas Técnicas | 0.3 | Ferramentas técnicas e cadeia de entrega documentadas |
| Segurança e Privacidade | 2.0 | Controles técnicos, continuidade aprovada e riscos residuais documentados |
| Modelagem de Ameaças | 3.6 | STRIDE sincronizado com os fluxos e o desenho OCI aprovado |
| Guia de Boas Práticas de Desenvolvimento Seguro | 1.1 | Baseline segura de desenvolvimento |
| Estratégia de Testes | 0.33 | Suítes, contraste semântico e barreiras da CI documentados |
| Guia de Execução, Configuração, Deploy e Operação | 0.29 | Local, CI, release, preflight OCI e direção de continuidade documentados; produção pendente |
| Manual de Uso | 2.5 | Uso do MVP técnico e correção supervisionada documentados; não autoriza operação real |
| Retenção, Backup e Continuidade | contínuo | Direção operacional aprovada; provisionamento e exercício pendentes |
| Observabilidade | contínuo | Instrumentação disponível; operação externa pendente |
Evidências da Unidade 1
Engenharia de Software
| Entrega exigida | Evidência verificável | Avaliação |
|---|---|---|
| Documento de Visão do Projeto | Visão do Projeto | Atendido |
| Análise de Concorrência | Análise de Concorrência | Atendido |
| Backlog do Produto e requisitos no Project | Requisitos e Backlog, Issues e Projects da organização | Atendido; Project exige acesso compatível da organização |
| Arquitetura e Modelagem de Dados | arc42, Modelo de Dados, solução backend e migrations | Atendido e superior ao mínimo documental |
Segurança
| Entrega exigida | Evidência verificável | Avaliação |
|---|---|---|
| Modelagem de Ameaças | Documento STRIDE, fonte revisável e modelo Threat Dragon | Atendido |
| Guia de Boas Práticas de Desenvolvimento Seguro | Guia na Wiki e fonte revisável | Atendido |
| Zero vulnerabilidades críticas aferidas pelo Dependabot | Dependabot e Dependency Review | Atendido: 0 alertas críticos abertos em 28/09/2026; evidência deve ser conferida novamente na entrega |
Infraestrutura
| Entrega exigida | Evidência verificável | Avaliação |
|---|---|---|
| Aplicação conteinerizada | Dockerfiles e Compose | Atendido |
| Guia de execução, configuração e operação | Guia de Execução e README | Atendido |
| Início da esteira CI/CD: lint, build, testes, imagem, scan e registry | Workflows, CI backend, CI frontend e containers | Atendido e ampliado com Trivy, SBOM, proveniência, multi-arquitetura, smoke test e GHCR |
Conclusão acadêmica: pelas evidências versionadas, os itens documentais e técnicos solicitados para a Unidade 1 estão atendidos. Essa conclusão não equivale a homologação operacional nem a autorização de produção.
A versão detalhada e revisável desta matriz está no repositório em
docs/validation/unit-1-readiness.md.
Pendências que não invalidam a Unidade 1
- Issue #162: homologação observada dos quatro perfis;
- Issues #266 e #267: identificador institucional no backend e no frontend;
- Issue #269: acesso excepcional após o fechamento da portaria;
- Issue #272: relatórios e exportação segura;
- Issue #275: estudantes autorizados a conduzir;
- Issue #30: retenção, backup externo, recuperação e contingência;
- Issue #382: ambiente econômico e seguro de homologação na OCI;
- Issue #100: reconciliação posterior à contingência;
- Issue #121: sincronização do Figma após homologação.
Pedestres e bicicletas permanecem como evolução futura na Issue #273. Câmeras, leitura automática de placas e controle físico também permanecem fora do MVP atual.
Produção institucional
Antes de uso real ainda será necessário, no mínimo:
- homologar os fluxos e permissões com representantes dos quatro perfis;
- definir ambiente, domínio, TLS, segredos e responsabilidades operacionais;
- provisionar backup externo, PITR e monitoramento conforme as decisões aprovadas;
- operar logs, métricas, alertas e resposta a incidentes;
- aplicar migrations de forma controlada, com backup e rollback revisados;
- exercitar recuperação e contingência na segunda unidade com os responsáveis;
- registrar aceite institucional e critérios de suporte.
O runbook do piloto acompanhado define quatro etapas após a preparação: treinamento com dados fictícios, observação paralela, piloto operacional controlado e encerramento. A etapa com dados operacionais reais só pode começar após autorização institucional e comprovação de infraestrutura, backup, contingência e suporte.
O arquivo infrastructure/docker/docker-compose.production.yml melhora a
reprodutibilidade ao consumir imagens versionadas do GHCR. Ele não substitui
essas decisões nem constitui um deploy realizado.
Linha do tempo resumida
| Período | Evolução preservada |
|---|---|
| Agosto de 2026 | Levantamento, visão, requisitos, arc42, modelo de dados, persistência e primeiros fluxos verticais |
| Final de agosto | Frota, motoristas, históricos, eventos, resumo operacional, testes PostgreSQL e cadeia inicial de containers |
| Início de setembro | Frontend integrado, acessibilidade, contas, auditoria, dados fictícios e roteiro de homologação |
| 13–16 de setembro | Sessão renovável, observabilidade, recuperação local e baseline passiva do OWASP ZAP |
| 21 de setembro | Release técnica v0.2.0, credenciais temporárias e troca obrigatória no primeiro acesso |
| 24 de setembro | Compose versionado de produção e encerramento excepcional auditado integrados à main |
| 29 de setembro | Release técnica v0.3.0, publicação GHCR somente por release e documentação da Unidade 1 consolidadas |
| 30 de setembro | Packages limpos de referrers OCI auxiliares; imagens SemVer preservadas e atestações mantidas no serviço do GitHub |
| 1º de outubro | Baseline reproduzível de backup protegido na OCI e protocolo de piloto operacional acompanhado incorporados à main; provisionamento e execução permanecem pendentes |
| 2 de outubro | ADR 0004 incorporada pelo PR #392 com topologia proposta, alternativas e gate de preflight para a homologação OCI; nenhum recurso criado |
| 3 de outubro | Roteiro de preflight OCI incorporado pelo PR #395, separando consulta somente leitura, revisão do plano e aplicação autorizada; execução ainda pendente |
| 3 de outubro | Correção descritiva supervisionada pelo Setor de Transporte integrada pelo PR #396, sem ampliar entrada, saída ou encerramento excepcional |
| 5 de outubro | Lint de artefatos gerados corrigido, tokens semânticos com testes de contraste incorporados e rotas autenticadas divididas para reduzir o carregamento inicial pelos PRs #398, #408 e #399 |
| 5 de outubro | Login adaptado a telas com pouca altura pelo PR #411, preservando dimensões dos controles e usando rolagem vertical natural, sem escala global; a aprovação institucional do desenho permanece pendente |
| 12–13 de outubro | Modernização de autenticação, navegação, operação, supervisão e administração incorporada pelos PRs #419, #420 e #426; agregados operacionais reais adicionados à API pelo PR #425; baseline frontend elevada a 495 testes em 48 arquivos |
O detalhamento histórico permanece verificável no histórico da Wiki, nas issues encerradas e nos pull requests incorporados.
Próximos passos recomendados
- concluir o treinamento e a homologação manual da Issue #162 com evidências sanitizadas;
- executar o preflight de conta, região, custo, DNS e responsáveis da Issue #382 sem publicar identificadores ou credenciais;
- revisar o plano Terraform e provisionar somente após autorização explícita e pelos gates das Issues #382 e #311;
- executar o piloto em fases conforme a Issue #388, sem antecipar dados reais;
- priorizar as decisões institucionais das Issues #266–#275;
- fechar a política de continuidade antes da reconciliação offline;
- sincronizar o Figma apenas depois dos fluxos aprovados.
Esta página deve ser atualizada após mudanças relevantes na main. Percentuais
de progresso, quando utilizados em apresentações, são estimativas e devem trazer
critério, evidência e incerteza; não substituem os estados verificáveis acima.