Skip to content

README.md

Latest commit

 

History

History
441 lines (311 loc) · 19.7 KB

README.md

File metadata and controls

441 lines (311 loc) · 19.7 KB

Sistema de Notificação de Estoque — API REST

🔗 Frontend

O frontend é desenvolvido em um repositório separado.
Acompanhe releases e evolução da interface em:

🚧 O frontend ainda está em desenvolvimento.

📊 Progresso do Projeto

Planejamento, tarefas e histórico de evolução disponíveis no GitHub Projects:

📑 Sumário

Visão Geral do Projeto

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 de materiais de uso interno (escritório, limpeza, relacionados). 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:

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.

⬆️ Voltar ao início

Tecnologias Utilizadas

Ferramentas Utilizadas

  • 💻 Visual Studio Code: Ambiente de desenvolvimento integrado (IDE) leve e extensível.
  • 🐳 Docker: Utilizado via Docker CLI para execução e gerenciamento dos contêineres do projeto.
  • 🐘 PostgreSQL: Banco de dados relacional executado em contêiner Docker, acessado via CLI (psql).
  • 📡 Insomnia: Ferramenta de teste de APIs REST que permite enviar requisições HTTP, validar respostas e testar endpoints com facilidade.

⬆️ Voltar ao início

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.

⬆️ Voltar ao início

Estratégia de Filtragem nas Listagens

Neste projeto adotei duas abordagens para filtragem em consultas:

  • Para consultas com múltiplos filtros opcionais, utilizei a abordagem baseada em Specifications do 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.

⬆️ Voltar ao início

Funcionalidades

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.

🔒 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

  • 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ções e Tratamento de Erros

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

📊 Documentação

⬆️ Voltar ao início

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.

👉 Veja a documentação visual do Swagger aqui:
📘 Swagger — Demonstrações Visuais da API

🗂️ Diagrama ER do banco de dados PostgreSQL

👉 Veja o diagrama completo aqui:
📊 Diagrama ER — Banco de Dados

⬆️ Voltar ao início

Demonstração das Notificações por E-mail

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

⬆️ Voltar ao início

Mensageria com Apache Kafka

O projeto utiliza Apache Kafka para comunicação assíncrona entre contextos de negócio, com foco em desacoplamento, resiliência e escalabilidade.

A mensageria é utilizada principalmente para eventos de negócio como:

  • criação de pedidos
  • notificações de estoque abaixo do mínimo
  • processamento assíncrono

A arquitetura foi projetada com foco em padrões utilizados no mercado, incluindo:

  • eventos de domínio desacoplados da infraestrutura
  • event envelope padronizado
  • versionamento de eventos
  • retry automático e Dead Letter Topic (DLT)
  • idempotência no consumo
  • correlationId para rastreabilidade
  • Outbox Pattern para consistência transacional

📘 Documentação técnica completa

A documentação técnica completa da arquitetura de mensageria, incluindo fluxos, decisões arquiteturais e diagramas C4, está disponível em:

➡️ Kafka Architecture — Documentação Técnica

⬆️ Voltar ao início

Testes Automatizados

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

⬆️ Voltar ao início

Testando a API via Insomnia

Se preferir usar o Insomnia ao invés do Swagger UI, você pode importar diretamente todos os endpoints prontos para teste.

Passos:

  1. Abra o Insomnia.
  2. Vá em File > Import > From File.
  3. 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.

⬆️ Voltar ao início

Estrutura do Projeto

.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

🔗 Veja a estrutura completa do projeto aqui

⬆️ Voltar ao início

Como Executar o Projeto

Pré-requisitos:

Passos

  1. Clone o repositório:
git clone git@github.com:renancvitor/inventory-notification-system-backend.git
  1. Acesse a pasta do projeto:
cd inventory-notification-system-backend
  1. Inicie os serviços necessários no Docker (PostgreSQL)
docker compose -f docker-compose.dev.yml up -d

Isso 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.

  1. Verifique se todos os containers estão disponíveis
docker ps

⚠️ Se algum container não estiver ativo, volte ao passo 3.

  1. Configure o banco de dados no arquivo src/main/resources/application-dev.yml 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
  1. Execute o backend com o Maven Wrapper no perfil de desenvolvimento:
SPRING_PROFILES_ACTIVE=dev ./mvnw spring-boot:run
  1. 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.

⬆️ Voltar ao início

Deploy na AWS

Este projeto está automaticamente deployado na AWS EC2 com um pipeline de CI/CD robusto e seguro. A aplicação é atualizada automaticamente a cada push para a branch main, garantindo que sempre esteja rodando a versão mais recente do código.

🚀 Arquitetura do Deploy

O processo de deploy é totalmente automatizado através de GitHub Actions:

  1. CI Pipeline - Compila e testa o código a cada push
  2. CD Pipeline - Realiza migração de banco, compila o JAR e faz deploy na EC2
  3. Validação - Verifica se o serviço iniciou corretamente com health checks

💡 Destaques da Automação

  • ✅ Zero Downtime: O serviço é gracefully reiniciado sem perder requisições
  • ✅ Backup Automático: Cada deploy faz backup do JAR anterior
  • ✅ Validação de Saúde: Health check confirma que a aplicação iniciou corretamente
  • ✅ Logs Detalhados: Cada etapa do deploy é registrada para troubleshooting
  • ✅ Secrets Seguros: Todas as credenciais armazenadas no GitHub Secrets

📚 Documentação Completa

Para instruções detalhadas sobre deploy manual, configuração de secrets, troubleshooting e muito mais:

👉 Veja a documentação completa aqui:
🚀 Deploy na AWS — Guia Completo

⬆️ Voltar ao início

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!

⬆️ Voltar ao início

Contato

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

⬆️ Voltar ao início

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.

⬆️ Voltar ao início