Baseline técnica — 30/09/2026: GitHub Actions executa formatação/lint, builds, testes, cobertura, Dependency Review, build de containers, Trivy e ensaio de recuperação do PostgreSQL. A stack de PostgreSQL, API e frontend também é iniciada em um projeto Compose descartável e precisa passar por readiness. Pull Requests e pushes na main validam sem publicar. Somente tags SemVer revisadas publicam imagens no GHCR; proveniência e SBOM assinados ficam no GitHub Artifact Attestations. Rastreabilidade: Issues #90, #92, #318 e #325. As seções históricas abaixo permanecem para registrar a evolução acadêmica; quando houver divergência de estado, esta baseline prevalece.

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: 0.3
Status: Fundação de CI e registry implementada; deploy pendente
Data de referência: 31 de agosto de 2026
Documentos relacionados: Decisão de Stack Tecnológica v0.2; Arquitetura de Software — arc42 v0.2; Estratégia de Testes v0.3; Guia de Execução, Configuração, Deploy e Operação v0.2; Segurança e Privacidade v0.1

Este documento apresenta a matriz de ferramentas técnicas do projeto Controle de Acesso de Veículos.

A matriz transforma as decisões gerais de stack em escolhas práticas para:

• Organizar e manter o monorepo.
• Desenvolver o frontend.
• Desenvolver o backend.
• Persistir dados.
• Criar migrations.
• Executar testes.
• Aplicar lint e formatação.
• Criar containers.
• Configurar pipeline de integração contínua.
• Preparar deploy futuro na OCI.
• Proteger credenciais e dependências.

Este documento diferencia ferramentas confirmadas, implementadas, propostas, pendentes e futuras. Uma ferramenta classificada como proposta ou futura não deve ser considerada configurada no projeto.

Tecnologias adotadas:

.NET 10
ASP.NET Core Web API
C#
Target Framework: net10.0
Formato de solução: .slnx

Situação atual:

• Solução backend criada.
• Projetos Domain, Application, Infrastructure e API criados.
• Referências entre projetos configuradas.
• Restore executado com sucesso.
• Build executado com sucesso.
• Comando inicial de testes executado sem falhas.
• Workflow de CI configurado para compilar a solução .slnx.

Motivos da adoção:

• Decisão confirmada pela equipe.
• Compatibilidade com APIs web.
• Compatibilidade com Entity Framework Core.
• Compatibilidade com PostgreSQL.
• Compatibilidade com Docker e Linux.
• Adequação para futura VM Linux na OCI.
• Suporte até maio de 2027.
• Ferramentas e SDK disponíveis no ambiente de desenvolvimento.

src/backend/
├── ControleAcessoVeiculos.slnx
├── ControleAcessoVeiculos.API/
├── ControleAcessoVeiculos.Application/
├── ControleAcessoVeiculos.Domain/
└── ControleAcessoVeiculos.Infrastructure/

Responsabilidades previstas:

Tecnologias previstas:

Entity Framework Core
Provider PostgreSQL compatível
Entity Framework Core Migrations

Finalidade:

• Mapear entidades C# para tabelas PostgreSQL.
• Configurar relacionamentos.
• Executar consultas.
• Criar migrations.
• Atualizar esquema do banco de forma versionada.
• Integrar persistência à camada Infrastructure.

Cuidados:

• Não colocar regras de negócio dentro do DbContext.
• Não tratar migrations como substituto da validação do Modelo de Dados.
• Revisar migrations antes de aplicá-las.
• Não executar migrations em produção sem backup e procedimento aprovado.
• Compreender SQL, índices, joins e transações mesmo usando ORM.

Situação: Definido como direcionamento técnico; ainda não instalado ou configurado.

Recomendação:

xUnit

Finalidade:

• Testar regras de domínio.
• Testar casos de uso.
• Testar validações.
• Testar transições de estado.
• Testar regras de quilometragem.
• Testar correções e auditoria.

Exemplos futuros:

Registro de entrada válido cria acesso aberto.
Saída duplicada é bloqueada.
Quilometragem de entrada menor que saída é rejeitada.
Correção sem motivo é rejeitada.
Usuário sem permissão não corrige registro.

Situação: Proposta recomendada; projetos de teste ainda não criados.

Recomendação:

FluentAssertions

Finalidade:

Melhorar a legibilidade dos testes.

Exemplo conceitual:

resultado.Sucesso.Should().BeTrue();
registro.Status.Should().Be(StatusRegistroAcesso.Aberto);

Situação: Proposta recomendada.

Recomendação inicial:

WebApplicationFactory
PostgreSQL de teste
Entity Framework Core

Evolução futura:

Testcontainers for .NET

Finalidade:

• Testar endpoints da API.
• Testar autenticação e autorização.
• Testar persistência real.
• Testar migrations.
• Testar consultas.
• Testar auditoria.
• Testar resposta de erros.
• Evitar testes que usem apenas mocks em fluxos críticos.

Situação: Proposta recomendada.

Recomendação:

Swagger / OpenAPI

Finalidade:

• Documentar endpoints.
• Testar a API localmente.
• Visualizar contratos de requisição e resposta.
• Ajudar a integração entre frontend e backend.
• Apoiar demonstrações técnicas.

Cuidados:

• Não expor Swagger publicamente em produção sem decisão e proteção adequadas.
• Não expor exemplos com senhas, tokens ou dados pessoais reais.

Situação: Implementado em Development pelo PR #369. O documento nativo fica em /openapi/v1.json e a interface em /swagger. Operações protegidas indicam Bearer JWT, operações anônimas permanecem sem requisito incorreto e a autorização não é persistida pelo navegador. Swagger e OpenAPI não são publicados em produção.

Recomendação inicial:

Usar Data Annotations para regras simples e avaliar FluentValidation
para regras mais complexas de entrada, saída, quilometragem e correção.

A decisão deve ser tomada antes da implementação dos primeiros endpoints.

Situação: Pendente de discussão.

Recomendação inicial:

ILogger do ASP.NET Core

Finalidade:

• Registrar inicialização.
• Registrar erros técnicos.
• Registrar falhas de conexão.
• Registrar problemas de infraestrutura.
• Apoiar diagnóstico local e futuro monitoramento.

Nunca registrar:

• Senhas.
• Hashes.
• Tokens.
• Strings de conexão.
• RG ou CPF completos.
• Segredos.
• Dados pessoais desnecessários.

Situação: Proposta recomendada.

Tecnologias adotadas:

React
TypeScript
Vite
npm

Situação atual:

• Projeto React com TypeScript criado.
• Dependências instaladas com npm.
• ESLint executado sem erros.
• Build executado com sucesso por meio de npm run build.
• Aplicação iniciada localmente por meio de npm run dev.

Finalidade:

• Criar a interface web.
• Executar ambiente local de desenvolvimento.
• Gerar build de produção.
• Integrar ferramentas de qualidade e testes.
• Preparar futuras telas do sistema.

Tecnologias adotadas:

Tailwind CSS 4
@tailwindcss/vite

Configuração adotada:

Plugin do Tailwind integrado ao Vite.
Importação global de Tailwind por meio de @import "tailwindcss".

Finalidade:

• Estilização utilitária.
• Criar componentes customizados.
• Manter consistência visual.
• Permitir flexibilidade de design.
• Criar interfaces responsivas.

Situação atual:

• Plugin @tailwindcss/vite instalado.
• Configuração adicionada ao vite.config.ts.
• Build validado localmente.
• Configurações legadas de PostCSS removidas.

Recomendação:

React Router

Finalidade:

• Organizar páginas.
• Criar rotas do sistema.
• Proteger rotas autenticadas futuramente.
• Separar telas de entrada, saída, consultas, veículos institucionais e administração.

Situação: Proposta recomendada.

Recomendação:

React Hook Form

Finalidade:

• Gerenciar formulários.
• Validar campos.
• Controlar erros de preenchimento.
• Reduzir repetição em telas de entrada, saída e veículos institucionais.

Situação: Proposta recomendada.

Recomendação:

Zod

Finalidade:

• Definir schemas de validação.
• Validar formulários.
• Melhorar integração com TypeScript.
• Compartilhar regras simples de validação com a interface.

A validação do frontend não substitui a validação no backend.

Situação: Proposta recomendada.

Recomendação:

Axios

Finalidade:

• Centralizar URL da API.
• Configurar interceptors de autenticação.
• Tratar erros de requisição.
• Facilitar configuração futura de tokens.

Situação: Proposta recomendada.

Recomendação:

Vitest
Testing Library
Playwright no futuro

Finalidade:

• Vitest: testar componentes e utilitários.
• Testing Library: testar interação com componentes React.
• Playwright: testar fluxos completos no navegador.

Situação: Proposta recomendada.

Situação atual:

O arquivo .editorconfig foi criado na raiz do monorepo.

Finalidade:

• Padronizar indentação.
• Padronizar quebras de linha.
• Evitar diferenças de formatação entre Windows e Linux.
• Melhorar consistência entre C#, TypeScript, JSON, YAML e Markdown.

Tecnologia adotada:

Docker

Finalidade:

• Padronizar ambiente.
• Executar backend, frontend e banco.
• Reproduzir ambiente local.
• Preparar deploy futuro.
• Facilitar execução em VM Linux na OCI.

Situação atual:

• Dockerfile inicial do backend criado.
• Dockerfile inicial do frontend criado.
• Execução completa ainda precisa ser validada.

Tecnologia adotada:

Docker Compose

Serviços previstos:

frontend
backend
postgresql
proxy reverso futuro

Situação atual:

• Arquivo docker-compose.yml inicial criado.
• Serviços de frontend, backend e PostgreSQL definidos.
• Execução integrada ainda precisa ser validada antes de ser considerada pronta para uso.

infrastructure/
└── docker/
    ├── frontend/
    │   ├── Dockerfile
    │   └── nginx.conf
    ├── backend/
    │   └── Dockerfile
    └── docker-compose.yml

• Usar imagens base atualizadas.
• Usar imagens oficiais quando possível.
• Não incluir segredos em imagens.
• Executar processo sem privilégios quando aplicável.
• Copiar apenas arquivos necessários.
• Analisar imagens futuramente.
• Atualizar dependências vulneráveis.

Tecnologia adotada:

GitHub Actions

Situação atual:

• Backend executa restore, dotnet format, build com warnings como erros, 164 testes e coleta de cobertura.
• Frontend executa instalação travada, lint e build.
• Dependency Review bloqueia novas dependências de severidade alta ou crítica.
• Containers de backend e frontend são construídos e analisados pelo Trivy.
• Pull Requests e main reconstroem e analisam imagens sem publicar no GHCR.
• Tags SemVer revisadas repetem as validações e publicam a release multi-arquitetura.
• Proveniência e SBOM assinados ficam no GitHub Artifact Attestations, sem versões OCI auxiliares no GHCR.
• Recuperação do PostgreSQL é ensaiada em banco isolado pela CI.

Push ou Pull Request
    ↓
Checkout do código
    ↓
Lint, formatação, builds e testes
    ↓
Build das imagens de backend e frontend
    ↓
Trivy HIGH/CRITICAL
    ↓
Pull Request: encerra sem credencial de package
main: encerra depois de build, scan, smoke test e ZAP, sem publicação
tag vMAJOR.MINOR.PATCH: repete validações → GHCR (`MAJOR.MINOR.PATCH` e `sha-<commit>`)
    ↓
GitHub Artifact Attestations: proveniência + SBOMs assinados

Promoção controlada e deploy futuro

Recomendação:

Dependabot

Finalidade:

• Avisar sobre dependências vulneráveis.
• Criar Pull Requests de atualização.
• Ajudar a acompanhar atualizações de dependências.

Situação: Configurado semanalmente para NuGet, npm, imagens Docker e GitHub Actions. Atualizações continuam sujeitas a Pull Request, revisão e CI; não há merge automático.

Recomendação:

GitHub Secret Scanning

Finalidade:

• Identificar segredos enviados acidentalmente.
• Apoiar proteção de tokens, senhas e chaves.
• Evitar exposição de credenciais OCI ou banco.

Situação: Proposta recomendada.

Opções futuras:

Trivy ou ferramenta equivalente

Situação: Futuro recomendado.

Direcionamento confirmado:

VM Linux na OCI

Situação: Futuro; infraestrutura ainda não criada.

Antes da criação da infraestrutura, a equipe deverá compreender:

• IAM.
• MFA.
• Código de bypass.
• Compartments.
• Compute.
• VCN.
• Subnets.
• Security Lists ou Network Security Groups.
• IP público.
• SSH.
• Firewall.
• Armazenamento.
• Custos e limites.
• Backup.
• Monitoramento.

• Habilitar MFA.
• Gerar e guardar código de bypass em local seguro.
• Não compartilhar credenciais.
• Não publicar chaves privadas.
• Não publicar código de bypass.
• Não abrir portas desnecessárias.
• Não criar recursos pagos sem entendimento.
• Não criar VM antes do planejamento da infraestrutura.

Recomendação:

Adiar a escolha até a etapa de deploy.

• Cliente HTTP: Axios ou Fetch API.
• React Router.
• React Hook Form.
• Zod.
• Prettier.
• Vitest.
• Testing Library.
• Estrutura interna de pastas e componentes.
• Estratégia de temas, cores e design system.
• Gerenciamento de estado, se necessário.
• Estratégia de autenticação e autorização no frontend.

• Entity Framework Core e provider PostgreSQL.
• Biblioteca de autenticação.
• Estratégia de token ou sessão.
• Data Annotations ou FluentValidation.
• xUnit e FluentAssertions.
• Projetos de testes.
• Estratégia de testes de integração.
• Ferramenta de cobertura.
• Analyzers específicos.
• Estratégia de logs mais avançada.
• Swagger/OpenAPI.
• Formato de erros da API.
• Estratégia de seed de dados.

• Validação do Docker Compose.
• Ambiente de homologação.
• Estratégia de PostgreSQL na OCI.
• Proxy reverso.
• HTTPS.
• Domínio.
• Monitoramento.
• Backup.
• Recuperação.
• Estratégia de deploy.
• Acesso SSH.
• Política de segredos.
• Testes de carga.
• Scanner de imagens.

1. Atualizar documentos com o resultado da Issue #16
    ↓
2. Estruturar arquitetura inicial do frontend
    ↓
3. Definir e instalar bibliotecas frontend necessárias
    ↓
4. Definir e instalar ferramentas de testes backend
    ↓
5. Modelar banco de dados e entidades do domínio
    ↓
6. Configurar Entity Framework Core e PostgreSQL
    ↓
7. Criar migrations iniciais
    ↓
8. Implementar autenticação e autorização
    ↓
9. Criar primeiros endpoints do MVP
    ↓
10. Criar primeiras telas do MVP
    ↓
11. Validar Docker Compose integrado
    ↓
12. Evoluir CI com testes e cobertura
    ↓
13. Planejar deploy e infraestrutura na OCI

A próxima atividade recomendada é estruturar a arquitetura inicial do frontend.

A atividade deverá definir:

- Organização de components, pages, routes, services, hooks, types e utils.
- React Router e rotas iniciais.
- Cliente HTTP centralizado.
- Convenções para componentes reutilizáveis.
- Layout base da aplicação.
- Página inicial temporária.

Depois da estrutura inicial do frontend, a equipe deverá confirmar:

- xUnit.
- FluentAssertions.
- Estratégia de testes de integração.
- Swagger/OpenAPI.
- Data Annotations ou FluentValidation.
- dotnet format.
- Analyzers .NET.
- Entity Framework Core com provider PostgreSQL.

Depois da implementação inicial do MVP, a equipe deverá planejar:

- Validação do Docker Compose.
- Estratégia de containers.
- Evolução da pipeline de CI/CD.
- Infraestrutura na OCI.
- Proxy reverso.
- HTTPS.
- Monitoramento.
- Backup.

Documento: Matriz de Ferramentas Técnicas
Versão: 0.3
Status: Ferramentas de desenvolvimento, teste e cadeia de entrega implementadas; implantação institucional pendente
Stack principal: Definida pela equipe e orientadora
Ferramentas complementares: Parcialmente definidas ou pendentes
Código: Monorepo e fluxos veiculares do MVP integrados
Backend: Clean Architecture adaptada, API .NET 10 e 262 testes na baseline atual
Frontend: React, Vite, TypeScript, Tailwind CSS 4, ESLint e 432 testes na baseline atual
Banco: PostgreSQL 16 integrado por EF Core com 16 migrations
Containers: Dockerfiles, Compose local, smoke test e Compose versionado para imagens do GHCR implementados
Pipeline: GitHub Actions com build, testes, CodeQL, Dependency Review, Trivy, ZAP, SBOM, proveniência e publicação multi-arquitetura
Deploy: Ainda não realizado

• Backend estruturado com .NET 10, ASP.NET Core Web API e Clean Architecture adaptada.
• Solução backend criada no formato .slnx.
• Restore, build e execução inicial de testes do backend validados localmente.
• Banco PostgreSQL, schema dbo, migrations e integração via Entity Framework Core implementados.
• Frontend criado com React, TypeScript, Vite e Tailwind CSS 4.
• Tailwind CSS configurado com o plugin oficial @tailwindcss/vite.
• Lint e build do frontend validados localmente.
• Docker Compose, Dockerfiles e workflows do GitHub Actions criados e validados na CI.
• Workflow de backend ajustado para utilizar ControleAcessoVeiculos.slnx.
• GitHub Actions validado com checks de backend e frontend aprovados no Pull Request da estrutura inicial.
• 262 testes automatizados de Domain, Application, API e PostgreSQL real e 432 testes de frontend estão integrados à baseline técnica de 30/09/2026.
• Imagens OCI são publicadas no GHCR; ambiente OCI, proxy reverso, monitoramento, backup protegido e deploy permanecem fora do escopo implementado.