Pular para o conteúdo principal

Guia de Desenvolvimento Local

Guia completo para configurar e rodar o projeto LJ Velas e Aromas em ambiente de desenvolvimento.

Sumário​

  1. Pré-requisitos
  2. Instalação passo a passo
  3. Configuração do .env
  4. Banco de dados
  5. Upload de imagens em dev
  6. Testando pagamentos
  7. Testando webhooks
  8. Ferramentas de desenvolvimento
  9. Problemas comuns

Pré-requisitos​

Certifique-se de ter as seguintes ferramentas instaladas antes de começar:

FerramentaVersão mínimaDownload
Node.js20.x LTShttps://nodejs.org
npm10.xIncluído com Node.js
Git2.xhttps://git-scm.com
MySQL8.0+https://dev.mysql.com/downloads/
Docker + Docker Compose24.x / 2.xhttps://www.docker.com (opcional, recomendado)

Dica: Use o Docker para o banco de dados em desenvolvimento — é o caminho mais rápido e evita conflitos de configuração.

Verifique suas versões:

node -v        # v20.x.x ou superior
npm -v         # 10.x.x ou superior
docker -v      # Docker version 24.x.x
git --version  # git version 2.x.x

Instalação passo a passo​

1. Clone o repositório​

git clone https://github.com/seu-usuario/ljvemasearomas.git
cd ljvemasearomas

2. Instale as dependências​

npm install

O script postinstall executa prisma generate automaticamente após a instalação.

3. Configure as variáveis de ambiente​

Copie o arquivo de exemplo:

cp .env.example .env

Edite o .env com suas configurações locais. Consulte a seção Configuração do .env para detalhes de cada variável.

4. Suba o banco de dados​

Com Docker (recomendado):

npm run db:up

Isso inicia um container MySQL 8.0 e o phpMyAdmin. Aguarde alguns segundos para o MySQL inicializar completamente.

Com MySQL local:

Certifique-se de que o serviço MySQL está rodando e crie o banco manualmente:

CREATE DATABASE ljvemasearomas CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE ljvemasearomas_shadow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

5. Sincronize o schema com o banco​

npm run db:push

Isso aplica o schema do Prisma ao banco de dados sem gerar arquivos de migração (ideal para desenvolvimento).

6. Execute o seed​

npm run db:seed

O seed cria os seguintes usuários de teste:

PapelE-mailSenha
Administradoradmin@ljvemasearomas.com.bradmin123
Clientecliente@teste.comcliente123

Além dos usuários, o seed popula categorias, produtos, cupons e configurações básicas da loja.

7. Inicie o servidor de desenvolvimento​

npm run dev

A aplicação estará disponível em http://localhost:3000.

Configuração do .env​

Abaixo está a referência completa de todas as variáveis de ambiente. As marcadas com * são obrigatórias para rodar o projeto localmente.

Banco de dados​

# * URL de conexão principal do Prisma
# Formato: mysql://USER:PASSWORD@HOST:PORT/DATABASE
DATABASE_URL="mysql://root:root@localhost:3306/ljvemasearomas"

# * Banco sombra do Prisma (usado em migrações — pode ser o mesmo host, outro banco)
SHADOW_DATABASE_URL="mysql://root:root@localhost:3306/ljvemasearomas_shadow"

Com Docker: o Docker Compose sobe o MySQL na porta 3306 com usuário root e senha root. Use os valores acima sem alteração.

Autenticação​

# * Chave secreta para assinar JWT — deve ter pelo menos 32 caracteres
# Gere com: openssl rand -hex 32
JWT_SECRET="sua-chave-secreta-de-pelo-menos-32-caracteres"

Upload de arquivos​

# * Caminho absoluto (ou relativo) onde os uploads serão salvos
# Em dev, use o diretório público do Next.js para servir imagens diretamente
UPLOAD_DIR="./public/uploads/products"

# * URL base pública das imagens (prefixo usado nas URLs retornadas pela API)
UPLOAD_URL_BASE="http://localhost:3000/uploads/products"

E-mail (SMTP)​

# * Host do servidor SMTP
EMAIL_HOST="smtp.gmail.com"

# * Porta SMTP (587 para TLS, 465 para SSL, 25 para sem criptografia)
EMAIL_PORT="587"

# * Usuário de autenticação SMTP (geralmente o próprio e-mail)
EMAIL_USER="seu-email@gmail.com"

# * Senha de autenticação SMTP
# Para Gmail: use uma "Senha de App" (não a senha da conta)
# Acesse: https://myaccount.google.com/apppasswords
EMAIL_PASS="sua-senha-de-app"

# * E-mail remetente (aparece no "De:" das mensagens)
EMAIL_FROM="LJ Velas e Aromas <seu-email@gmail.com>"

Alternativa: Use Mailtrap ou Resend para capturar e-mails de desenvolvimento sem enviá-los de verdade.

Mercado Pago​

# * Token de acesso da conta Mercado Pago
# Em desenvolvimento, use o token de TESTE (começa com TEST-)
# Obtenha em: https://www.mercadopago.com.br/developers/panel/app
MERCADOPAGO_ACCESS_TOKEN="TEST-0000000000000000-000000-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-000000000"

# * Chave pública (usada no frontend para o SDK do MP)
# Também começa com TEST- em modo sandbox
NEXT_PUBLIC_MP_PUBLIC_KEY="TEST-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Frete​

# * CEP de origem para cálculo de frete (endereço do remetente/loja)
STORE_ORIGIN_CEP="01310-100"

Variáveis opcionais​

# URL base da aplicação (usada para gerar links absolutos em e-mails)
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Chave da API para o serviço de NF-e (PHP microservice em /nfe-service)
NFE_API_KEY=""

# URL do serviço de NF-e
NFE_SERVICE_URL="http://localhost:8001"

# Integração com HyperDX (observabilidade / APM)
HYPERDX_API_KEY=""
OTEL_SERVICE_NAME="ljvemasearomas-dev"

Banco de dados​

Com Docker (recomendado)​

O projeto inclui um docker-compose.yml que sobe MySQL 8.0 e phpMyAdmin:

# Subir containers
npm run db:up

# Parar containers (mantém os dados)
npm run db:down

# phpMyAdmin disponível em http://localhost:8080
# Servidor: db | Usuário: root | Senha: root

Com MySQL local​

  1. Certifique-se de que o MySQL 8.0+ está rodando
  2. Crie dois bancos: ljvemasearomas e ljvemasearomas_shadow
  3. Atualize DATABASE_URL e SHADOW_DATABASE_URL no .env

Comandos Prisma​

ComandoDescrição
npm run db:pushSincroniza o schema com o banco (sem histórico de migração)
npm run db:seedPopula o banco com dados de teste
npm run db:resetApaga tudo e recria com seed (use com cuidado!)
npm run db:studioAbre o Prisma Studio em http://localhost:5555
npx prisma migrate devCria e aplica uma migração com histórico
npx prisma migrate resetReseta o banco e reaplica todas as migrações
npx prisma generateRegenera o Prisma Client após alterar o schema

Quando usar db:push vs migrate dev?

  • db:push é mais rápido para exploração e prototipagem — não gera arquivos de migração.
  • migrate dev gera arquivos SQL de migração versionados — use quando quiser que as mudanças sejam rastreadas e aplicadas em produção via prisma migrate deploy.

Upload de imagens em dev​

Em desenvolvimento, as imagens de produto são salvas no diretório público do Next.js para que possam ser servidas diretamente pelo servidor de desenvolvimento:

Configuração​

No .env, defina:

UPLOAD_DIR="./public/uploads/products"
UPLOAD_URL_BASE="http://localhost:3000/uploads/products"

Criando o diretório​

mkdir -p public/uploads/products

O diretório public/uploads/ já está listado no .gitignore — os arquivos de imagem não serão commitados.

Atenção: Essa configuração usa o ./public do Next.js, que serve arquivos estáticos diretamente. Em produção, o UPLOAD_DIR aponta para um caminho fora do diretório da aplicação (ex.: /home/USER/uploads/products). Nunca use o public/ do Next.js em produção para uploads, pois o conteúdo seria sobrescrito a cada novo deploy.

Testando pagamentos​

O Mercado Pago oferece um ambiente sandbox completo para testar pagamentos sem movimentar dinheiro real.

Configurando o sandbox​

  1. Acesse o Painel de Desenvolvedores do Mercado Pago
  2. Crie uma aplicação (ou use uma existente)
  3. Na aba Credenciais de teste, copie:
    • Access Token (começa com TEST-) → MERCADOPAGO_ACCESS_TOKEN
    • Public Key (começa com TEST-) → NEXT_PUBLIC_MP_PUBLIC_KEY

Cartões de teste​

Use os seguintes cartões para simular diferentes cenários:

CenárioNúmero do cartãoCódigoValidade
Pagamento aprovado5031 4332 1540 635112311/25
Pagamento pendente4235 6477 2802 568212311/25
Pagamento recusado3753 651535 56885123411/25
Saldo insuficiente5031 7557 3453 060412311/25

Dados do titular (sandbox): Use qualquer CPF válido (ex.: 000.000.001-91) e qualquer nome.

Referência completa: https://www.mercadopago.com.br/developers/pt/docs/checkout-api/additional-content/your-integrations/test/cards

Usuários de teste do MP​

Para testar o fluxo completo (comprador + vendedor), crie usuários de teste no painel do MP:

  1. Painel → Ferramentas de teste → Contas de teste
  2. Crie um usuário Comprador e um Vendedor
  3. Use as credenciais do Vendedor no .env

Testando webhooks​

O Mercado Pago precisa enviar notificações de pagamento (webhooks) para uma URL publicamente acessível. Em desenvolvimento local, use o localtunnel para expor seu servidor.

Iniciando o tunnel​

npm run dev:tunnel

O script exibe uma URL pública no formato https://xxxx.loca.lt. Exemplo:

Tunnel URL: https://meu-tunnel.loca.lt

Configurando o webhook no MP​

  1. Acesse: Painel MP → Sua aplicação → Webhooks
  2. Na URL de notificação, informe: https://meu-tunnel.loca.lt/api/webhooks/mercadopago
  3. Selecione os eventos: payment

Fluxo de teste​

  1. npm run dev em um terminal
  2. npm run dev:tunnel em outro terminal
  3. Realize um pagamento de teste
  4. Observe os logs no terminal do npm run dev — você verá as notificações do MP chegando em /api/webhooks/mercadopago

Importante: A URL do localtunnel muda a cada reinício. Lembre-se de atualizar o webhook no painel do MP sempre que reiniciar o tunnel.

Ferramentas de desenvolvimento​

Prisma Studio​

Interface gráfica para visualizar e editar dados do banco diretamente no navegador:

npm run db:studio
# Acesse: http://localhost:5555

phpMyAdmin (Docker)​

Interface web completa para administração do MySQL:

URL: http://localhost:8080
Servidor: db
Usuário: root
Senha: root

Disponível apenas quando os containers Docker estão ativos (npm run db:up).

ESLint​

# Verificar erros (sem corrigir)
npm run lint

# Corrigir erros automaticamente
npm run lint:fix

O projeto usa configuração estrita — --max-warnings=0 no CI, ou seja, zero warnings são tolerados no pipeline.

TypeScript​

# Verificar tipos sem gerar arquivos
npx tsc --noEmit

# Verificar em modo watch
npx tsc --noEmit --watch

Teste de conexão SMTP​

npm run test:smtp

Esse script verifica se as configurações de e-mail no .env estão corretas, tentando se conectar ao servidor SMTP e enviando um e-mail de teste.

Problemas comuns​

Error: Can't reach database server​

Causa: O MySQL não está rodando ou a DATABASE_URL está errada.

Solução:

# Com Docker:
npm run db:up

# Verifique se o container está rodando:
docker ps

# Confira as credenciais na DATABASE_URL do .env

Error: P1010 - User was denied access on the database​

Causa: O usuário MySQL não tem permissão no banco especificado.

Solução:

GRANT ALL PRIVILEGES ON ljvemasearomas.* TO 'root'@'localhost';
GRANT ALL PRIVILEGES ON ljvemasearomas_shadow.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

Error: Environment variable not found: DATABASE_URL​

Causa: O arquivo .env não existe ou não foi carregado.

Solução:

# Certifique-se de que o .env existe:
ls -la .env

# Se não existir, copie do exemplo:
cp .env.example .env

Module not found: @/...​

Causa: O Prisma Client não foi gerado ou os alias TypeScript não estão configurados.

Solução:

npx prisma generate
npm install

EACCES: permission denied, mkdir './public/uploads'​

Causa: O Node.js não tem permissão para criar o diretório de uploads.

Solução:

mkdir -p public/uploads/products
# No Linux/macOS, se necessário:
chmod 755 public/uploads/products

Porta 3000 já em uso​

Causa: Outro processo está usando a porta 3000.

Solução:

# Descobrir qual processo está na porta 3000:
# Windows:
netstat -ano | findstr :3000

# Linux/macOS:
lsof -i :3000

# Encerrar o processo ou usar outra porta:
PORT=3001 npm run dev

Seed falha com Unique constraint failed​

Causa: O banco já tem dados do seed anterior.

Solução:

# Reset completo (apaga todos os dados e resemeia):
npm run db:reset

Localtunnel mostra "Tunnel not found"​

Causa: O servidor de desenvolvimento não está rodando quando o tunnel é iniciado, ou a porta está errada.

Solução:

  1. Certifique-se de que npm run dev está rodando em outro terminal
  2. O tunnel usa a porta 3000 por padrão — se você alterou a porta, edite scripts/dev-tunnel.mjs

E-mails não chegam no Gmail​

Causa: Gmail bloqueou o acesso por "app menos seguro" ou a senha está errada.

Solução:

  1. Ative a verificação em duas etapas na conta Google
  2. Gere uma Senha de App: https://myaccount.google.com/apppasswords
  3. Use essa senha no EMAIL_PASS (não a senha da conta Google)
  4. Teste com: npm run test:smtp