O frontend será desenvolvido separadamente. Quando estiver pronto, ficará disponível em um repositório dedicado:
🚧 O frontend ainda está em desenvolvimento. O link será adicionado assim que o repositório estiver disponível.
- Visão Geral do Projeto
- Tecnologias Utilizadas
- Ferramentas Utilizadas
- Migrations e Versionamento de Banco
- Estratégia de Filtragem nas Listagens
- Funcionalidades
- Documentação Visual
- Demonstração das Notificações por E-mail
- Testes Automatizados
- Testando a API via Insomnia
- Estrutura do Projeto
- Como Executar o Projeto
- Contribuições
- Contato
- Licença
Sistema de Notificação de Estoque é um backend desenvolvido com Spring Boot, projetado para gerenciar o estoque e enviar notificações para produtos com baixo estoque.
Desenvolvido principalmente para prática de backend, o projeto também atende pequenas empresas que buscam organizar e monitorar seus processos de estoque. Ele segue uma arquitetura bem organizada em camadas e pacotes funcionais (application, domain, infra, exception e utils), garantindo escalabilidade e manutenção.
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)
O uso de boas práticas e a organização do projeto garantem um código escalável, claro e de fácil manutenção.
-
☕ Backend
- ☕ Java 17 ou superior + 🌱 Spring Boot 3
- 🌐 Spring Web
- 📦 JPA + 🛠️ Hibernate
- ✅ Validações (Bean Validation)
- 🔄 Spring Boot DevTools
- 🔧 Lombok
- 📄 Swagger (OpenAPI)
-
🗄️ Banco de Dados
- 🛠️ Controle de versionamento de banco com Flyway
- 🐘 PostgreSQL: Banco de dados
-
🧰 Ferramentas e Build
- 📦 Maven: Gerenciamento de dependências e build
- 🐧 WSL e 🐳 Docker CLI
- 💻 Visual Studio Code: Ambiente de desenvolvimento integrado (IDE) leve e extensível.
- 🐘 [PostgreSQL (Docker)]: Banco de dados utilizado via contêiner Docker.
- 📡 Insomnia: Ferramenta de teste de APIs REST que permite enviar requisições HTTP, validar respostas e testar endpoints com facilidade.
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.
Neste projeto adotei duas abordagens para filtragem em consultas:
-
Para consultas com múltiplos filtros opcionais, utilizei a abordagem baseada em
Specificationsdo Spring Data JPA. Isso garante flexibilidade, escalabilidade e código mais limpo para cenários complexos. -
Para consultas simples, com filtros únicos ou poucos parâmetros fixos, usei métodos diretos do repositório (
findBy...), para manter simplicidade e performance sem overengineering.
Essa decisão busca balancear clareza, manutenção e boas práticas técnicas, garantindo que o código seja fácil de entender e evoluir.
O Sistema de Notificação de Estoque é um backend desenvolvido com Spring Boot, com foco em boas práticas e organização de API REST.
- Cadastro e login de usuários
- Autenticação via JWT
- Controle de acesso baseado em perfis de usuário
- Permissões
- Organização dos tipos de usuários
- Status
- Organização dos status dos pedidos
- Pessoas e Usuários
- Cadastrar
- Listar (com paginação e filtros)
- Editar permissões
- Editar senha
- Soft delete
- Ativar
- Produtos
- Cadastrar
- Categorias para cada tipo de produto
- Listar produtos (com paginação e filtros)
- Controlar estoque
- Soft delete
- Ativar
- Notificação via e-mail quando estoque abaixo do configurado
- Movimentações
- Entrada e saída
- Validação do estoque - movimentações não ocorrem com estoque menor ou igual a zero
- Envio diário de relatórios de movimentações dos produtos
- Pedidos
- Cadastrar
- Listar pedidos (com paginação e filtros)
- Aprovar/Reprovar
- Controlar status
- Atualizar pedido — permitido apenas enquanto o status for Pendente.
- Estoque atualizado somente após aprovação do pedido
- Validação de dados de entrada (DTOs com Bean Validation)
- Mensagens de erro claras e padronizadas
- Tratamento centralizado e específico de exceções
- API documentada com Swagger UI
Para ver a interface Swagger em ação, acesse as demonstrações visuais com GIFs interativos mostrando os principais endpoints da API.
👉 Veja o diagrama completo aqui:
📊 Diagrama ER — Banco de Dados
O sistema envia notificações automáticas por e-mail para eventos críticos e operacionais, como:
- Estoque abaixo do mínimo configurado
- Relatório diário consolidado de pedidos gerados
🔗 Veja os exemplos reais dos e-mails enviados:
➡️ Exemplos de Notificações por E-mail
O projeto conta com uma cobertura significativa de testes unitários, garantindo a qualidade e o correto funcionamento dos fluxos principais de negócio da API, incluindo:
- Cadastro, listagem, ativar/soft delete e edição dos recursos suportados (pedidos, produtos, pessoas, e usuários).
- 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
Se preferir usar o Insomnia ao invés do Swagger UI, você pode importar diretamente todos os endpoints prontos para teste.
- Abra o Insomnia.
- Vá em File > Import > From File.
- Selecione o arquivo:
docs/insomnia/insomnia-api-export
Isso irá importar todos os endpoints organizados por pastas, com exemplos de requisição e possíveis payloads.
.github/workflows/ # Pipelines de CI: build, testes e validações automatizadas
docs/ # Documentação auxiliar do projeto
├── insomnia/ # Export da coleção da API para testes via Insomnia
├── gifs/ # Demonstrações visuais da API (GIFs usados no Swagger documentation)
├── email-notification/ # Exemplos reais de e-mails enviados pelo sistema
├── email-notification.md # Documento explicando e exibindo as notificações por e-mail
├── inventory-notification-der.png # Diagrama ER do banco de dados PostgreSQL
├── project-structure.md # Estrutura detalhada do projeto e organização dos pacotes
└── swagger-documentation.md # Documentação visual da API com GIFs demonstrativos
src/main/java/
├── application/ # Camada de aplicação: DTOs, serviços, controllers, especificações e repositórios
├── domain/ # Entidades, enums e exceções específicas de cada agregado de domínio
├── exception/ # Exceções genéricas: factories, handlings e modelos de erro
├── infra/ # Configurações, segurança, mensageria e integrações externas
├── utils/ # Utilitários de uso geral (página customizada, mappers, utilidades)
└── InventoryNotificationSystemBackendApplication.java
src/main/resources/
├── db/ # Scripts Flyway (migrations e seeds)
├── application-*.properties # Configurações específicas (dev, prod, secret)
└── application.properties # Configuração padrão
src/test/java/
├── controller/ # Testes unitários dos controllers, organizados por domínio e ação
├── service/ # Testes unitários dos services, com alta cobertura por método
├── utils/ # Fábrica de entidades e mocks reutilizáveis para testes
└── InventoryNotificationSystemBackendApplicationTests.java
src/test/resources/
├── application-test-secret.properties # Secrets isolados para os testes
├── application-test.properties # Configuração do ambiente de testes
└── payload/ # Dados auxiliares em JSONL usados em testes e validações manuais
LICENSE # Licença do projeto
README.md # Documentação principal do repositório
- ☕ Java 17 ou superior
- 🐳 Docker e Docker Compose instalados
- 💻 IDE de sua preferência (IntelliJ IDEA, VSCode, Eclipse etc.)
- 🐧 WSL (se estiver usando Windows)
- Clone o repositório:
git clone git@github.com:renancvitor/inventory-notification-system-backend.git- Acesse a pasta do projeto:
cd inventory-notification-system-backend- Inicie os serviços necessários no Docker (PostgreSQL)
docker-compose up -dIsso vai criar o container do banco de dados PostgreSQL. Certifique-se de que as portas configuradas no docker-compose.yml não estejam sendo usadas por outros serviços.
- Verifique se todos os containers estão disponíveis
docker ps- Configure o banco de dados no arquivo
src/main/resources/application-dev.propertiescom 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- Execute o backend com o Maven Wrapper:
./mvnw spring-boot:run- 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.
Se você quiser contribuir para o projeto, siga estas etapas:
- Faça um fork deste repositório.
- Crie uma nova branch (
git checkout -b feature/alguma-coisa). - Faça suas mudanças.
- Envie um pull request explicando as mudanças realizadas.
Obrigado pelo interesse em contribuir!
Se tiver dúvidas ou sugestões, sinta-se à vontade para entrar em contato:
-
📧 E-mail: renan.vitor.cm@gmail.com
-
🟦 LinkedIn: Renan Vitor
📌 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.