Projeto: Controle de Acesso de Veículos
Instituição: Instituto Federal de Pernambuco — Campus Belo Jardim
Disciplina: Projeto Integrador — Práticas Reais de Software e Segurança
Equipe: José Ernandes Gonçalves Costa; Raíssa Beatriz Marinho dos Santos
Cliente inicial: Eurico Lopes — Setor de Transporte
Versão: 2.4
Status: Arquitetura, fluxos funcionais do MVP e controles técnicos principais implementados; homologação e implantação institucional permanecem em evolução
Data de referência: 5 de outubro de 2026
Estrutura documental: arc42 adaptado ao escopo do projeto
Issue relacionada: #9 — Definir arquitetura inicial
Issue de implementação: #16 — Estruturar monorepo inicial
Documentos relacionados: MVP e Fluxo Digital v0.1; Requisitos e Backlog v0.3; Regras de Negócio v0.1; Modelo de Dados v0.3; Segurança e Privacidade v0.1; Estratégia de Testes v0.3; Decisão de Stack Tecnológica v0.3; Matriz de Ferramentas Técnicas v0.3

Baseline arquitetural — atualizada em 05/10/2026: as quatro camadas do backend, o frontend funcional, PostgreSQL via EF Core, 16 migrations, containers, CI, autenticação e sessões renováveis no servidor, provisionamento de contas, os fluxos geral e institucional, a autorização de eventos e o resumo operacional diário estão na main. O fluxo segue API → Application → Domain, com persistência em Infrastructure, transação e restrição concorrente no PostgreSQL. O consumo de cotas de evento bloqueia a linha do evento durante a reserva, impedindo ultrapassagem silenciosa por requisições simultâneas. O resumo diário segue API → Application → Infrastructure, converte o dia local configurado para um intervalo UTC semiaberto e executa agregações no PostgreSQL sem carregar entidades completas nem criar uma tabela de fechamento. As telas funcionais, correção descritiva auditada, catálogo e operação institucional, consulta da auditoria e renovação segura da sessão no frontend também estão integrados. Correções de identidade/tempo, homologação e produção ainda não estão prontas. As fronteiras de confiança e riscos da arquitetura agora estão detalhados em Modelagem de Ameaças. O arc42 completo abaixo permanece como documento arquitetural principal.

Este documento apresenta a arquitetura do sistema Controle de Acesso de Veículos do IFPE Campus Belo Jardim.

A arquitetura segue as doze seções principais do arc42, adaptadas ao escopo do projeto. A seção 13 possui finalidade administrativa e registra status, validação e próximas etapas.

O objetivo é orientar decisões de estrutura, componentes, segurança, dados, testes, implantação e evolução, considerando a stack tecnológica definida e o estado real da implementação.

A arquitetura não representa um sistema completo. A estrutura do monorepo, PostgreSQL, autenticação com renovação segura integrada, fluxos funcionais do MVP e telas integradas estão implementados, mas a homologação institucional e a operação de produção ainda precisam ser concluídas.

O documento utiliza como base:

• Processo Atual da Portaria — versão 0.4.
• Visão do Projeto — versão 0.2.
• Requisitos e Backlog — versão 0.3.
• MVP e Fluxo Digital — versão 0.1.
• Regras de Negócio — versão 0.1.
• Modelo de Dados — versão 0.3.
• Segurança e Privacidade — versão 0.1.
• Estratégia de Testes — versão 0.3.
• Decisão de Stack Tecnológica — versão 0.3.
• Feedback mais recente do cliente e dos participantes da apresentação.
• Formulários nº 01 e nº 02 como referência principal do MVP.

O processo atual de controle de entrada, saída e movimentação de veículos é realizado principalmente por formulários físicos preenchidos na portaria.

Esse processo apresenta dificuldades relacionadas a:

• Consulta demorada de registros antigos.
• Dependência de documentos físicos.
• Arquivamento e conferência manuais.
• Repetição de preenchimentos.
• Erros que exigem refazer formulários.
• Ausência de histórico digital de correções.
• Dificuldade para localizar veículos, placas, condutores e motoristas.
• Dificuldade para identificar o motorista associado a uma viagem, multa ou ocorrência.
• Dificuldade de continuidade durante a troca de turno.
• Uso de listas desatualizadas para verificar informações relacionadas ao acesso.
• Dificuldade para identificar veículos sem saída ou veículos institucionais sem retorno.

A solução deve digitalizar e melhorar o fluxo de controle de veículos, preservando os controles que possuem finalidade operacional, administrativa, de consulta ou rastreabilidade.

O sistema não deve simplesmente transformar todos os formulários em telas. Cada campo e etapa deve ser avaliado conforme:

• Finalidade.
• Necessidade operacional.
• Frequência de uso.
• Impacto no atendimento.
• Sensibilidade do dado.
• Necessidade de consulta posterior.
• Necessidade de auditoria.

O MVP deverá suportar preliminarmente:

• Interface web para usuários autorizados.
• Autenticação básica de usuários.
• Perfis básicos de acesso.
• Cadastro de veículos.
• Cadastro de pessoas relacionadas a veículos.
• Relação entre pessoas e veículos.
• Registro de entrada.
• Registro de saída.
• Registro de objetivo.
• Registro de condutor.
• Registro de motorista institucional.
• Registro de quilometragem de saída e entrada.
• Registro de itinerário institucional.
• Consulta por placa, veículo, condutor, motorista e período.
• Consulta de acessos sem saída.
• Consulta de veículos institucionais sem retorno.
• Conferência pelo Setor de Transporte.
• Correções controladas.
• Histórico de alterações.
• Registro do usuário responsável pelas operações.

• Controle geral de pedestres.
• Controle geral de visitantes sem veículo.
• Caminhadas sem veículo.
• Controle geral de servidores sem relação com veículos.
• Controle geral de terceirizados sem relação com veículos.
• Gestão geral de crachás.
• Reconhecimento facial.
• Reconhecimento automático de placas.
• Integração com câmeras.
• Integração com sensores.
• Integração com catraca ou cancela.
• Liberação automática de acesso.
• Controle de vagas.
• Relatórios gerenciais avançados.
• Integração com sistemas institucionais.
• Migração completa dos Formulários nº 03 a nº 07.

flowchart LR
    Condutor[Condutor ou Motorista]
    Porteiro[Porteiro]
    Vigilante[Vigilante]
    Transporte[Setor de Transporte]
    Seguranca[Setor de Segurança]
    SEGAI[SEGAI]
    Sistema[Sistema de Controle de Acesso de Veículos]

    Condutor -->|Informações do veículo e objetivo| Porteiro
    Porteiro -->|Registra entrada e saída| Sistema
    Vigilante -->|Dá continuidade e consulta registros| Sistema
    Transporte -->|Confere, consulta e corrige conforme permissão| Sistema
    Seguranca -->|Comunica restrições e atividades| Porteiro
    SEGAI -.->|Fluxo futuro de residentes| Sistema
    Sistema -->|Consultas e histórico| Transporte

flowchart LR
    Usuario[Usuário autenticado]
    Navegador[Navegador web]
    Frontend[Frontend React + TypeScript + Vite + Tailwind CSS]
    Backend[Backend ASP.NET Core Web API + .NET 10]
    Banco[(PostgreSQL)]
    Backup[Backup local verificável]
    OCI[VM Linux na OCI]

    Usuario --> Navegador
    Navegador --> Frontend
    Frontend -->|HTTP/HTTPS futuro| Backend
    Backend --> Banco
    Banco --> Backup
    OCI --> Frontend
    OCI --> Backend
    OCI --> Banco

• Interface web para usuários autorizados.
• Fluxo de entrada e saída geral de veículos.
• Fluxo de saída e retorno de veículos institucionais.
• Consultas operacionais e históricas básicas.
• Autenticação e perfis básicos.
• Registro de usuário responsável.
• Correção com justificativa e auditoria.
• Persistência em PostgreSQL.
• Backend em ASP.NET Core Web API com .NET 10.
• Frontend em React, TypeScript, Vite e Tailwind CSS 4.
• Contingência a ser definida.

• Registro de recusa de acesso.
• Registro de permanência excepcional.
• Registro simplificado de mototáxi.
• Registro simplificado de evento com veículo.
• Veículos de discentes residentes.
• Ocorrência simples associada a um acesso.
• Exportações autorizadas.
• Relatórios básicos.

• Controle de pessoas sem veículo.
• Reconhecimento de placas.
• Integrações com câmeras, sensores e catraca.
• Controle de estacionamento.
• Liberação automática de acesso.
• Gestão de crachás.
• Reconhecimento facial.
• Integração obrigatória com sistemas institucionais.

A solução será uma aplicação web em formato de monólito modular, utilizando Clean Architecture adaptada ao MVP.

A stack de aplicação será:

• React.
• TypeScript.
• Vite.
• Tailwind CSS 4.
• ASP.NET Core Web API.
• C#.
• .NET 10 e net10.0.
• PostgreSQL.
• Entity Framework Core.
• Entity Framework Core Migrations.

A infraestrutura e entrega utilizarão:

• Docker.
• Docker Compose.
• GitHub Actions.
• VM Linux na OCI em etapa futura.

Interface Web — React + TypeScript + Vite + Tailwind CSS
    ↓
ASP.NET Core Web API — C# / .NET 10
    ↓
Application e regras de negócio
    ↓
Domain
    ↓
Infrastructure — EF Core
    ↓
PostgreSQL

A estrutura do backend utiliza os projetos API, Application, Domain e Infrastructure. O frontend React também está estruturado por componentes, funcionalidades, páginas, serviços, tipos e testes, conforme o código integrado à main.

A arquitetura em camadas e o monólito modular são recomendados porque:

• Separam interface, regras de negócio e persistência.
• Facilitam testes por componente.
• Permitem alterar regras sem reescrever a interface.
• Centralizam autorização e auditoria.
• Favorecem manutenção e evolução.
• São adequados ao porte do MVP.
• Evitam a complexidade prematura de microserviços.
• São compatíveis com Docker, GitHub Actions e OCI.
• Aproveitam a experiência da equipe em C#, .NET e bancos relacionais.

A arquitetura ainda não define:

• Biblioteca definitiva de componentes frontend.
• Cliente HTTP do frontend.
• Gerenciamento de estado do frontend.
• Biblioteca específica de autenticação.
• Estratégia final de sessão ou token.
• Proxy reverso.
• Ferramentas de logs, métricas e traces.
• Estratégia final de backup.
• Topologia definitiva de produção e eventual alta disponibilidade na OCI.
• Provisionamento e parâmetros finais do ambiente de homologação.
• Domínio.
• Certificado HTTPS.
• Configuração final do banco em produção.

O ambiente de desenvolvimento utiliza o SDK .NET 10 e o projeto backend utiliza net10.0.

A equipe propõe manter:

.NET 10
Target Framework: net10.0

A decisão deverá ser validada pelos professores e mantida compatível com a infraestrutura de desenvolvimento, os containers e a OCI.

flowchart TB
    UI[Interface Web<br/>React + TypeScript + Vite + Tailwind CSS]
    API[API<br/>ASP.NET Core Web API + .NET 10]
    Auth[Autenticação e Autorização futuras]
    Access[Serviço de Registros de Acesso]
    Institutional[Serviço de Veículos Institucionais]
    People[Serviço de Pessoas e Veículos]
    Query[Serviço de Consultas e Conferência]
    Audit[Serviço de Auditoria]
    Repositories[Repositórios]
    EF[Entity Framework Core futuro]
    Database[(PostgreSQL futuro)]

    UI --> API
    API --> Auth
    API --> Access
    API --> Institutional
    API --> People
    API --> Query
    API --> Audit

    Auth --> Repositories
    Access --> Repositories
    Institutional --> Repositories
    People --> Repositories
    Query --> Repositories
    Audit --> Repositories

    Repositories --> EF
    EF --> Database

Responsabilidade: apresentar telas e fluxos para usuários autenticados, coletar dados, exibir validações e permitir consultas conforme o perfil.

Tecnologias: React, TypeScript, Vite e Tailwind CSS 4.

Estado atual: frontend funcional organizado por páginas, features, componentes, serviços e contratos. As rotas autenticadas são carregadas sob demanda, e o contrato de tokens semânticos separa a paleta institucional das funções de interface. Valores claros e escuros possuem testes de contraste, mas o tema escuro ainda não é ativado pela aplicação. Migrações visuais incrementais e homologação permanecem em evolução.

Responsabilidades previstas:

• Tela de autenticação.
• Registro de entrada.
• Registro de saída.
• Registro de saída e retorno institucional.
• Consulta por placa, veículo, condutor, motorista e período.
• Consulta de registros em aberto.
• Consulta de veículos institucionais sem retorno.
• Correção autorizada.
• Conferência pelo Setor de Transporte.
• Gestão de usuários e perfis, quando autorizada.

Responsabilidade: receber requisições da interface, validar autorização, coordenar casos de uso, aplicar regras de negócio e retornar resultados.

Tecnologias: ASP.NET Core Web API, C# e .NET 10.

Estado atual: API autenticada com os fluxos funcionais do MVP implementados; homologação institucional e evolução pós-MVP permanecem pendentes.

Responsabilidades previstas:

• Expor operações da aplicação.
• Validar usuário autenticado.
• Encaminhar operações aos serviços de negócio.
• Validar permissões do perfil.
• Tratar erros de aplicação.
• Garantir que ações relevantes gerem auditoria.

Responsabilidade: controlar identidade e permissões dos usuários.

Estado atual: autenticação renovável, contas individuais, credenciais temporárias, revogação e autorização por políticas implementadas; homologação institucional pendente.

Responsabilidades previstas:

• Validar credenciais.
• Criar sessão ou token de acesso.
• Verificar se o usuário está ativo.
• Verificar perfil e permissões.
• Associar o usuário autenticado às operações.
• Impedir acesso a funções não autorizadas.

Responsabilidade: manter cadastros de pessoas e veículos ligados ao fluxo veicular.

Estado atual: cadastro mínimo, normalização, vínculo e busca de recorrentes implementados nos fluxos do MVP.

Responsabilidades previstas:

• Cadastrar e localizar pessoa relacionada.
• Cadastrar e localizar veículo.
• Associar pessoa e veículo.
• Manter situação ativa ou inativa.
• Evitar coleta de dados sem finalidade aprovada.
• Permitir consulta por placa ou outras informações validadas.

Responsabilidade: controlar entradas, saídas, acessos abertos e situações relacionadas ao fluxo geral de veículos.

Estado atual: entrada, saída normal, acessos abertos, histórico, correção descritiva e encerramento excepcional implementados.

Responsabilidades previstas:

• Registrar entrada.
• Registrar saída.
• Associar condutor, veículo, categoria e objetivo.
• Identificar registros em aberto.
• Sinalizar duplicidade ou inconsistências.
• Permitir consulta de acessos conforme perfil.
• Encaminhar correções para auditoria.

Responsabilidade: controlar o uso de veículos institucionais, incluindo saída, retorno, motorista, quilometragem e itinerário.

Estado atual: frota, motoristas autorizados, saída, retorno, histórico e quilometragem implementados.

Responsabilidades previstas:

• Registrar saída institucional.
• Associar motorista ao veículo.
• Registrar quilometragem de saída.
• Registrar itinerário.
• Localizar viagem em uso.
• Registrar retorno.
• Registrar quilometragem de entrada.
• Sinalizar quilometragem inconsistente.
• Identificar veículo institucional sem retorno.

Responsabilidade: permitir consultas operacionais e apoiar a conferência do Setor de Transporte.

Estado atual: consultas operacionais e históricas implementadas conforme as permissões atuais; relatórios e exportação segura permanecem na Issue #272.

Responsabilidades previstas:

• Consultar por placa.
• Consultar por veículo.
• Consultar por condutor.
• Consultar por motorista.
• Consultar por data ou período.
• Consultar acessos sem saída.
• Consultar veículos institucionais sem retorno.
• Exibir histórico de alterações conforme permissão.
• Apoiar conferência de registros.

Responsabilidade: registrar operações relevantes realizadas por usuários autorizados.

Estado atual: auditoria transacional implementada nos casos de uso relevantes do MVP e consulta restrita ao Administrador; cobertura de novos fluxos deve ser revisada continuamente.

Responsabilidades previstas:

• Registrar criação.
• Registrar alteração.
• Registrar correção.
• Registrar encerramento.
• Registrar conferência, se aplicável.
• Armazenar usuário, data, horário, valor anterior, novo valor e motivo quando aplicável.

Responsabilidade: persistir e recuperar dados sem expor detalhes de banco às regras de negócio.

Tecnologias previstas: Entity Framework Core e PostgreSQL.

Estado atual: EF Core, DbContext, configurações Fluent API, stores transacionais e 16 migrations implementados em Infrastructure.

Responsabilidades previstas:

• Operações de leitura e escrita.
• Respeito às chaves, restrições e relacionamentos.
• Suporte a transações.
• Aplicação de exclusão lógica, quando definida.
• Consultas filtradas e paginadas, quando necessário.
• Execução de migrations versionadas.

Responsabilidade: armazenar registros operacionais, cadastros, relacionamentos, perfis e auditoria.

Tecnologia: PostgreSQL.

Estado atual: PostgreSQL 16 integrado à aplicação, com schema dbo, constraints, índices e migrations versionadas.

Entidades preliminares:

• Pessoa.
• Veículo.
• PessoaVeiculo.
• CategoriaAcesso.
• RegistroAcesso.
• UsoVeiculoInstitucional.
• Usuário.
• Perfil.
• Auditoria.

sequenceDiagram
    actor Operador as Porteiro ou Vigilante
    participant UI as React + TypeScript
    participant API as ASP.NET Core Web API
    participant Auth as Autorização
    participant Access as Serviço de Acesso
    participant EF as Entity Framework Core
    participant DB as PostgreSQL
    participant Audit as Auditoria

    Operador->>UI: Inicia registro de entrada
    UI->>API: Envia dados da entrada
    API->>Auth: Valida usuário e permissão
    Auth-->>API: Usuário autorizado
    API->>Access: Registra entrada
    Access->>EF: Persiste pessoa e veículo
    EF->>DB: Salva dados
    Access->>EF: Cria RegistroAcesso aberto
    EF->>DB: Salva registro
    Access->>Audit: Registra criação
    Audit->>DB: Salva auditoria
    API-->>UI: Confirmação do registro

Resultado esperado:

• O acesso fica registrado com data, horário, veículo, condutor, objetivo, categoria e usuário responsável.
• O registro permanece aberto até a saída, salvo fluxo excepcional validado.
• O sistema aplica somente os campos obrigatórios aprovados para a categoria.

Situação: Backend e frontend integrados; hipóteses operacionais permanecem revisáveis na homologação.

sequenceDiagram
    actor Operador as Porteiro ou Vigilante
    participant UI as React + TypeScript
    participant API as ASP.NET Core Web API
    participant Auth as Autorização
    participant Access as Serviço de Acesso
    participant EF as Entity Framework Core
    participant DB as PostgreSQL
    participant Audit as Auditoria

    Operador->>UI: Localiza acesso aberto
    UI->>API: Solicita registros por placa ou veículo
    API->>Auth: Valida usuário e permissão
    Auth-->>API: Usuário autorizado
    API->>Access: Localiza registro aberto
    Access->>EF: Consulta RegistroAcesso
    EF->>DB: Busca registro
    DB-->>EF: Retorna registro
    EF-->>Access: Registro encontrado
    Access-->>API: Registro disponível
    API-->>UI: Exibe acesso aberto
    Operador->>UI: Confirma saída
    UI->>API: Envia encerramento
    API->>Access: Registra data, hora e status
    Access->>EF: Atualiza RegistroAcesso
    EF->>DB: Salva alteração
    Access->>Audit: Registra encerramento
    Audit->>DB: Salva auditoria
    API-->>UI: Confirma saída registrada

Resultado esperado:

• A saída encerra o acesso aberto.
• O usuário responsável pela saída é rastreável.
• Uma saída duplicada deve ser impedida ou sinalizada.
• Caso não exista entrada correspondente, o comportamento deve seguir procedimento ainda pendente de validação.

Situação: Backend e frontend integrados; encerramento excepcional auditado foi acrescentado pela Issue #271.

sequenceDiagram
    actor Operador as Usuário autorizado
    participant UI as React + TypeScript
    participant API as ASP.NET Core Web API
    participant Institutional as Serviço Institucional
    participant EF as Entity Framework Core
    participant DB as PostgreSQL
    participant Audit as Auditoria

    Operador->>UI: Inicia saída institucional
    UI->>API: Envia veículo, motorista, km e itinerário
    API->>Institutional: Valida e registra saída
    Institutional->>EF: Cria viagem em uso
    EF->>DB: Salva UsoVeiculoInstitucional
    Institutional->>Audit: Registra saída
    Audit->>DB: Salva auditoria
    API-->>UI: Confirma saída

    Operador->>UI: Localiza veículo em uso
    UI->>API: Envia retorno com km e horário
    API->>Institutional: Registra retorno
    Institutional->>Institutional: Valida quilometragem
    Institutional->>EF: Atualiza viagem como concluída
    EF->>DB: Salva retorno
    Institutional->>Audit: Registra retorno
    Audit->>DB: Salva auditoria
    API-->>UI: Confirma retorno

Resultado esperado:

• Uma saída institucional contém veículo, motorista, data, horário, quilometragem e itinerário.
• Um retorno completa horário e quilometragem de entrada.
• Quilometragem de entrada inferior à de saída deve ser sinalizada e somente tratada por correção autorizada.
• O vínculo com RegistroAcesso pode existir, mas é opcional no modelo atual.

Situação: Backend e frontend integrados; regras institucionais finais permanecem em homologação.

sequenceDiagram
    actor Usuario as Usuário autorizado
    participant UI as React + TypeScript
    participant API as ASP.NET Core Web API
    participant Auth as Autorização
    participant Query as Serviço de Consultas
    participant EF as Entity Framework Core
    participant DB as PostgreSQL

    Usuario->>UI: Informa filtros de consulta
    UI->>API: Solicita registros
    API->>Auth: Valida perfil e permissões
    Auth-->>API: Consulta autorizada
    API->>Query: Processa filtros
    Query->>EF: Executa consulta
    EF->>DB: Consulta registros
    DB-->>EF: Retorna dados
    EF-->>Query: Retorna resultado
    Query-->>API: Resultado filtrado
    API-->>UI: Exibe dados permitidos

Resultado esperado:

• Usuários consultam somente dados permitidos por seus perfis.
• O Setor de Transporte consegue pesquisar por placa, veículo, condutor, motorista e período.
• Registros históricos são recuperados sem consulta manual aos arquivos físicos.

Situação: Consultas gerais e institucionais implementadas; relatórios e exportação segura permanecem na Issue #272.

sequenceDiagram
    actor Usuario as Usuário autorizado
    participant UI as React + TypeScript
    participant API as ASP.NET Core Web API
    participant Auth as Autorização
    participant Domain as Regras de Negócio
    participant EF as Entity Framework Core
    participant DB as PostgreSQL
    participant Audit as Auditoria

    Usuario->>UI: Seleciona registro para correção
    UI->>API: Envia campo, novo valor e motivo
    API->>Auth: Verifica permissão
    Auth-->>API: Correção autorizada
    API->>Domain: Valida correção
    Domain->>EF: Preserva valor anterior
    EF->>DB: Atualiza registro
    Domain->>Audit: Cria auditoria
    Audit->>DB: Salva valor anterior, novo valor e motivo
    API-->>UI: Confirma correção

Resultado esperado:

• Somente usuários autorizados realizam correções.
• O motivo da correção é armazenado.
• O valor anterior permanece disponível na auditoria.
• A alteração pode ser conferida posteriormente.

Situação: Correção descritiva do acesso geral implementada e auditada; correções de identidade, horários e fluxo institucional dependem de escopo próprio.

flowchart TD
    Falha[Falha de rede ou sistema]
    Decisao{Procedimento de contingência aprovado?}
    Temporario[Registrar temporariamente no meio definido]
    Comunicar[Comunicar Setor de Transporte, quando aplicável]
    Sistema[Aplicação disponível novamente]
    Lancar[Lançar registro posteriormente]
    Auditoria[Registrar justificativa e auditoria]

    Falha --> Decisao
    Decisao -->|Sim| Temporario
    Decisao -->|Não definido| Comunicar
    Temporario --> Comunicar
    Comunicar --> Sistema
    Sistema --> Lancar
    Lancar --> Auditoria

Situação: Procedimento operacional pendente de validação.

flowchart TB
    Portaria[Computador ou tablet da portaria]
    Transporte[Computador do Setor de Transporte]
    Admin[Dispositivo administrativo]
    Rede[Rede institucional ou internet]
    OCI[VM Linux na OCI futura]
    Proxy[Proxy reverso futuro]
    Frontend[Container frontend futuro]
    Backend[Container backend futuro]
    Banco[(PostgreSQL futuro)]
    Backup[Backup local verificável]
    Observabilidade[Logs, métricas e traces futuros]

    Portaria --> Rede
    Transporte --> Rede
    Admin --> Rede
    Rede --> OCI
    OCI --> Proxy
    Proxy --> Frontend
    Proxy --> Backend
    Backend --> Banco
    Banco --> Backup
    OCI -.-> Observabilidade

controle-acesso-veiculos/
├── .github/
│   └── workflows/
│       ├── ci-backend.yml
│       └── ci-frontend.yml
├── infrastructure/
│   └── docker/
│       ├── backend/
│       │   └── Dockerfile
│       ├── frontend/
│       │   ├── Dockerfile
│       │   └── nginx.conf
│       └── docker-compose.yml
├── src/
│   ├── backend/
│   │   ├── ControleAcessoVeiculos.slnx
│   │   ├── ControleAcessoVeiculos.API/
│   │   ├── ControleAcessoVeiculos.Application/
│   │   ├── ControleAcessoVeiculos.Domain/
│   │   └── ControleAcessoVeiculos.Infrastructure/
│   └── frontend/
│       ├── src/
│       ├── package.json
│       ├── package-lock.json
│       ├── vite.config.ts
│       └── eslint.config.js
├── .editorconfig
├── .gitignore
├── LICENSE
└── README.md

• A solução deve poder ser acessada por navegador.
• A infraestrutura definitiva ainda precisa ser confirmada.
• O funcionamento inicial não depende de catraca, câmera ou sensor.
• A aplicação deve ser compatível com conteinerização.
• A implantação futura deverá utilizar Linux e considerar OCI.
• O backend deverá ser compatível com execução em container Linux.
• O banco deverá ser executado conforme estratégia aprovada.

O sistema deverá exigir autenticação para operações internas.

Cada usuário deverá possuir uma conta associada a uma pessoa e a um perfil. A senha deverá ser armazenada somente como hash.

O backend usa PasswordHasher do ASP.NET Core Identity, JWT curto e sessão renovável controlada pelo servidor. O frontend mantém o access token somente em memória, restaura e renova a sessão por cookie opaco HttpOnly, aplica proteção CSRF e coordena renovação e encerramento entre abas. O key ring do ASP.NET Core Data Protection fica em armazenamento durável compartilhável, com discriminador estável e XML protegido por certificado X.509 fornecido externamente; uma configuração incompleta falha de forma fechada em produção. Os tempos e a política operacional final ainda precisam de validação institucional, e o armazenamento compartilhado e o serviço de segredos ainda precisam ser provisionados na OCI.

Situação: Implementada e integrada tecnicamente; validação institucional dos tempos permanece pendente.

O acesso às operações deverá ser controlado por perfil e, futuramente, por permissões mais detalhadas se necessário.

Perfis preliminares:

• Porteiro.
• Vigilante.
• Setor de Transporte.
• Setor de Segurança.
• SEGAI.
• Administrador.

A matriz definitiva de permissões permanece pendente.

Operações relevantes deverão registrar:

• Usuário responsável.
• Data e horário.
• Entidade ou registro afetado.
• Tipo da ação.
• Valor anterior e novo valor, quando existir alteração.
• Motivo, quando a ação for correção.

A auditoria deverá apoiar conferência e rastreabilidade, sem permitir alteração silenciosa de registros relevantes.

A camada Application deverá validar os dados antes de salvar registros.

Validações preliminares:

• Campos obrigatórios conforme categoria aprovada.
• Existência de veículo e pessoa relacionados.
• Usuário autorizado para a operação.
• Saída associada a registro aberto, quando existente.
• Quilometragem de entrada maior ou igual à de saída.
• Ausência de encerramento duplicado.
• Datas e horários coerentes.

Validações relacionadas a RG/CPF, placa obrigatória, tipos oficiais de veículo e significado do campo “veículo” permanecem pendentes.

A interface deverá apresentar mensagens claras e operacionais, sem expor informações técnicas desnecessárias.

A API deverá tratar erros de forma padronizada conforme decisão futura da equipe.

Exemplos:

• “Não foi localizado um acesso aberto para esta placa.”
• “Você não possui permissão para corrigir este registro.”
• “A quilometragem de entrada não pode ser inferior à quilometragem de saída.”
• “Informe o motivo da correção.”

Erros técnicos deverão ser registrados sem exposição de segredos ou dados pessoais desnecessários.

Cadastros e registros que possuem relevância histórica não deverão ser removidos fisicamente sem procedimento aprovado.

Pessoas, veículos, usuários e perfis poderão possuir situação ativa ou inativa, preservando relações e histórico.

A definição detalhada de cancelamento e exclusão permanece pendente.

O sistema deverá coletar somente dados necessários à finalidade do controle veicular.

RG ou CPF não deverá ser obrigatório enquanto sua finalidade, necessidade, retenção e perfis autorizados não forem definidos.

Telefone, e-mail, marca, modelo, cor, identificação patrimonial e número de frota só deverão ser coletados se houver necessidade validada.

A API possui logging HTTP mínimo e exportação OpenTelemetry opcional de métricas HTTP/runtime e traces ASP.NET Core por OTLP. A exportação é vendor-neutral, desabilitada por padrão e não inclui logs, corpos, credenciais ou SQL. Valores de query são redigidos e health checks não geram traces.

O collector, armazenamento, centralização de logs, painéis, alertas e resposta operacional ainda precisam ser definidos com a infraestrutura real. Consulte Observabilidade.

O sistema possui um ensaio local reproduzível de backup lógico, manifesto SHA-256 e restauração em banco isolado, validado também pela CI nas Issues #67 e #308. Nome, tamanho e hash são conferidos antes de copiar o dump ao PostgreSQL, e uma cópia adulterada é rejeitada. O procedimento não permite restaurar sobre o banco operacional por padrão e o checksum não substitui autenticidade ou criptografia.

O PR #313 aprovou backup lógico diário como caminho adicional, janela móvel de 35 dias, RPO-alvo de uma hora, RTO-alvo de quatro horas e exercício trimestral. O dump atual entrega apenas RPO técnico de até 24 horas. A Issue #311 provisionará Object Storage privado, Vault, instance principal, MFA e separação IAM; a Issue #312 implementará WAL/PITR. O desenho está aprovado, mas ainda não foi implantado nem exercitado.

A decisão operacional usa cinco anos para acessos, usos, eventos, auditorias e formulários físicos reconciliados, 90 dias para logs técnicos e 35 dias para backups. Pessoas, veículos e identidade mínima permanecem enquanto necessários a registros retidos. A referência arquivística ou de proteção de dados ainda deve confirmar o enquadramento antes do descarte automático.

O sistema deverá prever procedimentos para indisponibilidade de rede, dispositivo, aplicação ou banco. A proposta usa formulário numerado com dados mínimos, comunicação do incidente, digitação e conferência por pessoas distintas e guarda restrita do papel por cinco anos após a reconciliação.

Os endpoints atuais registram horário e ator do servidor e não devem ser usados para recriar ocorrências antigas. A Issue #100 rastreia um fluxo autenticado, idempotente e auditável, condicionado à validação da Issue #30 pela Portaria, Vigilância e Setor de Transporte. Consulte Retenção, Backup e Continuidade.

Status: Proposta.

Contexto: A portaria, o vigilante e o Setor de Transporte precisam acessar registros centralizados por navegador.

Decisão: Utilizar uma aplicação web acessível por navegador.

Consequências: A solução dependerá da disponibilidade de rede ou de uma estratégia de contingência, além de exigir autenticação e controle de acesso.

Status: Confirmada como direcionamento arquitetural.

Contexto: O projeto possui regras de negócio, perfis, validações, consultas e auditoria que não devem ficar misturados com telas ou detalhes de banco.

Decisão: Organizar a solução como monólito modular, com camadas API, Application, Domain e Infrastructure.

Situação: Camadas implementadas e exercitadas pelos fluxos do MVP, mantendo dependências no sentido API → Application → Domain e detalhes em Infrastructure.

Consequências: Exige disciplina na separação entre camadas e deve evitar complexidade artificial, como CQRS ou microserviços sem necessidade.

Status: Confirmada como direcionamento técnico.

Contexto: O sistema possui entidades e relações entre pessoas, veículos, registros, viagens, usuários, perfis e auditoria.

Decisão: Utilizar PostgreSQL como banco relacional e Entity Framework Core como ORM e ferramenta de migrations.

Situação: PostgreSQL 16 e EF Core 10 integrados, com 13 entidades e 16 migrations versionadas.

Status: Confirmada pela equipe.

Contexto: O backend foi criado com .NET 10 e net10.0, considerando a experiência da equipe e a compatibilidade com Docker, Linux, PostgreSQL e OCI.

Decisão: Utilizar ASP.NET Core Web API com C# e .NET 10.

Situação: Estrutura criada, compilada e validada localmente.

Consequências: Os projetos, pacotes e imagens Docker deverão permanecer compatíveis com net10.0.

Status: Parcialmente implementada.

Contexto: Formulários físicos dificultam rastrear correções e alterações.

Decisão: Registrar o usuário autenticado nas operações relevantes e manter auditoria para criação, alteração, correção e encerramento.

Situação: Login, ciclo de contas, fluxos geral e institucional e catálogos possuem auditoria transacional. A trilha é consultável por Administrador com política, filtros e limites próprios.

Status: Confirmada como direcionamento técnico.

Contexto: O projeto precisa de uma interface web para a portaria e o Setor de Transporte, com formulários, consultas e componentes reutilizáveis.

Decisão: Utilizar React com TypeScript, Vite e Tailwind CSS 4.

Situação: Frontend funcional integrado à API para os fluxos veiculares do MVP, com testes automatizados e validações de acessibilidade.

Consequências: Componentes, estado, cliente HTTP e validação de formulários estão organizados por features. O carregamento sob demanda reduz o JavaScript inicial, e os tokens semânticos permitem evolução visual incremental sem acoplar componentes a nomes de cores; novos fluxos devem preservar contratos, acessibilidade, foco e estados de carregamento.

Status: Proposta de privacidade.

Contexto: O Formulário nº 02 contém campo para RG ou CPF, mas a necessidade e a finalidade ainda não foram formalmente definidas.

Decisão: Não exigir RG ou CPF no MVP até validação pelos responsáveis.

Consequências: O modelo poderá evoluir caso o campo seja aprovado, mas não haverá coleta obrigatória prematura.

Status: Confirmada como direcionamento de escopo.

Contexto: A catraca está quebrada e não há infraestrutura validada para automação, câmeras ou reconhecimento de placas.

Decisão: O MVP funcionará sem integração com equipamentos físicos.

Consequências: O controle inicial será realizado pelo usuário no sistema, e integrações futuras serão tratadas separadamente.

Status: Confirmada como direcionamento técnico.

Contexto: O projeto utiliza GitHub, branch principal protegida, Pull Requests e exige automação de qualidade e entrega.

Decisão: Utilizar GitHub Actions para lint, build, testes e etapas futuras de containerização e deploy.

Situação: Workflows de build, testes, análise, recuperação, containers, ZAP, SBOM, proveniência e publicação no GHCR implementados; deploy institucional pendente.

Status: Confirmada como direcionamento técnico.

Contexto: A disciplina exige conteinerização e o projeto precisa de ambientes reproduzíveis.

Decisão: Utilizar Docker para empacotamento e Docker Compose para ambiente local, quando os serviços estiverem configurados.

Situação: Imagens e Compose local validados na CI; Compose versionado para consumir imagens do GHCR implementado, sem deploy institucional.

Status: Confirmada como direcionamento de organização.

Contexto: O projeto possui frontend, backend, infraestrutura, workflows e documentação relacionados ao mesmo produto.

Decisão: Manter frontend, backend, infraestrutura e automações no mesmo repositório.

Consequências: Facilita rastreabilidade, Pull Requests e sincronização das versões, mas exige organização clara de pastas.

Status: Confirmada como direcionamento de implantação.

Contexto: A equipe definiu uma VM Linux na OCI para uma etapa futura de implantação.

Decisão: Planejar a implantação futura em VM Linux na Oracle Cloud Infrastructure.

Situação: Infraestrutura ainda não criada ou configurada.

Consequências: A equipe deverá estudar rede, firewall, IAM, SSH, containers, backup e custos antes do deploy.

Status: Direção aceita; provisionamento e exercício pendentes.

Contexto: O histórico operacional precisa permanecer por cinco anos, mas backups existem para recuperação e ampliam exposição e custo quando retidos sem necessidade.

Decisão: Reter registros e papel reconciliado por cinco anos, logs por 90 dias e backups por 35 dias. Proteger as cópias em Object Storage privado com Vault, instance principal, MFA e grupos IAM separados. Adotar RPO-alvo de uma hora por WAL/PITR e RTO-alvo de quatro horas.

Situação: ADR 0002 e PR #313 incorporados; Issues #311 e #312 abertas.

Consequências: Regras de retenção imutável devem ser testadas antes do bloqueio; chaves não são compartilhadas como arquivos; produção depende do exercício de recuperação e contingência da segunda unidade.

Status: Proposta; depende do preflight da tenancy e da revisão de custo.

Contexto: A segunda unidade prevê um piloto acompanhado, enquanto o crédito, a vigência, a região, os limites e a capacidade efetiva da conta OCI ainda precisam ser conferidos.

Decisão: Começar com uma implantação reversível de nó único. Somente HTTPS fica público; frontend, API e PostgreSQL permanecem organizados pelo Compose versionado, sem publicar backend, banco, Docker ou interfaces administrativas. O acesso administrativo deve ser temporário, individual e auditável. Imagens versionadas são baixadas do GHCR sem build no host, e segredos não entram em Git, imagem, Terraform ou cloud-init.

Situação: ADR 0004 e PR #392 incorporados. A Issue #382 permanece aberta para preflight, revisão do plano, provisionamento, DNS, HTTPS e operação. Nenhum recurso OCI foi criado e Arm ou benefícios gratuitos não são garantidos.

Consequências: O piloto reduz custo e complexidade, mas aceita uma VM como ponto único de falha. Load balancer, serviços gerenciados e alta disponibilidade só serão adotados se medições, orçamento e capacidade operacional justificarem.

Documento: Arquitetura de Software — arc42
Versão: 2.4
Status: Arquitetura e fluxos técnicos do MVP implementados; homologação e produção institucional pendentes
Núcleo considerado: Formulários nº 01 e nº 02
MVP: Preliminar
Stack: React, TypeScript, Vite, Tailwind CSS 4, ASP.NET Core Web API, C#, .NET 10, PostgreSQL, Entity Framework Core, Docker, Docker Compose, GitHub Actions e OCI futura
Monorepo: Estrutura inicial criada
Backend: Domínio, persistência, segurança inicial, fluxos geral e institucional e manutenção controlada dos catálogos de frota e motoristas implementados; demais casos de uso pendentes
Frontend: Telas e fluxos veiculares do MVP integrados à API, carregamento sob demanda por rota e tokens semânticos com testes de contraste; seletor de tema e homologação permanecem pendentes
PostgreSQL: Serviço local configurado e modelo inicial versionado
EF Core: DbContext, configurações Fluent API e 16 migrations implementados
Docker: Dockerfiles e Compose configurados; endurecimento adicional rastreado na Issue #25
CI/CD: Workflows de aplicação, containers, dependências e recuperação local do PostgreSQL criados e validados; pipeline ainda será ampliada
Rate limiting: Janela fixa por usuário/IP e política de login implementadas; proxy confiável e controle distribuído pendentes
OCI: Topologia econômica de homologação proposta na ADR 0004; preflight, VM, rede e deploy ainda não executados
Autenticação: JWT, contas individuais, ciclo administrativo, validação imediata de conta/perfil e autorização preliminar implementados
Auditoria: Autenticação, criação e estado de contas, fluxos geral e institucional e catálogos auditados de forma transacional; atores humanos e origem de sistema são distinguidos
Implementação de negócio: Fluxos geral e institucional, consultas históricas, catálogos, eventos, resumo diário, correção descritiva e encerramento excepcional implementados; decisões pós-MVP permanecem no backlog

• Aplicação web.
• Monólito modular.
• Clean Architecture adaptada.
• React, TypeScript, Vite e Tailwind CSS 4.
• ASP.NET Core Web API com C# e .NET 10.
• PostgreSQL.
• Entity Framework Core e migrations.
• Docker e Docker Compose.
• GitHub Actions.
• VM Linux na OCI como infraestrutura futura.
• Homologação OCI progressiva, de nó único, com somente HTTPS público e gate de custo.
• Monorepo.
• Separação entre fluxo geral e fluxo institucional.
• Não obrigatoriedade de RG/CPF antes da validação.
• Não dependência de catraca, câmera ou reconhecimento de placa no MVP.

• Validar a arquitetura com os professores.
• Confirmar compatibilidade do .NET 10 com os requisitos da disciplina.
• Homologar autenticação, autorização e fluxos com os quatro perfis.
• Ampliar os testes automatizados junto de cada novo fluxo.
• Validar a proposta de contingência com os usuários reais.
• Conferir a tenancy e revisar o plano da infraestrutura OCI na Issue #382.
• Definir backup protegido e recuperação operacional de produção.

A estruturação do monorepo (#16), a persistência inicial (#20), o alinhamento do modelo (#23) e os fluxos veiculares do MVP foram concluídos. As próximas entregas devem seguir issues menores e revisáveis:

1. Homologar os quatro perfis e as hipóteses de interface na Issue #162.
2. Decidir identificador institucional e exceções nas Issues #266–#275; a recuperação segura do MVP foi concluída na Issue #220.
3. Evoluir o ensaio de backup/restauração somente após definir a infraestrutura real.
4. Homologar retenção, backup e contingência na Issue #30 antes da reconciliação da Issue #100.
5. Preparar implantação somente com TLS, segredos, monitoramento e responsabilidades definidos.