💊 API da Loja de Suplementos

Uma API RESTful para uma loja online de suplementos, construída com Node.js, TypeScript e Express. Possui autenticação de usuários, gerenciamento de produtos, processamento de pagamentos via Pix com Woovi, hospedagem de imagens via ImgBB, cache com Redis e observabilidade completa com logs estruturados e métricas Prometheus.

---

📋 Sumário

• Visão Geral
• Arquitetura
• Stack Tecnológica
• Estrutura do Projeto
• Endpoints da API
• Variáveis de Ambiente
• Executando o Projeto
• Executando os Testes

---

Visão Geral

A API da Loja de Suplementos permite que clientes naveguem e comprem suplementos via pagamentos Pix, enquanto administradores gerenciam o catálogo de produtos. O status do pagamento é atualizado automaticamente via webhooks da Woovi. O sistema utiliza Redis para cachear respostas paginadas de produtos e pedidos, reduzindo a carga no banco de dados.

---

Arquitetura

┌─────────────────────────────────────────────────────────┐
│                        Cliente                          │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP
┌────────────────────────▼────────────────────────────────┐
│                   Servidor Express                       │
│  ┌──────────────┐  ┌───────────┐  ┌──────────────────┐ │
│  │ Rate Limiter │  │  Helmet   │  │  logs pino-http   │ │
│  └──────────────┘  └───────────┘  └──────────────────┘ │
│                                                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │                     Rotas                         │  │
│  │  /api/auth   /api/supplements   /api/payment      │  │
│  └──────────────────┬────────────────────────────────┘  │
│                     │                                    │
│  ┌──────────────────▼────────────────────────────────┐  │
│  │               Middlewares                         │  │
│  │   AuthMiddleware · RoleMiddleware · Validate(Zod) │  │
│  └──────────────────┬────────────────────────────────┘  │
│                     │                                    │
│  ┌──────────────────▼────────────────────────────────┐  │
│  │                  Controllers                      │  │
│  └──────────────────┬────────────────────────────────┘  │
│                     │                                    │
│  ┌──────────────────▼────────────────────────────────┐  │
│  │                  Services                         │  │
│  └──────┬────────────────────────┬───────────────────┘  │
│         │                        │                       │
│  ┌──────▼──────┐         ┌───────▼──────┐               │
│  │   MongoDB   │         │  Redis Cache │               │
│  │  (Mongoose) │         │  (Upstash)   │               │
│  └─────────────┘         └──────────────┘               │
└─────────────────────────────────────────────────────────┘
         │                        │
┌────────▼────────┐      ┌────────▼────────┐
│  ImgBB (imagens)│      │  Woovi (Pix)    │
└─────────────────┘      └─────────────────┘

Fluxo de Requisição

1. A requisição passa pelo rate limiter global e pelos middlewares de segurança (Helmet, CORS)
2. Middlewares específicos de rota são aplicados: autenticação JWT, verificação de papel (role) e validação com Zod
3. O controller delega ao serviço correspondente
4. Os serviços interagem com MongoDB, cache Redis e APIs externas (ImgBB, Woovi)
5. Erros sobem até o handler global de erros, que responde com JSON estruturado usando AppError

Estratégia de Cache

• Respostas de GET /supplements são cacheadas por 60 segundos com a chave supplements:{page}:{limit}
• Respostas de GET /order/* são cacheadas por 30 segundos com as chaves orders:user:{id}:{page}:{limit} e orders:admin:{page}:{limit}
• O cache é invalidado em operações de escrita (criar/deletar/atualizar suplemento, novo pedido de pagamento)

Fluxo de Pagamento

POST /api/payment
       │
       ▼
  Busca suplementos e calcula o total
       │
       ▼
  POST para a API da Woovi → obtém QR Code + brCode
       │
       ▼
  Salva o Pedido (isPaid: false)
       │
       ▼
  Retorna o QR Code ao cliente
       │
       ▼ (assíncrono, via webhook)
  POST /api/payment/webhook (Woovi)
       │
       ▼
  Encontra o Pedido pelo correlationID → define isPaid: true

---

Stack Tecnológica

Camada	Tecnologia
Runtime	Node.js + TypeScript
Framework	Express
Banco de Dados	MongoDB (Mongoose + mongoose-paginate-v2)
Cache	Redis (Upstash)
Autenticação	JWT (jsonwebtoken) + bcryptjs
Validação	Zod
Upload de Arquivos	Multer + ImgBB API
Pagamentos	Woovi (Open Pix)
Logging	Pino + pino-pretty (dev) / pino file transport (prod)
Métricas	Prometheus (prom-client)
Segurança	Helmet + CORS + express-rate-limit
Testes	Jest

---

Estrutura do Projeto

src/
├── controllers/
│   ├── auth/
│   │   ├── LoginController.ts
│   │   └── RegisterController.ts
│   ├── payments/
│   │   └── PaymentsController.ts
│   └── supplements/
│       └── SupplementsController.ts
│
├── services/
│   ├── ConvertImages.ts
│   ├── CreatePaymentService.ts
│   ├── CreateSupplement.ts
│   ├── CreateUser.ts
│   ├── DeleteSupplementService.ts
│   ├── GetOrdersService.ts
│   ├── GetSupplementsService.ts
│   ├── UpdateSupplementService.ts
│   └── ValidateUser.ts
│
├── models/
│   ├── Order.ts
│   ├── Supplement.ts
│   └── User.ts
│
├── middlewares/
│   ├── AuthMiddleware.ts
│   ├── RateLimiter.ts
│   ├── RoleMiddleware.ts
│   └── ValidateMiddleware.ts
│
├── routes/
│   ├── authRoutes.ts
│   ├── paymentsRoutes.ts
│   └── supplementsRoutes.ts
│
├── validators/
│   ├── auth.validator.ts
│   ├── payments.validator.ts
│   └── supplements.validator.ts
│
├── db/
│   └── connectToDB.ts
│
├── lib/
│   └── cache.ts
│
├── observability/
│   └── logger.ts
│
├── utils/
│   └── AppError.ts
│
└── server.ts

---

Endpoints da API

Autenticação — /api

Método	Caminho	Auth	Descrição
POST	/register	—	Registrar um novo usuário
POST	/login	—	Fazer login e receber um token JWT

POST /register — Body

{
  "username": "joaosilva",
  "email": "joao@exemplo.com",
  "password": "senha123"
}

POST /login — Body

{
  "email": "joao@exemplo.com",
  "password": "senha123"
}

---

Suplementos — /api

Método	Caminho	Auth	Papel	Descrição
GET	/supplements	—	—	Listar suplementos (paginado)
POST	/supplements	✅ JWT	admin	Adicionar um novo suplemento com imagens
PATCH	/supplements/:id	✅ JWT	admin	Atualizar um suplemento
DELETE	/supplements/:id	✅ JWT	admin	Deletar um suplemento

GET /supplements — Parâmetros de query

?page=1&limit=10

POST /supplements — multipart/form-data

name        string
description string (máx. 400 caracteres)
price       number
image       arquivo(s) (até 5)

---

Pagamentos — /api

Método	Caminho	Auth	Papel	Descrição
POST	/payment	✅ JWT	customer	Criar um pagamento Pix
POST	/payment/webhook	—	—	Webhook da Woovi para confirmação de pagamento
GET	/order/admin	✅ JWT	admin	Listar todos os pedidos (paginado)
GET	/order/costumer	✅ JWT	—	Listar pedidos do usuário autenticado

POST /payment — Body

{
  "supplementsIds": ["id1", "id2"],
  "addressUser": "Rua Principal, 123"
}

---

Sistema

Método	Caminho	Descrição
GET	/health	Verificação de saúde (status do DB + uptime)
GET	/metrics	Métricas do Prometheus

---

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Servidor
PORT=3000
NODE_ENV=development

# Banco de Dados
MONGODB_URI=mongodb://localhost:27017/supplements-store

# Cache
UPSTASH_REDIS_REST_URL=redis://localhost:6379

# Autenticação
JWT_SECRET=seu_jwt_secret_aqui

# APIs Externas
IMGBB_API_KEY=sua_chave_imgbb
WOOVI_API_URL=https://api.woovi.com/api/v1/charge
WOOVI_API_KEY=sua_chave_woovi

# Logging
LOG_LEVEL=debug

Variável	Descrição
PORT	Porta em que o servidor escuta
NODE_ENV	development ou production
MONGODB_URI	String de conexão com o MongoDB
UPSTASH_REDIS_REST_URL	URL de conexão com o Redis
JWT_SECRET	Chave secreta para assinar tokens JWT
IMGBB_API_KEY	Chave de API do imgbb.com
WOOVI_API_URL	Endpoint de cobrança da Woovi (OpenPix)
WOOVI_API_KEY	Chave de autorização da API da Woovi
LOG_LEVEL	Nível de log do Pino (debug, info, warn, error)

---

Executando o Projeto

Pré-requisitos

• Node.js 18+
• MongoDB
• Redis

Instalar dependências

npm install

Desenvolvimento

npm run dev

Build de produção

npm run build
npm start

---

Executando os Testes

Os testes utilizam Jest com mock de módulos para todas as dependências externas (MongoDB, Redis, axios). Não são necessárias conexões reais para executar a suíte de testes.

# Executar todos os testes
npm test

# Modo watch
npm run test:watch

# Relatório de cobertura
npm run test:coverage

Cobertura de testes

Suite	O que é testado
ConvertImages.test.ts	Upload no ImgBB, codificação base64, tratamento de erros
CreatePayment.test.ts	Cálculo de preço, chamada à API da Woovi, persistência do pedido
CreateSupplement.test.ts	Criação de suplemento, salvamento no DB, tratamento de erros
CreateUser.test.ts	Verificação de duplicatas, criação de usuário, chamadas ao logger