🛍️ Store - E-Commerce de Eletrônicos

Projeto de estudos: Mini e-commerce com Spring Boot (backend) + Flutter (mobile)

---

📋 Sobre o Projeto

E-commerce completo focado em eletrônicos e peças, desenvolvido com as melhores práticas de mercado para fins educacionais.

🎯 Objetivos de Aprendizado

• API REST robusta com Spring Boot
• Autenticação JWT
• Push notifications via Firebase
• Observabilidade completa (OpenTelemetry + Prometheus + Grafana + Elasticsearch)
• Clean Architecture
• Testes automatizados
• CI/CD básico

---

🏗️ Arquitetura

Backend (este repositório)

• Framework: Spring Boot 4.x
• Linguagem: Java 21+
• Database: PostgreSQL 17+
• Migrations: Flyway
• Documentação: Swagger/OpenAPI
• Notificações: Firebase Cloud Messaging
• Segurança: Spring Security + JWT
• Observability: OpenTelemetry + Micrometer + Prometheus

Frontend (separado)

• Flutter 3.x
• Dart
• Provider/Bloc para state management

---

🚀 Funcionalidades

MVP (Fase 1)

• ✅ Catálogo de Produtos

  • Listagem com filtros (categoria, marca, preço)
  • Busca por nome
  • Paginação
  • Detalhes do produto

• ✅ Autenticação e Usuários

  • Cadastro de usuário
  • Login JWT
  • Perfil do usuário
  • Gerenciamento de endereços

• ✅ Carrinho de Compras

  • Adicionar/remover produtos
  • Alterar quantidades
  • Persistência no banco

• ✅ Pedidos

  • Criar pedido a partir do carrinho
  • Acompanhar status (criado, pago, enviado, entregue)
  • Histórico de pedidos

• ✅ Notificações Push

  • Registro de tokens FCM
  • Notificação automática em mudanças de status

Observabilidade (stack e configuração disponíveis)

• OpenTelemetry (traces distribuídos)
• Métricas com Prometheus
• Dashboards Grafana
• Logs estruturados (JSON)

Detalhes e passo a passo: docs/OBSERVABILITY_STACK.md.

---

🛠️ Tecnologias

Core

• Spring Boot 4.x
• Spring Data JPA - Persistência
• Spring Security - Autenticação/Autorização
• Spring Validation - Validações
• Spring Actuator - Health checks e métricas

Dados & Storage

• PostgreSQL - Banco principal
• Flyway - Migrations
• Redis - Cache
• MinIO - Object Storage

Documentação

• SpringDoc OpenAPI 3 - Swagger UI

Notificações

• Firebase Admin SDK - Push notifications

Observabilidade

• OpenTelemetry + Micrometer
• Prometheus - Métricas
• Logstash Logback Encoder - Logs JSON

Testes

• JUnit 5
• Mockito
• Spring Boot Test

DevOps

• Docker / Docker Compose
• Maven - Build
• GitHub Actions - CI
• Qodana - Code Quality

---

📦 Estrutura do Projeto

store-backend/
├── docs/                           # Documentação
│   ├── CATALOG_MODULE_IMPLEMENTED.md
│   ├── DEEP_LINKS_IMPLEMENTATION.md
│   ├── FIREBASE_FCM_INTEGRATION.md
│   ├── GITHUB_ACTIONS.md
│   ├── MINIO_INTEGRATION.md
│   ├── OBSERVABILITY_STACK.md
│   ├── REDIS_INTEGRATION.md
│   └── checklist.md
├── src/
│   ├── main/
│   │   ├── java/br/dev/fca/store/
│   │   │   ├── config/        # Configurações (Security, Swagger)
│   │   │   ├── domain/        # Entidades, Enums
│   │   │   ├── application/   # Services, DTOs, Use Cases
│   │   │   ├── infra/         # Repositories, Integrações
│   │   │   └── web/           # Controllers, Exception Handlers
│   │   └── resources/
│   │       ├── db/migration/  # Scripts Flyway
│   │       └── application.properties
│   └── test/                  # Testes
├── observability/             # Stack de observabilidade (OTel/Tempo/etc)
├── docker-compose.yml         # API (depende de serviços externos)
├── Dockerfile                 # Imagem do backend
└── pom.xml                    # Dependencies

---

🚦 Getting Started

Pré-requisitos

• Java 21+ (Download)
• Maven 3.8+ (ou use o wrapper ./mvnw)
• Docker e Docker Compose (Instalar)
• PostgreSQL 17+ (ou use Docker para subir o banco)

1️⃣ Clone o Repositório

git clone https://github.com/FelipeCostaAraujo/store-backend.git
cd store-backend

2️⃣ Suba as dependências (PostgreSQL, Redis, MinIO)

O backend depende de PostgreSQL, Redis e MinIO.
Você pode usar serviços locais ou Docker e ajustar as variáveis com base no .env.example.

3️⃣ Configure as Variáveis de Ambiente

Use o .env.example como base.
Se rodar via Docker Compose, o .env é carregado automaticamente.

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=storedb
DB_USER=storeuser
DB_PASSWORD=storepass

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# MinIO
MINIO_URL=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=store

# JWT
JWT_SECRET=change-me-in-production-must-be-at-least-256-bits-long
JWT_EXPIRATION=86400
JWT_REFRESH_EXPIRATION=2592000

# Firebase (após configurar)
FIREBASE_CREDENTIALS_PATH=/path/to/serviceAccountKey.json

# App
PORT=3000

4️⃣ Instale as Dependências

./mvnw clean install

5️⃣ Execute as Migrations

./mvnw flyway:migrate

6️⃣ Rode a Aplicação

./mvnw spring-boot:run

A API estará disponível em: http://localhost:3000 (ou a porta definida em PORT)

7️⃣ Acesse o Swagger

Abra no navegador: http://localhost:3000/swagger-ui.html

---

🧪 Testes

Rodar Todos os Testes

./mvnw test

Testes e Build (verify)

./mvnw verify

Coverage Report

./mvnw test jacoco:report

Relatório em: target/site/jacoco/index.html

---

🐳 Docker

Build da Imagem

docker build -t store-backend:latest .

Rodar com Docker Compose (API)

docker compose up --build

Serviço disponível:

• API: http://localhost:6173 (padrão do docker-compose.yml)

Obs.: a API espera PostgreSQL/Redis/MinIO fora do Compose (por padrão em host.docker.internal).

---

📚 Documentação

Endpoints da API

Acesse o Swagger após subir a aplicação.

Guias e integrações

• docs/CATALOG_MODULE_IMPLEMENTED.md - Catálogo
• docs/DEEP_LINKS_IMPLEMENTATION.md - Deep links
• docs/FIREBASE_FCM_INTEGRATION.md - FCM
• docs/MINIO_INTEGRATION.md - Upload de imagens
• docs/REDIS_INTEGRATION.md - Cache
• docs/OBSERVABILITY_STACK.md - Observabilidade
• docs/GITHUB_ACTIONS.md - CI/Qodana
• docs/checklist.md - Backlog e próximos passos

Exemplos de Requisições

Cadastrar Usuário

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Strong@Pass123",
    "name": "João Silva",
    "cpf": "123.456.789-00",
    "phone": "(11) 98765-4321"
  }'

Login

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Strong@Pass123"
  }'

Listar Produtos

curl http://localhost:3000/api/products?page=0&size=20

---

🔐 Firebase Setup (Push Notifications)

1. Crie um projeto no Firebase Console
2. Ative o Cloud Messaging
3. Baixe o arquivo serviceAccountKey.json (Configurações > Service accounts)
4. Guarde o arquivo em um caminho seguro (não versionado)
5. Configure a variável de ambiente FIREBASE_CREDENTIALS_PATH

---

🗃️ Database Schema

Principais Tabelas

• users - Usuários do sistema
• categories - Categorias de produtos
• brands - Marcas
• products - Produtos
• product_images - Imagens dos produtos
• addresses - Endereços de entrega
• carts - Carrinhos de compras
• cart_items - Items do carrinho
• orders - Pedidos
• order_items - Items do pedido
• device_tokens - Tokens FCM para push

---

🤝 Contribuindo

Este é um projeto de estudos, mas contribuições são bem-vindas!

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Padrão de Commits

Seguimos o Conventional Commits:

• feat: nova funcionalidade
• fix: correção de bug
• docs: documentação
• test: testes
• refactor: refatoração
• chore: tarefas gerais

---

📈 Roadmap / Backlog

Veja docs/checklist.md para itens planejados e pendências.

---

📝 License

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

---

👨‍💻 Autor

Felipe Araújo

• GitHub: @FelipeCostaAraujo

---

📞 Contato e Suporte

Para dúvidas ou sugestões, abra uma issue.

---

⭐ Se este projeto te ajudou nos estudos, deixe uma estrela!