Controle Verbas — API REST

---

🔗 Frontend

Este backend possui um frontend totalmente integrado e funcional. Para explorar a interface de usuário, visite o repositório do frontend:

• 🌐 Controle Verbas — Frontend

---

Visão Geral do Projeto

Controle Verbas é uma API REST completa, segura e totalmente automatizada que integra seu frontend, com autenticação via JWT, validação robusta e arquitetura profissional com Spring Boot.
Desenvolvido principalmente para prática de backend, o projeto também pode atender pequenas empresas que buscam organizar seu fluxo de verbas.
O projeto adota arquitetura em camadas (controller, service, repository, domain e DTOs), aplicando boas práticas de organização, responsabilidade e manutenção de código.

O desenvolvimento do projeto consolidou habilidades como:

• 🏗️ Arquitetura RESTful
• 🧪 Testes unitários e de integração com JUnit 5 e 🔧 Mockito
• ✅ Validações robustas com Bean Validation
• 🛠️ Tratamento de erros
• 📖 Documentação automatizada com Swagger (OpenAPI)
• 🔒 Segurança com JWT (JSON Web Token)

A arquitetura em camadas e as boas práticas aplicadas tornam o código organizado, escalável e fácil de manter.

---

Tecnologias Utilizadas

• ☕ Java 17 ou superior + 🌱 Spring Boot 3
• 🔒 Spring Security + 🔑 JWT
• 📦 JPA + 🛠️ Hibernate
• 🐘 Banco de dados PostgreSQL
• 🛠️ Controle de versionamento de banco com Flyway
• 📦 Maven: Gerenciamento de dependências e build.
• 🧪 JUnit 5
• 🔧 Mockito
• 📄 Swagger (OpenAPI)
• 🐧 WSL e 🐳 Docker CLI

---

Ferramentas Utilizadas

• 💻 Visual Studio Code: Ambiente de desenvolvimento integrado (IDE) leve e extensível.
• 🐘 PostgreSQL: Sistema de gerenciamento de banco de dados relacional de código aberto, usado via CLI em contêiner Docker.
• 📡 Insomnia: Ferramenta de teste de APIs REST que permite enviar requisições HTTP, validar respostas e testar endpoints com facilidade.

---

Migrations e Versionamento de Banco

O projeto utiliza o Flyway para gerenciar as migrations de banco de dados no PostgreSQL. Todas as alterações de estrutura no banco, como criação de tabelas e mudanças de schema, são versionadas e controladas. Isso garante consistência entre os ambientes de desenvolvimento e produção.

---

Funcionalidades

O Controle Verbas é um backend desenvolvido com Spring Boot, com foco em boas práticas e organização de API REST.

🔒 Autenticação e Segurança

• Cadastro e login de usuários
• Autenticação via JWT
• Controle de acesso baseado em perfis de usuário

📚 Gerenciamento de Conteúdo

• Cargos e Departamentos
  • Cadastrar
  • Listar (com paginação e filtros)
  • Editar
  • Soft delete
  • Ativar
• Permissões
  • Organização dos tipos de usuários
• Status
  • Organização dos status dos orçamentos
• Pessoas e Usuários
  • Cadastrar
  • Listar (com paginação e filtros)
  • Editar dados básicos
  • Editar permissões
  • Editar senha
  • Soft delete
  • Ativar
• Orçamentos
  • Cadastrar
  • Listar orçamentos (com paginação e filtros)
  • Aprovar/Reprovar
  • Controlar status
  • Marcar um orçamento como liberado

🛠️ Validações e Tratamento de Erros

• Validação de dados de entrada (DTOs com Bean Validation)
• Mensagens de erro claras e padronizadas
• Tratamento centralizado de exceções

📊 Documentação

• API documentada com Swagger UI

---

Documentação Visual

🌐 API - Swagger

Para ver a interface Swagger em ação, acesse as demonstrações visuais com GIFs interativos mostrando os principais endpoints da API.

🗂️ Diagrama ER do banco de dados PostgreSQL

---

Testes Automatizados

O projeto conta com uma cobertura significativa de testes unitários e de integração, garantindo a qualidade e o correto funcionamento dos fluxos principais de negócio da API, incluindo:

• Cadastro, listagem, ativar/soft delete e edição de cargos, departamentos, pessoas, usuários, orçamentos.
• Autenticação com JWT.
• Validações de regras de negócio.
• Tratamento global de exceções.

Tecnologias utilizadas nos testes

• 🧪 JUnit 5
• 🔧 Mockito
• 🧪 Spring Boot Test

---

Organização do Projeto

Abaixo está um resumo da estrutura de pastas e arquivos principais do projeto:

docs
 ├── gifs/
 ├── documentacao-swagger.md
 └── estrutura-projeto.md

src/main
 ├── java/com/api/controleverbasbackend
 │    ├── controller/
 │    ├── domain
 │    │    ├── entity/
 │    │    └── enums/
 │    ├── dto/
 │    ├── exception/
 │    ├── infra
 │    │    ├── config/
 │    │    ├── documentation/
 │    │    ├── logging/
 │    │    ├── messaging/
 │    │    └── security/
 │    ├── repository/
 │    ├── service/
 │    └── ControleVerbasBackendApplication.java
 ├── resources
 │    ├── db/
 │    └── *.properties
 ├── test/java/com/api/controleverbasbackend
 │    ├── controller
 │    │    ├── negativo/
 │    │    └── positivo/
 │    ├── Kafka/
 │    ├── service
 │    │    ├── negativo/
 │    │    └── positivo/
 │    ├── utils/
 │    └── ControleVerbasBackendApplicationTests.java
 ├── LICENSE
 └── README.md

📌 Para a estrutura completa e detalhada, consulte estrutura-projeto.md.

---

Como Executar o Projeto

Pré-requisitos:

• ☕ Java 17 ou superior
• 🐳 Docker e Docker Compose instalados
• 💻 IDE de sua preferência (IntelliJ IDEA, VSCode, Eclipse etc.)
• 🐧 WSL (se estiver usando Windows)

Passo a passo:

1. Clone o repositório

git clone https://github.com/seu-usuario/controle-verbas-backend.git

2. Acesse a pasta do projeto

cd controle-verbas-backend

3. Inicie os serviços necessários no Docker (PostgreSQL e Kafka)

docker-compose up -d

Isso vai criar os containers do banco de dados e da mensageria. Certifique-se de que as portas configuradas no docker-compose.yml não estejam sendo usadas por outros serviços.

4. Verifique se todos os containers estão disponíveis

docker ps

Verifique se os containers do PostgreSQL e Kafka estão rodando.
⚠️ Se algum container não estiver ativo, volte ao passo 3.

5. Configure o banco de dados no arquivo src/main/resources/application-dev.properties com suas credenciais locais. Ao iniciar o projeto, as migrations serão aplicadas automaticamente pelo Flyway.

spring.datasource.url=jdbc:postgresql://localhost:5432/nome_do_banco
spring.datasource.username=seu_usuario
spring.datasource.password=sua_senha

6. Execute o backend com o Maven Wrapper:

./mvnw spring-boot:run

7. Acesse a API pelo navegador ou ferramentas como Insomnia na porta configurada (por padrão http://localhost:8080).
   ⚠️ Lembre-se de manter o Docker rodando enquanto estiver utilizando a aplicação.

---

Contribuições

Se você quiser contribuir para o projeto, siga estas etapas:

1. Faça um fork deste repositório.
2. Crie uma nova branch (git checkout -b feature/alguma-coisa).
3. Faça suas mudanças.
4. Envie um pull request explicando as mudanças realizadas.

Obrigado pelo interesse em contribuir!

---

Contato

Se tiver dúvidas ou sugestões, sinta-se à vontade para entrar em contato:

• 📧 E-mail: renan.vitor.cm@gmail.com
• 🟦 LinkedIn: Renan Vitor

---

Licença

📌 Este projeto está licenciado sob a Licença MIT, o que significa que você pode utilizá-lo, modificar, compartilhar e distribuir livremente, desde que mantenha os devidos créditos aos autores e inclua uma cópia da licença original - veja o arquivo LICENSE para detalhes ou acesse a licença MIT oficial.