"Não espere 9 meses para ter o seu bebê, adquira agora e calcule em quanto tempo ele chegará em sua casa!"
CegonhaExpress é um sistema completo de entrega especializado em bebês reborn, desenvolvido como projeto acadêmico para demonstrar conceitos avançados de Programação Orientada a Objetos, arquitetura em camadas e integração de APIs.
- 📦 Sobre o Projeto
- 🏗️ Arquitetura Técnica
- 🛠️ Tecnologias Utilizadas
- 🚀 Configuração e Instalação
- 📚 Uso da API
- 🗄️ Configuração de Banco de Dados
- 🧪 Testes
- 🎯 Conceitos Demonstrados
- 🚨 Troubleshooting
- 📊 Monitoramento
- 🔒 Segurança
- 🤝 Contribuição
- 📄 Licença
- 👨💻 Autores
- 📞 Suporte
Sistema de logística e entrega que simula o processo completo de pedido, cálculo de frete e acompanhamento de entregas de bebês reborn, combinando humor e funcionalidade técnica robusta.
- Cálculo de Frete Inteligente: Integração com Google Distance Matrix API para distâncias reais
- Validação de Endereços: Integração com API ViaCEP para validação automática de CEPs
- Gestão de Pedidos: Sistema completo de cadastro e acompanhamento de encomendas
- Múltiplas Modalidades: Entrega expressa (1 dia), padrão (3 dias) e econômica (7 dias)
- API REST Completa: Backend robusto com documentação Swagger/OpenAPI
- Tratamento de Exceções: Sistema global de tratamento de erros
- Catálogo de Bebês: Sistema de visualização de bebês reborn disponíveis
- API REST com documentação Swagger/OpenAPI
- JPA/Hibernate para persistência de dados
- Integração Google Maps para cálculo de distância real
- Integração ViaCEP para validação de CEPs
- Validações robustas com Bean Validation
- Tratamento de exceções personalizado
- CORS configurado para frontend
- H2 para desenvolvimento e testes
- MariaDB preparado para produção
- Modelagem otimizada com relacionamentos JPA
- Indices para performance em consultas frequentes
Backend:
- Java 21+
- Spring Boot 3.5.0
- Spring Data JPA
- Spring Web
- Bean Validation
- H2/MariaDB
- Google Maps Services 2.2.0
- SpringDoc OpenAPI 2.8.8
Ferramentas:
- Maven 3.6+
- Lombok
- SLF4J
- Java 21 ou superior
- Maven 3.6+
- IDE de sua preferência (IntelliJ IDEA, Eclipse, VS Code)
- Conta Google Cloud (para Google Maps API)
git clone https://github.com/GabrielCoelho/cegonha-express-delivery.git
cd cegonha-express-delivery- Acesse o Google Cloud Console
- Crie um novo projeto ou selecione um existente
- No menu de navegação, vá em APIs e Serviços → Biblioteca
- Pesquise por "Distance Matrix API"
- Clique em Distance Matrix API e depois em ATIVAR
- No Google Cloud Console, vá em APIs e Serviços → Credenciais
- Clique em + CRIAR CREDENCIAIS → Chave de API
- Copie a chave gerada
- [RECOMENDADO] Clique em RESTRINGIR CHAVE e configure:
- Restrições de API: Selecione apenas "Distance Matrix API"
- No Google Cloud Console, vá em Faturamento
- Vincule um cartão de crédito ao projeto
- Nota: O Google oferece $200 de créditos gratuitos mensais
# Copie o template de configuração
cp src/main/resources/application-template.yml src/main/resources/application-local.ymlEdite o arquivo src/main/resources/application-local.yml:
spring:
# Configurações de banco de dados MariaDB
datasource:
url: jdbc:mariadb://localhost:3306/cegonha_express
driver-class-name: org.mariadb.jdbc.Driver
username: seu_usuario_aqui # <- SUBSTITUA PELO USUARIO CRIADO
password: sua_senha_aqui # ← SUBSTITUA PELA SUA SENHA
{...}
# Google Maps API Configuration
google:
maps:
api:
key: "SUA_API_KEY_AQUI" # ← SUBSTITUA PELA SUA API KEYAntes de executar a aplicação, certifique-se de que o MariaDB está rodando:
# No Ubuntu/Debian
sudo apt update
sudo apt install mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb
# No macOS (via Homebrew)
brew install mariadb
brew services start mariadb
# No Windows
# Baixe e instale o MariaDB do site oficialCrie o banco de dados:
# Conecte ao MariaDB
mysql -u root -p
# Crie o banco de dados
CREATE DATABASE cegonha_express CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# Crie um usuário específico (opcional, mas recomendado)
CREATE USER 'cegonhaex'@'localhost' IDENTIFIED BY 'cegonha';
GRANT ALL PRIVILEGES ON cegonhaexpress.* TO 'cegonhaex'@'localhost';
FLUSH PRIVILEGES;Alternativa com H2 (para desenvolvimento rápido):
Se preferir usar H2 para desenvolvimento local, substitua a configuração do datasource por:
spring:
datasource:
url: jdbc:h2:mem:cegonhadb
driver-class-name: org.h2.Driver
username: sa
password: ""
jpa:
properties:
hibernate:
dialect: org.hibernate.dialect.H2Dialect
# Console H2 (apenas para H2)
h2:
console:
enabled: true
path: /h2-console# Compilar e executar
./mvnw spring-boot:run
# Ou compilar e executar JAR
./mvnw clean package
java -jar target/cegonha-express-0.0.1-SNAPSHOT.jar- Importe o projeto como projeto Maven
- Execute a classe
CegonhaExpressApplication.java
- API Documentation: http://localhost:8080/swagger-ui/index.html
- Aplicação: http://localhost:8080
Para H2 (se estiver usando):
- H2 Console: http://localhost:8080/h2-console
- JDBC URL:
jdbc:h2:mem:cegonhadb - Username:
sa - Password: (deixar em branco)
- JDBC URL:
Você pode utilizar a Swagger UI para verificar todos os endpoints criados, ou ler a nossa documentação completa do Uso da API
- 200: Sucesso
- 201: Criado com sucesso
- 204: Sem conteúdo
- 400: Dados inválidos
- 404: Recurso não encontrado
- 409: Conflito de estado
- 415: Tipo de mídia não suportado
- 503: Serviço indisponível
MariaDB está configurado como padrão nesta fase do projeto pois estamos próximos da apresentação final do mesmo.
Para usar H2 (desenvolvimento rápido), veja a seção "Alternativa com H2" na configuração do application-local.yml.
# Executar todos os testes
./mvnw testObservação: Estamos com uma cobertura quase completa de testes que foram criados em cada implementação. Conforme o projeto foi ficando mais robusto, alguns testes podem retornar falhas e/ou erros por já não estarem atualizados. É algo que a equipe focará na semana da apresentação.
Use o Swagger UI ou ferramentas como Postman/Insomnia para testar os endpoints.
- Herança:
BaseEntitycomo classe pai para todas as entidades - Polimorfismo: Enum
TipoEntregacom comportamentos diferentes - Encapsulamento: Proteção de dados nas entidades
- Abstração: Interfaces para repositories e services
- Strategy Pattern: Cálculo de fretes por modalidade na classe
Frete - Factory Pattern: Criação de objetos via construtores especializados
- DTO Pattern: Transferência de dados entre camadas
- Repository Pattern: Abstração de acesso a dados
- Controller: Endpoints REST
- Service: Lógica de negócio
- Repository: Acesso a dados
- Entity: Modelo de domínio
- DTO: Transferência de dados
- Config: Configurações da aplicação
GoogleMapsIntegrationException: API_KEY_INVALID
Solução: Verifique se a chave API está correta e se a Distance Matrix API está habilitada.
org.h2.jdbc.JdbcSQLNonTransientConnectionException
Solução: Verifique se as configurações do banco no application-local.yml estão corretas.
Solução: Certifique-se de enviar Content-Type: application/json nas requisições POST/PUT.
404 - CEP não encontrado na base de dados dos Correios
Solução: Verifique se o CEP é válido. A API ViaCEP pode estar temporariamente indisponível.
Para debugar problemas, habilite logs detalhados:
logging:
level:
br.com.cegonhaexpress: DEBUG
com.google.maps: DEBUG
org.springframework.web: DEBUG- Performance de API: Tempo de resposta das requisições
- Taxa de Erro: Percentual de requisições com erro
- Uso da API Google: Número de chamadas à Distance Matrix API
- Uso da API ViaCEP: Número de consultas de CEP
- API Key: Nunca commite a chave do Google Maps no código
- Banco de Dados: Use senhas fortes em produção
- CORS: Configure origens permitidas adequadamente
- HTTPS: Use HTTPS em produção
- Rate Limiting: Implemente rate limiting para APIs públicas
- Nomenclatura: CamelCase para Java, snake_case para banco
- Documentação: JavaDoc para métodos públicos
- Testes: Cobertura mínima de 80%
- Commits: Mensagens claras e descritivas
main: Código estável de produçãodevelop: Código desenvolvido e em teste das duas equipes: Back e Frontendbackend: Código implementado pela equipe de backend testado somente dentro deste escopofrontend: Código implementado pela equipe de fronend testado somente dentro deste escopo
feat/*: Novas funcionalidades a serem implementadas(bug/hot)fix/*: Correções de bugs
Bem-vindo ao Cegonha Express! Este guia irá ajudá-lo a navegar pela nossa plataforma e realizar pedidos de bebês Reborn de forma simples e rápida.
Ao acessar nosso site, você terá duas opções principais:
- Acessar o Catálogo: Para explorar e encomendar bebês Reborn
- Rastrear Pedido: Para acompanhar o status da sua encomenda
Navegue pelo nosso catálogo completo com todas as opções de bebês Reborn disponíveis para pronta entrega.
- Explore as diversas opções com diferentes características
- Encontre o bebê que conquista seu coração
- Clique em "FAZER PEDIDO" no bebê escolhido
Você será direcionado para uma página de checkout onde deverá:
- Informar seus dados pessoais
- Preencher o endereço de entrega completo
- Verificar se o CEP está correto
⚠️ Atenção: Caso informe um CEP inválido, você receberá uma mensagem de erro. Certifique-se de inserir um CEP válido para prosseguir.
- Revise todas as informações inseridas
- Escolha o tipo de entrega desejado
- Confirme o pedido
| Tipo | Descrição |
|---|---|
| 🚚 Econômica | Opção mais acessível com prazo estendido |
| 📦 Padrão | Equilibrio entre preço e prazo |
| ⚡ Express | Entrega mais rápida |
Após finalizar o pedido, você receberá:
- Notificação de confirmação
- Código de rastreio para acompanhar sua encomenda
- Clique em "Rastreio" na página principal ou na barra de navegação
- Digite o código de rastreio fornecido na confirmação do pedido
- Clique em "Rastrear Encomenda"
Seu pedido passará pelos seguintes status:
- Nossas cegonhas estão preparando seu bebê
- Status inicial após confirmação do pedido
- Seu bebê está quase pronto para a viagem
- Informações de frete e prazo de entrega disponíveis
- Seu bebê saiu do ninho e está a caminho do seu novo lar
- Acompanhe a jornada até a entrega
- Seu bebê chegou ao destino
- Pedido finalizado com sucesso
- Pedido cancelado (quando aplicável)
- Disponível para confirmação na tela de rastreio
📝 Para Administradores/Cegonhas
O painel administrativo permite:
- Gerenciar status dos pedidos
- Avançar etapas de entrega
- Cancelar pedidos quando necessário
- Monitorar bebês nos ninhos e em trânsito
- Acompanhar bebês que ainda estão sendo preparados
- Monitorar entregas em andamento
- Manter status atualizados em tempo real
Em caso de dúvidas ou problemas:
- Verifique se o CEP informado está correto
- Certifique-se de ter o código de rastreio em mãos
- Entre em contato com nossa equipe de suporte
💝 Cegonha Express - Realizando sonhos sem a espera de 9 meses!
Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
| Desenvolvedor | Responsabilidade Principal | GitHub |
|---|---|---|
| Gabriel Coelho Soares | Liderança, Arquitetura Backend, Integração APIs | @GabrielCoelho |
| Brenda Gaudêncio | Frontend React, UI/UX | @brendagaudencio |
| Marcos Moreira | Dados, Configuração AWS | @JamalShadowDev |
| Renan Mazzilli | DevOps, Build Tools | @renan-mazzilli |
| Adryelle Calefi | Gestão, Documentação | @DryCaleffi |
| Guilherme Garcia | Code Review, Testes | @HiroGarcia |
| Mateus Nascimento | Gestão, Apresentação | @M-Araujo26 |
| Tabata Etiéle | Code Review, Documentação | @TabataEtiele |
| Thaito Batalini | Code Review, Apresentação | @thaitoGB |
Para dúvidas e suporte:
- Issues: Abra uma issue no GitHub
- Documentação: Consulte a documentação da API via Swagger e nossos arquivos de Documentação
Projeto desenvolvido com ☕ para fins acadêmicos - FATEC 2025