Modelo de Dados - ifpebj-ti/controle-acesso-veiculos GitHub Wiki

Modelo de Dados — Controle de Acesso de Veículos

Instituição: Instituto Federal de Pernambuco — Campus Belo Jardim
Projeto: Controle de Acesso de Veículos
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 do documento: 1.2 Status: Modelo físico e 16 migrations implementados; homologação funcional e produção institucional pendentes Data de referência: 30 de agosto de 2026 Issue relacionada: #10 — Modelar entidades de dados
Documentos relacionados: MVP e Fluxo Digital; Requisitos e Backlog; Regras de Negócio; Arquitetura de Software — arc42; Segurança e Privacidade; Estratégia de Testes; Guia de Execução, Configuração, Deploy e Operação; Decisão de Stack Tecnológica

Como ler este documento: a versão 0.5 distingue o banco implementado da baseline conceitual que orientou a modelagem. As seções 7 e 13 preservam a proposta histórica baseada em UUID para registrar a evolução da decisão; elas não são o contrato físico atual nem devem ser executadas. O estado físico autoritativo está na seção 3.2 e nas migrations versionadas no repositório.

Baseline física atual: 16 migrations estão na main. As migrations PreventDuplicateOpenVehicleAccess e PreventDuplicateOpenInstitutionalVehicleUsage adicionam índices únicos parciais que permitem somente um registro aberto por veículo em cada fluxo. O fluxo geral cria ou reutiliza pessoa, veículo, vínculo e categoria dentro de uma transação. Sem documento, uma nova pessoa é criada para evitar associação indevida por nome. O fluxo institucional persiste motorista, itinerário e quilometragens sem duplicar esses dados na auditoria. A migration AddInstitutionalVehicleCatalog normaliza identificações institucionais, falha diante de colisões e garante sua unicidade por índice filtrado. A migration AddInstitutionalDriverAuthorization separa a autorização para dirigir do cadastro de pessoa, registra ator e datas e não autoriza pessoas históricas automaticamente. A migration AddGeneralAccessHistoryIndex adiciona o índice temporal da consulta histórica geral sem transformar registros existentes. A migration AllowSystemAuditActors permite ator nulo somente para eventos originados pelo sistema, preservando a distinção entre bootstrap e ação autenticada. A migration AddEventAuthorizationCatalog adiciona EventoAcesso e AutorizacaoVeiculoEvento, com janela temporal, cancelamento lógico, pernoite, cotas por tipo, placas opcionais normalizadas, autoria, constraints e índices. A migration LinkEventAuthorizationsToAccessRecords adiciona ao acesso geral uma referência opcional à regra de veículo do evento, com índice e chave estrangeira restritiva. Essa relação preserva a autorização realmente consumida. O resumo operacional da Issue #86 não altera o modelo físico: ele executa agregações condicionais sobre RegistroAcesso, UsoVeiculoInstitucional e o vínculo com AutorizacaoVeiculoEvento. O dia local é convertido para um intervalo UTC semiaberto, evitando contagem dupla entre datas consecutivas. Nenhuma entidade, tabela ou migration foi adicionada para representar fechamento, turno ou conferência.

1. Objetivo

Este documento define a modelagem de dados preliminar do sistema de Controle de Acesso de Veículos do IFPE Campus Belo Jardim.

A modelagem foi revisada após:

  • Análise dos sete formulários.
  • Criação das Regras de Negócio.
  • Criação dos Requisitos e Backlog.
  • Criação do documento MVP e Fluxo Digital.
  • Feedback positivo recebido na apresentação do projeto.
  • Orientação do cliente para digitalizar e melhorar o processo atual sem copiar automaticamente todas as planilhas.
  • Definição preliminar da stack tecnológica.
  • Definição de PostgreSQL como banco de dados relacional.
  • Definição de Entity Framework Core como ORM e ferramenta de migrations.
  • Definição de ASP.NET Core Web API e Clean Architecture adaptada ao MVP.

O modelo considera apenas os dados necessários ao fluxo inicial do MVP.

A existência de um campo no formulário físico não significa que ele será automaticamente mantido no sistema. Cada campo deverá ser validado conforme sua finalidade, necessidade operacional, proteção de dados e utilidade para consultas futuras.

Este modelo serve como base para:

  • Evolução controlada do banco PostgreSQL já implementado.
  • Revisão de novas migrations do Entity Framework Core.
  • Criação de validações.
  • Controle de acesso.
  • Auditoria.
  • Estratégia de testes.
  • Casos de uso da camada de aplicação.
  • Configurações da camada de infraestrutura.

Este documento representa a intenção funcional e resume o modelo físico inicial. As migrations e o snapshot do Entity Framework Core no repositório são a fonte técnica executável; regras pendentes não devem ser tratadas como definitivas.

2. Escopo da modelagem

2.1. Incluído no MVP

  • Veículos.
  • Pessoas relacionadas a veículos.
  • Relações entre pessoas e veículos.
  • Categorias de acesso.
  • Registros de entrada e saída.
  • Condutores.
  • Motoristas institucionais.
  • Objetivos de acesso.
  • Quilometragem de veículos institucionais.
  • Itinerário de veículos institucionais.
  • Usuários.
  • Perfis.
  • Auditoria.
  • Histórico de correções.

2.2. Possível inclusão posterior

  • Registro de recusa.
  • Permanência excepcional.
  • Mototáxis.
  • Eventos com veículos.
  • Ocorrências simples.
  • Veículos de discentes residentes.
  • Permissão detalhada.
  • PerfilPermissao.
  • Exportação autorizada.
  • Relatórios básicos.

Esses fluxos somente deverão ser adicionados ao modelo principal depois de validados e priorizados.

2.3. Fora do escopo inicial

  • Controle geral de pedestres sem veículo.
  • Controle geral de visitantes sem veículo.
  • Controle geral de servidores sem veículo.
  • Controle geral de terceirizados sem veículo.
  • Caminhadas sem veículo.
  • Gestão de crachás.
  • Reconhecimento facial.
  • Reconhecimento automático de placas.
  • Integração com câmeras.
  • Integração com sensores.
  • Automação de catraca ou cancela.
  • Controle de vagas.

3. Tecnologias e direcionamentos de persistência

3.1. Decisões confirmadas pela equipe

Categoria Item Decisão Situação
Stack — Dados Banco de dados PostgreSQL Confirmada pela equipe
Stack — Dados ORM Entity Framework Core Confirmada como direcionamento técnico
Stack — Dados Migrations Entity Framework Core Migrations Confirmada como direcionamento técnico
Stack — Backend Framework ASP.NET Core Web API Confirmada pela equipe
Stack — Backend Linguagem C# Confirmada pela equipe
Stack — Backend Versão .NET 10 com target net10.0 Implementada no repositório
Arquitetura Persistência Camada Infrastructure concentra EF Core e PostgreSQL Implementada
Infraestrutura Banco local e integração PostgreSQL 16 containerizado ou instância local compatível Configurado
Infraestrutura Banco em produção PostgreSQL conforme estratégia futura na OCI Pendente

3.2. Consequências para o modelo

A decisão de usar PostgreSQL e Entity Framework Core implica que:

  • As entidades serão mapeadas para tabelas relacionais.
  • Relações serão implementadas por chaves estrangeiras.
  • Restrições de integridade deverão ser aplicadas no banco e na camada de aplicação.
  • Alterações no esquema deverão ser versionadas por migrations.
  • As migrations deverão ser revisadas antes de aplicação em cada ambiente.
  • Consultas deverão considerar índices futuros para placa, períodos, motorista, veículo e registros em aberto.
  • O uso de ORM não elimina a necessidade de entender SQL, transações, índices e integridade referencial.
  • Novas mudanças devem partir do modelo implementado e gerar migrations revisáveis; o SQL histórico da seção 13 não deve ser executado.

3.3. Estado físico implementado

O backend utiliza .NET 10, Entity Framework Core 10 e Npgsql. O ControleAcessoVeiculosDbContext aplica configurações Fluent API na camada Infrastructure e mapeia as tabelas no schema dbo do PostgreSQL 16.

Entidade Identificador e relações principais Dados implementados relevantes
Pessoa integer gerado pelo banco nome, tipo/número de documento opcionais, vínculo, e-mail opcional, ativo e datas
Veiculo integer gerado pelo banco placa opcional, identificação alternativa, tipo, vínculo institucional, marca, modelo, cor, ano, ativo e datas
PessoaVeiculo FKs inteiras para Pessoa e Veiculo tipo de relação, vigência opcional, ativo e datas
CategoriaAcesso integer gerado pelo banco nome, descrição, validade opcional, ativo e datas
Perfil integer gerado pelo banco nome único, descrição, ativo e datas
Usuario FKs inteiras para Pessoa e Perfil e-mail único, hash da senha, ativo e datas
RegistroAcesso FKs para Veiculo, Pessoa, CategoriaAcesso, regra opcional de evento e usuários responsáveis entrada/saída, objetivo, status, observação e datas
UsoVeiculoInstitucional FKs para Veiculo, motorista, RegistroAcesso opcional e usuários responsáveis saída/retorno, quilometragem, itinerário, status e datas
EventoAcesso FKs para usuários criador e atualizador nome, responsável, contato operacional anulável para registros anteriores, início/fim UTC, área, estacionamento controlado, pernoite, observação, estado e datas
AutorizacaoVeiculoEvento FK para EventoAcesso tipo normalizado, quantidade e placa normalizada opcional
Auditoria FK para Usuario e identificador inteiro do registro afetado entidade, ação, estados anterior/posterior em jsonb, detalhes e data/hora

As migrations versionadas são:

  1. InitialCreate, que criou a fundação inicial.
  2. AlignMvpDataModel, que alinhou entidades, relações, restrições e dados de auditoria ao modelo do MVP.

A migration de alinhamento preserva pessoas, veículos e vínculos existentes. Se houver registros de acesso antigos sem objetivo ou usuários responsáveis inferíveis, ela interrompe a atualização para evitar fabricar dados.

4. Classificação das informações

Classificação Significado
Confirmado em documento Campo identificado diretamente nos formulários analisados
Confirmado em reunião Informação validada verbalmente por responsável pelo processo
Informado Relato de participante ainda sujeito a confirmação
Preliminar Decisão inicial utilizada para orientar a modelagem
Proposta Solução sugerida, ainda não pertencente ao processo atual
Futuro Item previsto para evolução posterior
Pendente Informação que precisa ser confirmada antes da implementação definitiva
Fora do escopo Item não incluído no MVP

5. Princípios da modelagem

MD-01 — Modelar somente o necessário

O modelo deve conter apenas as entidades e os campos necessários para o fluxo aprovado do MVP.

MD-02 — Não copiar planilhas automaticamente

Os campos dos formulários devem ser avaliados antes de serem transformados em atributos obrigatórios.

MD-03 — Preservar rastreabilidade

O modelo deve permitir identificar quem criou, alterou, corrigiu ou conferiu um registro.

MD-04 — Separar fluxos diferentes

O registro geral de acesso e o uso de veículo institucional possuem necessidades diferentes e podem ser representados por entidades relacionadas, mas não necessariamente iguais.

MD-05 — Proteger dados pessoais

Dados como RG ou CPF somente devem ser armazenados se sua necessidade for confirmada.

MD-06 — Permitir evolução

Eventos, mototáxis, permanências e ocorrências poderão ser adicionados futuramente sem obrigar sua implementação no MVP.

MD-07 — Utilizar integridade relacional

O PostgreSQL deverá preservar relações entre entidades por meio de chaves primárias, chaves estrangeiras, restrições e transações.

Classificação: Proposta técnica.

MD-08 — Versionar alterações do esquema

Alterações futuras no banco deverão ser registradas por migrations do Entity Framework Core e revisadas antes de aplicação em ambientes compartilhados.

Classificação: Proposta técnica.

MD-09 — Manter domínio independente da persistência

As regras centrais de domínio não devem depender diretamente de Entity Framework Core, PostgreSQL, SQL ou detalhes de infraestrutura.

As configurações de persistência deverão ser concentradas na camada Infrastructure, de acordo com a Clean Architecture adaptada.

Classificação: Proposta arquitetural.

6. Entidades principais

As entidades preliminares do MVP são:

  1. Pessoa.
  2. Veículo.
  3. PessoaVeiculo.
  4. CategoriaAcesso.
  5. RegistroAcesso.
  6. UsoVeiculoInstitucional.
  7. Usuário.
  8. Perfil.
  9. Auditoria.

7. Entidades e atributos — baseline conceitual v0.4

Esta seção preserva a proposta anterior à implementação para fins acadêmicos e de rastreabilidade. Tipos UUID, nomes e obrigatoriedades abaixo podem divergir do banco atual. Para desenvolvimento e operação, use a seção 3.3, as entidades, as configurações Fluent API e as migrations do repositório.

7.1. Pessoa

Representa uma pessoa relacionada a um veículo ou a uma operação veicular.

Exemplos:

  • Condutor.
  • Motorista institucional.
  • Responsável pelo veículo.
  • Passageiro, se necessário.
  • Usuário do sistema.
Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
nome VARCHAR(200) varchar(200) Sim Confirmado em documento Nome completo
documento_tipo VARCHAR(10) varchar(10) Não Pendente RG ou CPF, se necessário
documento_numero VARCHAR(20) varchar(20) Não Pendente Número do documento
tipo_vinculo VARCHAR(50) varchar(50) Não Pendente Servidor, aluno, terceirizado ou visitante
ativo BOOLEAN boolean Sim Preliminar Indica se o cadastro está ativo
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

Os campos de telefone, e-mail, órgão emissor e UF não fazem parte do núcleo do MVP, salvo necessidade validada.

7.2. Veículo

Representa um veículo que entra, sai ou é utilizado pelo campus.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
placa VARCHAR(10) varchar(10) Pendente Confirmado em documento Placa do veículo
tipo VARCHAR(50) varchar(50) Pendente Preliminar Tipo padronizado
identificacao_veiculo VARCHAR(100) varchar(100) Pendente Pendente Campo “veículo” dos formulários
eh_institucional BOOLEAN boolean Sim Preliminar Indica se é veículo institucional
ativo BOOLEAN boolean Sim Preliminar Indica se está ativo
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

Os campos marca, modelo, cor, identificação patrimonial e número de frota ficam fora do núcleo obrigatório até que sua necessidade seja confirmada.

7.3. PessoaVeiculo

Representa a relação entre uma pessoa e um veículo.

Essa entidade é necessária porque:

  • Uma pessoa pode estar relacionada a vários veículos.
  • Um veículo pode possuir mais de uma pessoa relacionada.
  • A relação pode indicar responsabilidades diferentes.
  • A relação pode ser temporária.
Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
pessoa_id UUID uuid Sim Preliminar Pessoa relacionada
veiculo_id UUID uuid Sim Preliminar Veículo relacionado
tipo_relacao VARCHAR(50) varchar(50) Sim Preliminar Responsável, condutor ou motorista
ativo BOOLEAN boolean Sim Preliminar Indica se a relação está ativa
data_inicio DATE date Não Pendente Início da relação
data_fim DATE date Não Pendente Fim da relação
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

7.4. CategoriaAcesso

Representa a situação ou finalidade geral do acesso veicular.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
nome VARCHAR(100) varchar(100) Sim Preliminar Nome da categoria
descricao VARCHAR(500) varchar(500) Não Preliminar Descrição
ativo BOOLEAN boolean Sim Preliminar Indica se está disponível
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação

Categorias preliminares:

  • Visitante com veículo.
  • Terceirizado com veículo.
  • Veículo institucional.
  • Discente residente.
  • Evento.
  • Treino ou jogo.
  • Caminhada com veículo relacionado.
  • Mototáxi.
  • Outro acesso autorizado.

A lista definitiva deverá ser validada.

O campo requer_documento não será tratado como obrigatório no MVP até que RG ou CPF seja confirmado.

7.5. RegistroAcesso

Representa o registro geral de entrada e saída de veículos, principalmente relacionado ao Formulário nº 02.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
veiculo_id UUID uuid Sim Confirmado em documento Veículo relacionado
pessoa_id UUID uuid Sim Confirmado em documento Condutor relacionado
categoria_id UUID uuid Sim Preliminar Categoria do acesso
data DATE date Sim Confirmado em documento Data do acesso
horario_entrada TIME time Sim Confirmado em documento Horário de entrada
horario_saida TIME time Não Confirmado em documento Horário de saída
objetivo VARCHAR(500) varchar(500) Sim Confirmado em documento Objetivo do acesso
status VARCHAR(50) varchar(50) Sim Preliminar Aberto, encerrado ou pendente
criado_por_id UUID uuid Sim Preliminar Usuário que criou
atualizado_por_id UUID uuid Não Preliminar Usuário da última alteração
autorizacao_veiculo_evento_id INTEGER integer Não Implementado Regra de placa ou cota efetivamente consumida no evento
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

Os campos de itinerário e quilometragem não fazem parte obrigatoriamente de todo RegistroAcesso. Eles pertencem principalmente ao fluxo de veículo institucional.

O campo observacoes poderá ser adicionado se houver necessidade validada.

7.6. UsoVeiculoInstitucional

Representa a saída e o retorno de veículos institucionais, principalmente relacionado ao Formulário nº 01.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
veiculo_id UUID uuid Sim Confirmado em documento Veículo utilizado
motorista_id UUID uuid Sim Confirmado em documento Motorista responsável
registro_acesso_id UUID uuid Não Preliminar Registro geral associado, se existir
data_saida DATE date Sim Confirmado em documento Data de saída
horario_saida TIME time Sim Confirmado em documento Horário de saída
quilometragem_saida INTEGER integer Sim Confirmado em documento Quilometragem de saída
itinerario VARCHAR(500) varchar(500) Sim Confirmado em documento Itinerário
data_entrada DATE date Não Confirmado em documento Data de retorno
horario_entrada TIME time Não Confirmado em documento Horário de retorno
quilometragem_entrada INTEGER integer Não Confirmado em documento Quilometragem de entrada
status VARCHAR(50) varchar(50) Sim Preliminar Em uso, concluído ou pendente
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

O vínculo com RegistroAcesso é opcional porque o Formulário nº 01 possui fluxo próprio de saída e retorno.

7.7. Usuário

Representa uma pessoa autorizada a acessar o sistema.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
pessoa_id UUID uuid Sim Preliminar Pessoa vinculada
perfil_id UUID uuid Sim Preliminar Perfil de acesso
username VARCHAR(50) varchar(50) Sim Preliminar Nome de usuário
senha_hash VARCHAR(255) varchar(255) Sim Proposta de segurança Hash da senha
ativo BOOLEAN boolean Sim Preliminar Indica se pode acessar
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação
atualizado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de atualização

A senha nunca deve ser armazenada em texto puro.

7.8. Perfil

Representa o conjunto de permissões de um usuário.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
nome VARCHAR(100) varchar(100) Sim Preliminar Nome do perfil
descricao VARCHAR(500) varchar(500) Não Preliminar Descrição
ativo BOOLEAN boolean Sim Preliminar Indica se está ativo
criado_em TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data de criação

Perfis preliminares do MVP:

  • Porteiro.
  • Vigilante.
  • Setor de Transporte.
  • Administrador.

Setor de Segurança e SEGAI poderão ser incluídos posteriormente, caso suas necessidades sejam definidas.

7.9. Auditoria

Representa o histórico de operações importantes.

Atributo Tipo lógico Tipo PostgreSQL preliminar Obrigatório no MVP Classificação Descrição
id UUID uuid Sim Preliminar Identificador único
entidade VARCHAR(100) varchar(100) Sim Preliminar Entidade alterada
registro_id UUID uuid Sim Preliminar Registro afetado
acao VARCHAR(50) varchar(50) Sim Preliminar Criação, alteração, correção ou encerramento
usuario_id UUID uuid Sim Preliminar Usuário responsável
dados_anteriores JSON jsonb Não Preliminar Estado anterior
dados_novos JSON jsonb Não Preliminar Estado posterior
data_hora TIMESTAMP timestamp with time zone ou padrão definido pela equipe Sim Preliminar Data e hora da operação

O campo ip_origem fica como evolução futura.

8. Entidades futuras

As seguintes entidades não fazem parte obrigatoriamente do MVP:

  • Evento.
  • Mototáxi.
  • PermanenciaVeiculo.
  • Ocorrencia.
  • Permissao.
  • PerfilPermissao.

Elas poderão ser adicionadas quando os respectivos fluxos forem validados e priorizados.

9. Relacionamentos

Origem Destino Cardinalidade Descrição
Pessoa PessoaVeiculo 1:N Uma pessoa pode ter relações com vários veículos
Veículo PessoaVeiculo 1:N Um veículo pode ter várias pessoas relacionadas
Pessoa RegistroAcesso 1:N Uma pessoa pode aparecer em vários acessos como condutor
Veículo RegistroAcesso 1:N Um veículo pode possuir vários acessos
CategoriaAcesso RegistroAcesso 1:N Uma categoria classifica vários acessos
AutorizacaoVeiculoEvento RegistroAcesso 1:N Uma regra de evento pode autorizar vários acessos até sua quantidade; o vínculo é opcional
Veículo UsoVeiculoInstitucional 1:N Um veículo pode ter várias viagens
Pessoa UsoVeiculoInstitucional 1:N Uma pessoa pode conduzir várias viagens
RegistroAcesso UsoVeiculoInstitucional 0..1:0..1 Associação opcional
Pessoa Usuário 1:0..1 Uma pessoa pode ter uma conta
Perfil Usuário 1:N Um perfil pode possuir vários usuários
Usuário Auditoria 1:N Um usuário pode gerar vários registros de auditoria

10. Modelo conceitual

erDiagram
    PESSOA ||--o{ PESSOA_VEICULO : "relaciona"
    VEICULO ||--o{ PESSOA_VEICULO : "possui"
    PESSOA ||--o{ REGISTRO_ACESSO : "conduz"
    VEICULO ||--o{ REGISTRO_ACESSO : "possui"
    CATEGORIA_ACESSO ||--o{ REGISTRO_ACESSO : "classifica"
    VEICULO ||--o{ USO_VEICULO_INSTITUCIONAL : "é utilizado em"
    PESSOA ||--o{ USO_VEICULO_INSTITUCIONAL : "conduz"
    REGISTRO_ACESSO ||--o| USO_VEICULO_INSTITUCIONAL : "pode relacionar"
    PESSOA ||--o| USUARIO : "possui"
    PERFIL ||--o{ USUARIO : "define"
    USUARIO ||--o{ AUDITORIA : "realiza"

    PESSOA {
        uuid id PK
        string nome
        string documento_tipo
        string documento_numero
        boolean ativo
    }

    VEICULO {
        uuid id PK
        string placa
        string tipo
        string identificacao_veiculo
        boolean eh_institucional
        boolean ativo
    }

    PESSOA_VEICULO {
        uuid id PK
        uuid pessoa_id FK
        uuid veiculo_id FK
        string tipo_relacao
        boolean ativo
    }

    CATEGORIA_ACESSO {
        uuid id PK
        string nome
        boolean ativo
    }

    REGISTRO_ACESSO {
        uuid id PK
        uuid veiculo_id FK
        uuid pessoa_id FK
        uuid categoria_id FK
        date data
        time horario_entrada
        time horario_saida
        string objetivo
        string status
    }

    USO_VEICULO_INSTITUCIONAL {
        uuid id PK
        uuid veiculo_id FK
        uuid motorista_id FK
        uuid registro_acesso_id FK
        date data_saida
        time horario_saida
        integer quilometragem_saida
        integer quilometragem_entrada
        string itinerario
        string status
    }

    USUARIO {
        uuid id PK
        uuid pessoa_id FK
        uuid perfil_id FK
        string username
        string senha_hash
        boolean ativo
    }

    PERFIL {
        uuid id PK
        string nome
        boolean ativo
    }

    AUDITORIA {
        uuid id PK
        string entidade
        uuid registro_id
        string acao
        uuid usuario_id FK
        timestamp data_hora
    }

11. Regras de integridade

11.1. Identificadores

  • Todas as entidades devem possuir identificador único.
  • O identificador deverá ser gerado automaticamente.
  • UUID é uma decisão preliminar e poderá ser revisada antes da implementação.
  • O tipo uuid é suportado pelo PostgreSQL e é compatível com o modelo proposto.

11.2. Chaves estrangeiras

  • registro_acesso.veiculo_id deve referenciar um veículo existente.
  • registro_acesso.pessoa_id deve referenciar uma pessoa existente.
  • registro_acesso.categoria_id deve referenciar uma categoria existente.
  • pessoa_veiculo.pessoa_id deve referenciar uma pessoa existente.
  • pessoa_veiculo.veiculo_id deve referenciar um veículo existente.
  • uso_veiculo_institucional.veiculo_id deve referenciar um veículo existente.
  • uso_veiculo_institucional.motorista_id deve referenciar uma pessoa existente.
  • usuario.pessoa_id deve referenciar uma pessoa existente.
  • usuario.perfil_id deve referenciar um perfil existente.
  • auditoria.usuario_id deve referenciar um usuário existente.

11.3. Domínio

  • A placa deverá possuir formato válido quando a regra for definida.
  • A duplicidade de placa deverá ser tratada conforme a política de cadastro definida.
  • O username deve ser único.
  • A quilometragem de entrada não deve ser inferior à de saída, salvo correção autorizada.
  • A data de fim de uma relação não deve ser anterior à data de início.
  • Um registro encerrado não deve ser encerrado novamente.
  • Uma viagem concluída não deve ser encerrada novamente.
  • Um usuário inativo não deve iniciar novas operações.
  • Campos de status deverão aceitar somente valores previstos no domínio validado.
  • Campos pendentes não devem se tornar obrigatórios sem validação institucional.

11.4. Exclusão

  • Registros históricos não devem ser excluídos fisicamente.
  • Veículos com registros associados devem ser inativados.
  • Pessoas com registros associados devem ser inativadas.
  • Usuários com auditoria associada devem ser inativados.
  • Perfis vinculados a usuários não devem ser excluídos fisicamente.
  • A estratégia de exclusão lógica deverá ser implementada de forma coerente entre domínio, aplicação e infraestrutura.

12. Estados dos registros

12.1. RegistroAcesso

Estado Descrição
aberto Entrada registrada e saída ainda não registrada
encerrado Saída registrada
pendente Necessita de conferência ou correção
permanencia Veículo permanece no campus, se o fluxo for incluído
recusado Acesso recusado, se o fluxo for incluído

12.2. UsoVeiculoInstitucional

Estado Descrição
em_uso Veículo saiu e ainda não retornou
concluido Veículo retornou
pendente_retorno Saída registrada sem retorno localizado
corrigido Registro sofreu correção autorizada

12.3. Cadastros

Estado Descrição
ativo Cadastro disponível
inativo Cadastro não utilizado atualmente
pendente Cadastro necessita de validação
bloqueado Cadastro impedido, se essa regra for aprovada

13. Modelo lógico histórico para PostgreSQL — não executar

A ordem abaixo registra a proposta conceitual v0.4 e suas dependências entre tabelas.

O SQL não representa o banco implementado nem uma migration pronta para produção e não deve ser executado. Ele foi preservado para explicar a evolução entre a proposta baseada em UUID e o modelo físico baseado em inteiros gerados pelo banco.

CREATE TABLE pessoa (
    id UUID PRIMARY KEY,
    nome VARCHAR(200) NOT NULL,
    documento_tipo VARCHAR(10),
    documento_numero VARCHAR(20),
    tipo_vinculo VARCHAR(50),
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE veiculo (
    id UUID PRIMARY KEY,
    placa VARCHAR(10),
    tipo VARCHAR(50),
    identificacao_veiculo VARCHAR(100),
    eh_institucional BOOLEAN NOT NULL DEFAULT FALSE,
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE pessoa_veiculo (
    id UUID PRIMARY KEY,
    pessoa_id UUID NOT NULL REFERENCES pessoa(id),
    veiculo_id UUID NOT NULL REFERENCES veiculo(id),
    tipo_relacao VARCHAR(50) NOT NULL,
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    data_inicio DATE,
    data_fim DATE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE categoria_acesso (
    id UUID PRIMARY KEY,
    nome VARCHAR(100) NOT NULL,
    descricao VARCHAR(500),
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE perfil (
    id UUID PRIMARY KEY,
    nome VARCHAR(100) NOT NULL UNIQUE,
    descricao VARCHAR(500),
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE usuario (
    id UUID PRIMARY KEY,
    pessoa_id UUID NOT NULL REFERENCES pessoa(id),
    perfil_id UUID NOT NULL REFERENCES perfil(id),
    username VARCHAR(50) NOT NULL UNIQUE,
    senha_hash VARCHAR(255) NOT NULL,
    ativo BOOLEAN NOT NULL DEFAULT TRUE,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE registro_acesso (
    id UUID PRIMARY KEY,
    veiculo_id UUID NOT NULL REFERENCES veiculo(id),
    pessoa_id UUID NOT NULL REFERENCES pessoa(id),
    categoria_id UUID NOT NULL REFERENCES categoria_acesso(id),
    data DATE NOT NULL,
    horario_entrada TIME NOT NULL,
    horario_saida TIME,
    objetivo VARCHAR(500) NOT NULL,
    status VARCHAR(50) NOT NULL,
    criado_por_id UUID NOT NULL REFERENCES usuario(id),
    atualizado_por_id UUID REFERENCES usuario(id),
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE uso_veiculo_institucional (
    id UUID PRIMARY KEY,
    veiculo_id UUID NOT NULL REFERENCES veiculo(id),
    motorista_id UUID NOT NULL REFERENCES pessoa(id),
    registro_acesso_id UUID REFERENCES registro_acesso(id),
    data_saida DATE NOT NULL,
    horario_saida TIME NOT NULL,
    quilometragem_saida INTEGER NOT NULL,
    itinerario VARCHAR(500) NOT NULL,
    data_entrada DATE,
    horario_entrada TIME,
    quilometragem_entrada INTEGER,
    status VARCHAR(50) NOT NULL,
    criado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE auditoria (
    id UUID PRIMARY KEY,
    entidade VARCHAR(100) NOT NULL,
    registro_id UUID NOT NULL,
    acao VARCHAR(50) NOT NULL,
    usuario_id UUID NOT NULL REFERENCES usuario(id),
    dados_anteriores JSONB,
    dados_novos JSONB,
    data_hora TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

13.1. Observações sobre o modelo lógico

  • O tipo uuid foi considerado nesta baseline, mas a implementação adotou integer gerado pelo banco.
  • O tipo jsonb é recomendado para os dados de auditoria no PostgreSQL por permitir armazenamento estruturado e consultas futuras.
  • TIMESTAMPTZ é uma proposta para registros de criação, alteração e auditoria; a equipe deverá padronizar estratégia de fuso horário.
  • Campos de placa, documento, tipo de veículo, objetivo e itinerário ainda possuem pendências de negócio.
  • Índices deverão ser definidos depois de validar os padrões de consulta e o volume de acessos.
  • Restrições como CHECK, UNIQUE condicional e índices parciais poderão ser adicionadas após validação das regras.
  • O mapeamento atual está implementado por configurações do Entity Framework Core na camada Infrastructure.
  • Mudanças futuras devem ser feitas por migrations novas; este SQL histórico não deve ser convertido diretamente em produção.

14. Dicionário de dados

Tipo lógico Tipo PostgreSQL sugerido Descrição
UUID uuid Identificador único universal
VARCHAR(n) varchar(n) Texto variável com limite de tamanho
INTEGER integer Número inteiro
BOOLEAN boolean Verdadeiro ou falso
DATE date Data
TIME time Horário
TIMESTAMP timestamptz ou padrão definido pela equipe Data e horário
JSON jsonb Estrutura de dados em formato JSON otimizada para PostgreSQL

14.1. Domínios preliminares

Domínio Valores preliminares
tipo_relacao responsável, condutor, motorista_institucional, passageiro
tipo_vinculo servidor, aluno, terceirizado, visitante, prestador, outro
status_registro aberto, encerrado, pendente
status_uso em_uso, concluido, pendente_retorno, corrigido
perfil porteiro, vigilante, setor_transporte, administrador

Os valores ainda precisam ser validados.

15. Campos por fluxo

15.1. Fluxo geral de veículos

Campo Entidade Situação
data RegistroAcesso Manter
veículo Veículo Manter, significado pendente
placa Veículo Manter, obrigatoriedade pendente
condutor Pessoa Manter
horário de entrada RegistroAcesso Manter
horário de saída RegistroAcesso Manter
objetivo RegistroAcesso Manter, formato pendente
categoria CategoriaAcesso Manter
usuário responsável Usuário Manter
assinatura manual Auditoria ou autenticação Avaliar substituição

15.2. Fluxo institucional

Campo Entidade Situação
veículo Veículo Manter
placa Veículo Manter, obrigatoriedade pendente
motorista UsoVeiculoInstitucional Manter
data de saída UsoVeiculoInstitucional Manter
horário de saída UsoVeiculoInstitucional Manter
quilometragem de saída UsoVeiculoInstitucional Manter
itinerário UsoVeiculoInstitucional Manter
horário de entrada UsoVeiculoInstitucional Manter no retorno
quilometragem de entrada UsoVeiculoInstitucional Manter no retorno
assinatura manual Auditoria ou autenticação Avaliar substituição

15.3. Dados pendentes

Campo ou decisão Questão Prioridade
RG ou CPF Será obrigatório? Alta
Tipo de documento Qual documento será aceito? Alta
Campo “veículo” Representa tipo, modelo, patrimônio ou frota? Alta
Placa Será obrigatória em todos os acessos? Alta
Tipo de veículo Quais opções oficiais serão utilizadas? Alta
Objetivo Texto, lista ou combinação? Alta
Itinerário Destino, trajeto ou ambos? Alta
Assinatura Será substituída por autenticação e auditoria? Média
Patrimônio Será necessário? Média
Número de frota Será necessário? Média
Retenção Qual será o prazo digital? Alta
Índices Quais consultas precisarão de otimização? Média
Fuso horário Qual padrão será adotado nos registros de data e hora? Média

16. Dados pessoais e controles de acesso

16.1. Dados pessoais

Dado Entidade Classificação Justificativa
nome Pessoa Dado pessoal Identificação básica
RG ou CPF Pessoa Dado pessoal de identificação Somente se necessário
tipo de vínculo Pessoa Dado pessoal institucional Classificação do acesso
username Usuário Dado de autenticação Acesso ao sistema
senha_hash Usuário Credencial protegida Autenticação

16.2. Perfis preliminares

Perfil Consultar registros Registrar entrada/saída Corrigir Gerenciar usuários
Porteiro Sim, dados operacionais Sim Não definido Não
Vigilante Sim, dados operacionais Sim, conforme validação Não definido Não
Setor de Transporte Sim Conforme validação Sim, conforme autorização Não definido
Administrador Conforme política Conforme política Conforme política Sim

Essa matriz é preliminar e deverá ser validada.

16.3. Proteção

  • Senhas devem ser armazenadas somente como hash.
  • RG ou CPF não deve aparecer em consultas gerais sem necessidade.
  • Consultas, correções e exportações devem ser auditáveis.
  • Dados pessoais devem ser coletados somente com finalidade definida.
  • Usuários devem possuir apenas as permissões necessárias.
  • Strings de conexão e segredos não devem ser armazenados no código ou nas migrations.
  • Configurações sensíveis deverão utilizar variáveis de ambiente ou mecanismo seguro equivalente.
  • A política de criptografia será definida na arquitetura e no documento de segurança.

17. Rastreabilidade

Requisito ou decisão Entidade(s) Status
Cadastrar veículo Veículo Modelado preliminarmente
Cadastrar pessoa Pessoa Modelado preliminarmente
Associar pessoa e veículo PessoaVeiculo Modelado preliminarmente
Registrar entrada RegistroAcesso Modelado preliminarmente
Registrar saída RegistroAcesso Modelado preliminarmente
Registrar objetivo RegistroAcesso Modelado preliminarmente
Registrar placa Veículo Modelado preliminarmente
Registrar motorista UsoVeiculoInstitucional Modelado preliminarmente
Registrar quilometragem UsoVeiculoInstitucional Modelado preliminarmente
Registrar itinerário UsoVeiculoInstitucional Modelado preliminarmente
Consultar registros RegistroAcesso Modelado preliminarmente
Consultar por placa Veículo e RegistroAcesso Modelado preliminarmente
Consultar por motorista Pessoa e UsoVeiculoInstitucional Modelado preliminarmente
Consultar veículos sem saída RegistroAcesso Modelado preliminarmente
Conferir registros RegistroAcesso e Auditoria Modelado preliminarmente
Controlar perfis Usuário e Perfil Modelado preliminarmente
Registrar correções Auditoria Modelado preliminarmente
Persistência relacional Todas as entidades principais Modelado preliminarmente
Migrations versionadas Infrastructure e banco PostgreSQL Implementado
Integridade referencial Chaves estrangeiras Implementado no modelo físico inicial

18. Impactos do feedback do cliente

O feedback recebido provocou as seguintes decisões de modelagem:

  • O modelo deve priorizar o MVP.
  • Os campos dos formulários não serão automaticamente obrigatórios.
  • As entidades futuras não devem ser implementadas antecipadamente.
  • O modelo deve permitir simplificação do processo.
  • Dados sem finalidade confirmada devem permanecer pendentes.
  • Os Formulários nº 03 a nº 07 não serão modelados integralmente neste momento.
  • Eventos, mototáxis, permanências e ocorrências podem ficar para versões posteriores.
  • O modelo deve apoiar melhorias, não apenas reproduzir o papel.
  • A estrutura deve permitir implementação futura em PostgreSQL com Entity Framework Core sem antecipar migrations não aprovadas.
  • As regras de domínio devem permanecer separadas dos detalhes de persistência.

19. Limitações

  • O modelo ainda não foi validado formalmente.
  • A obrigatoriedade da placa não foi confirmada por categoria.
  • O significado do campo “veículo” ainda está pendente.
  • RG ou CPF ainda não foi aprovado como dado obrigatório.
  • As permissões definitivas ainda não foram aprovadas.
  • O fluxo de veículos de discentes residentes ainda não está detalhado.
  • Eventos, mototáxis, permanências e ocorrências ainda não estão consolidados.
  • O SQL conceitual v0.4 foi preservado apenas como registro histórico e não é uma migration.
  • O modelo implementado ainda pode mudar após validação das regras institucionais.
  • A estratégia de índices ainda não foi definida.
  • A política de retenção ainda não foi definida.
  • A infraestrutura do PostgreSQL na OCI ainda não foi definida.

20. Próximas etapas

  1. Validar o MVP com a equipe e o cliente.
  2. Confirmar os campos mantidos e eliminados.
  3. Confirmar a obrigatoriedade de RG ou CPF.
  4. Confirmar o significado do campo “veículo”.
  5. Confirmar os tipos oficiais de veículos.
  6. Confirmar o formato do objetivo.
  7. Confirmar o significado do itinerário.
  8. Validar perfis e permissões.
  9. Revisar toda migration futura antes de aplicá-la.
  10. Ampliar os testes de integração PostgreSQL junto de cada novo fluxo.
  11. Definir retenção, backup e recuperação na Issue #30.
  12. Atualizar este documento quando uma regra aprovada alterar o modelo físico.

21. Status vigente, validação e próximas etapas

Documento: Modelo de Dados — Controle de Acesso de Veículos
Versão: 1.2 Status: Modelo físico e 16 migrations implementados; homologação funcional e produção institucional pendentes Formulários considerados: 7 de 7
Núcleo do MVP: Formulários nº 01 e nº 02
Feedback do cliente: Favorável à digitalização e à melhoria do processo atual
Banco de dados: PostgreSQL confirmado pela equipe
ORM: Entity Framework Core confirmado como direcionamento técnico
Migrations: Entity Framework Core Migrations confirmado como direcionamento técnico
Backend: ASP.NET Core Web API com C#
Versão do .NET: .NET 10 com target net10.0, implementada Arquitetura: Clean Architecture adaptada ao MVP e monólito modular
Validação pelo Setor de Transporte: Pendente
Validação pela portaria: Pendente
Validação dos perfis: Pendente
Aprovação do modelo lógico: Pendente
Implementação do banco: DbContext, configurações Fluent API e modelo PostgreSQL implementados Migrations: Dez migrations versionadas, incluindo alinhamento do MVP, segurança, integridade dos fluxos, consultas, catálogos institucionais e atores de auditoria Responsáveis pela documentação:

  • José Ernandes Gonçalves Costa.
  • Raíssa Beatriz Marinho dos Santos.

Principais alterações da versão 0.4

  • Atualizada a versão do documento de 0.3 para 0.4.
  • Incluída a decisão de PostgreSQL como banco relacional.
  • Incluída a decisão de Entity Framework Core como ORM.
  • Incluída a decisão de Entity Framework Core Migrations para versionamento do esquema.
  • Registrada a integração esperada com ASP.NET Core Web API, C# e Clean Architecture.
  • Adicionados tipos PostgreSQL preliminares aos atributos.
  • Atualizado o modelo lógico para utilizar uuid, timestamptz e jsonb.
  • Atualizada a seção de persistência para separar modelo lógico de migrations reais.
  • Adicionados princípios de integridade relacional, migrations versionadas e independência do domínio.
  • Adicionadas pendências sobre índices, fuso horário, estratégia de migrations e infraestrutura PostgreSQL.
  • Mantido que o banco, as migrations, o Entity Framework Core e o código ainda não foram implementados.
  • Mantidas como pendentes as regras institucionais, RG/CPF, placa, campo “veículo”, itinerário, perfis e retenção.

Principais alterações da versão 0.5

  • Separado o modelo físico implementado da baseline conceitual v0.4.
  • Registrados .NET 10, EF Core 10, PostgreSQL 16 e schema dbo.
  • Documentadas as nove entidades e as seis migrations versionadas.
  • Marcados UUIDs e SQL conceitual como registro histórico não executável.
  • Preservadas as pendências funcionais e institucionais que a implementação técnica não pode decidir.

Principais alterações da versão 0.6

  • Incluída a entidade MotoristaInstitucional como autorização separada do cadastro de pessoa.
  • Registrada a migration AddInstitutionalDriverAuthorization, sem autorização retroativa de pessoas históricas.
  • Atualizada a baseline para dez entidades, oito migrations e 84 testes na main.
  • Mantidos fora do MVP os campos das planilhas sem finalidade institucional validada.
  • Adicionados índices de saída e motorista/saída para a consulta histórica institucional na Issue #59.

Principais alterações da versão 0.7

  • Atualizada a baseline para 94 testes na main.
  • Registrada a manutenção controlada da frota da Issue #61 sem nova migration, pois reutiliza Ativo e DataAlteracao.
  • Mantida a exclusão lógica para preservar vínculos, usos institucionais e auditoria.

Principais alterações da versão 0.8

  • Atualizada a baseline para nove migrations e 99 testes na main.
  • Registrado o índice ix_registros_acesso_data_entrada da Issue #63 para a consulta histórica geral.
  • Mantidos documento, objetivo e observação fora dos filtros de busca por minimização de dados.
  • Registrada a correção descritiva da Issue #65 sem nova migration, reutilizando campos e auditoria existentes.

Principais alterações da versão 0.9

  • Atualizada a baseline para dez migrations e 129 testes na main.
  • Registrada a migration AllowSystemAuditActors, que torna usuario_id opcional somente para eventos originados pelo sistema.
  • Documentada a auditoria atômica da criação administrativa e do bootstrap sem senha, hash, nome ou e-mail nos detalhes.