Problemas Comuns no Desenvolvimento

Esta página documenta problemas comuns encontrados durante o desenvolvimento do Sistema Divino Alimento e suas soluções.

Problemas com Porta

Porta 3000 já em uso

Sintoma:

Error: listen EADDRINUSE: address already in use :::3000

Solução:

# Encontrar processo usando a porta
lsof -i :3000

# Saída exemplo:
# COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# node    12345 user   23u  IPv6 123456      0t0  TCP *:3000 (LISTEN)

# Matar processo
kill -9 12345

# Ou matar todos os processos Node.js
killall node

Alternativa:

Alterar a porta no arquivo .env:

PORT=3001

Porta do PostgreSQL já em uso

Sintoma:

Error: Port 5432 is already allocated

Solução:

# Verificar se já existe PostgreSQL rodando
sudo systemctl status postgresql

# Se sim, parar o serviço
sudo systemctl stop postgresql

# Ou alterar a porta no docker-compose.yml
ports:
  - "5433:5432"  # Mapear porta diferente

Problemas com Docker

Containers não iniciam

Sintoma:

ERROR: for app  Container "xxxxx" is unhealthy

Solução:

# Ver logs detalhados
docker-compose logs app

# Reconstruir containers
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# Verificar status
docker-compose ps

Erro de permissão no Docker

Sintoma:

permission denied while trying to connect to the Docker daemon socket

Solução:

# Adicionar seu usuário ao grupo docker
sudo usermod -aG docker $USER

# Fazer logout e login novamente
# Ou recarregar grupos
newgrp docker

# Testar
docker ps

Volumes do Docker com dados antigos

Sintoma: Banco de dados com dados inconsistentes ou migrations antigas.

Solução:

# Parar containers
docker-compose down

# Remover volumes (CUIDADO: apaga todos os dados)
docker-compose down -v

# Recriar tudo do zero
docker-compose up -d

# Executar migrations
docker-compose exec app npx sequelize-cli db:migrate
docker-compose exec app npx sequelize-cli db:seed:all

Imagem Docker não atualiza

Sintoma: Alterações no código não aparecem após rebuild.

Solução:

# Rebuild forçado sem cache
docker-compose build --no-cache

# Ou remover imagem e recriar
docker-compose down
docker rmi divino-alimento-app
docker-compose up -d --build

Problemas com PostgreSQL

Erro de conexão com PostgreSQL

Sintoma:

SequelizeConnectionError: connect ECONNREFUSED 127.0.0.1:5432

Solução:

# Verificar se PostgreSQL está rodando (local)
sudo systemctl status postgresql

# Iniciar PostgreSQL (local)
sudo systemctl start postgresql

# Com Docker
docker-compose ps
docker-compose logs postgres

# Verificar configuração no .env
DB_HOST=localhost  # ou 'postgres' se usando Docker
DB_PORT=5432
DB_NAME=divino_alimento_dev

Banco de dados não existe

Sintoma:

SequelizeConnectionError: database "divino_alimento_dev" does not exist

Solução:

# Criar banco manualmente
createdb divino_alimento_dev

# Ou via psql
psql -U postgres
CREATE DATABASE divino_alimento_dev;
\q

# Com Docker
docker-compose exec postgres psql -U postgres -c "CREATE DATABASE divino_alimento_dev;"

Senha do PostgreSQL incorreta

Sintoma:

SequelizeConnectionError: password authentication failed for user "postgres"

Solução:

Verifique o arquivo .env:

DB_USER=postgres
DB_PASSWORD=postgres  # Deve corresponder ao configurado no PostgreSQL

Para redefinir senha do PostgreSQL (local):

sudo -u postgres psql
ALTER USER postgres PASSWORD 'nova_senha';
\q

Erro de encoding

Sintoma:

Error: encoding "UTF8" does not match locale

Solução:

# Criar banco com encoding específico
createdb -E UTF8 -T template0 divino_alimento_dev

# Ou via psql
CREATE DATABASE divino_alimento_dev 
  WITH ENCODING 'UTF8' 
  LC_COLLATE='pt_BR.UTF-8' 
  LC_CTYPE='pt_BR.UTF-8' 
  TEMPLATE=template0;

Problemas com Migrações

Migrations não executam

Sintoma:

ERROR: relation "SequelizeMeta" does not exist

Solução:

# Verificar configuração do Sequelize
cat .sequelizerc

# Tentar executar migrations novamente
npx sequelize-cli db:migrate

# Se persistir, criar tabela manualmente
psql -U postgres -d divino_alimento_dev
CREATE TABLE IF NOT EXISTS "SequelizeMeta" (
  "name" VARCHAR(255) NOT NULL PRIMARY KEY
);
\q

# Executar migrations
npx sequelize-cli db:migrate

Migration já executada

Sintoma:

ERROR: Migration already executed

Solução:

# Ver migrations executadas
npx sequelize-cli db:migrate:status

# Reverter última migration
npx sequelize-cli db:migrate:undo

# Ou reverter todas
npx sequelize-cli db:migrate:undo:all

# Executar novamente
npx sequelize-cli db:migrate

Erro em migration específica

Sintoma:

ERROR: column "campo_x" does not exist

Solução:

# Reverter até antes da migration problemática
npx sequelize-cli db:migrate:undo

# Corrigir o arquivo de migration em migrations/

# Executar novamente
npx sequelize-cli db:migrate

Ordem das migrations incorreta

Sintoma: Foreign keys ou dependências não resolvidas.

Solução:

1. Verificar timestamps nos nomes dos arquivos de migration
2. Renomear se necessário (formato: YYYYMMDDHHMMSS-nome.js)
3. Reverter todas as migrations
4. Executar novamente na ordem correta

npx sequelize-cli db:migrate:undo:all
npx sequelize-cli db:migrate

Problemas com Dependências

Erro ao instalar dependências

Sintoma:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

Solução:

# Limpar cache do npm
npm cache clean --force

# Remover node_modules e package-lock.json
rm -rf node_modules package-lock.json

# Reinstalar
npm install

# Se persistir, usar --legacy-peer-deps
npm install --legacy-peer-deps

Versão do Node.js incompatível

Sintoma:

error: The engine "node" is incompatible with this module

Solução:

# Verificar versão atual
node --version

# Instalar versão correta (18.x ou superior)
# Com nvm
nvm install 18
nvm use 18

# Verificar
node --version
npm --version

# Reinstalar dependências
npm install

Módulo não encontrado

Sintoma:

Error: Cannot find module 'express'

Solução:

# Verificar se node_modules existe
ls node_modules/

# Reinstalar dependências
npm install

# Instalar módulo específico
npm install express

# Verificar package.json
cat package.json

Problemas com GraphQL

Schema inválido

Sintoma:

Error: Syntax Error: Expected Name, found "}"

Solução:

1. Verificar sintaxe dos arquivos .graphql
2. Verificar se todos os tipos estão definidos
3. Verificar se não há vírgulas no final (GraphQL não usa vírgulas)

# ❌ Errado
type Mercado {
  id: ID!,
  nome: String!,
}

# ✅ Correto
type Mercado {
  id: ID!
  nome: String!
}

Resolver não encontrado

Sintoma:

Error: Resolver not found for field "mercado"

Solução:

1. Verificar se o resolver está exportado
2. Verificar se está importado no index.js dos resolvers
3. Verificar nome do campo (deve corresponder exatamente ao schema)

// resolvers/index.js
const mercadoResolvers = require('./mercado');

module.exports = {
  Query: {
    ...mercadoResolvers.Query
  },
  Mutation: {
    ...mercadoResolvers.Mutation
  }
};

Erro de tipo GraphQL

Sintoma:

Expected type "ID!", found "undefined"

Solução:

Verificar se o resolver está retornando dados no formato correto:

// ❌ Errado - retorna null
mercado: async (_, { id }) => {
  return await Mercado.findByPk(id);  // Pode retornar null
}

// ✅ Correto - lança erro se não encontrar
mercado: async (_, { id }) => {
  const mercado = await Mercado.findByPk(id);
  if (!mercado) {
    throw new Error('Mercado não encontrado');
  }
  return mercado;
}

Problemas com Frontend

Erro de CORS

Sintoma:

Access to fetch at 'http://localhost:3000/graphql' from origin 'http://localhost:3001' 
has been blocked by CORS policy

Solução:

Configurar CORS no backend:

// server.js
const cors = require('cors');

app.use(cors({
  origin: process.env.FRONTEND_URL || 'http://localhost:3001',
  credentials: true
}));

Sessão não persiste

Sintoma: Login funciona mas usuário é deslogado ao recarregar página.

Solução:

1. Verificar se credentials: 'include' está configurado no Apollo Client:

// lib/apollo-client.ts
const httpLink = createHttpLink({
  uri: 'http://localhost:3000/graphql',
  credentials: 'include',  // Importante!
});

2. Verificar configuração de cookies no Express:

// server.js
app.use(session({
  cookie: {
    secure: false,  // true apenas em produção (HTTPS)
    httpOnly: true,
    maxAge: 24 * 60 * 60 * 1000
  }
}));

Componentes não atualizam

Sintoma: Dados mudam no backend mas não refletem no frontend.

Solução:

1. Verificar cache do Apollo Client
2. Usar refetchQueries nas mutations:

const [criar] = useMutation(CRIAR_MERCADO, {
  refetchQueries: ['GetMercados'],
  awaitRefetchQueries: true
});

3. Ou invalidar cache manualmente:

const [criar] = useMutation(CRIAR_MERCADO, {
  update(cache, { data: { criarMercado } }) {
    cache.evict({ fieldName: 'mercados' });
  }
});

Problemas com Autenticação

OAuth não redireciona

Sintoma: Após autorizar no Google, não redireciona de volta.

Solução:

1. Verificar URL de callback no Google Cloud Console
2. Deve corresponder exatamente ao .env:

GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

3. Verificar rota no backend:

router.get('/auth/google/callback',
  passport.authenticate('google', {
    failureRedirect: '/login?error=auth_failed'
  }),
  (req, res) => {
    res.redirect('/dashboard');
  }
);

Credenciais OAuth inválidas

Sintoma:

Error: invalid_client

Solução:

1. Verificar se GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET estão corretos
2. Verificar se as credenciais não expiraram
3. Recriar credenciais no Google Cloud Console se necessário
4. Atualizar .env com novas credenciais

Problemas com Testes

Testes não executam

Sintoma:

No tests found

Solução:

# Verificar se arquivos de teste existem
ls test/
ls **/*.test.js

# Verificar configuração do Jest
cat package.json  # Procurar por "jest"

# Executar com verbose
npm test -- --verbose

Banco de dados de teste

Sintoma: Testes modificam banco de desenvolvimento.

Solução:

Criar banco de teste separado:

# .env.test
NODE_ENV=test
DB_NAME=divino_alimento_test

Configurar testes para usar .env.test:

// test/setup.js
require('dotenv').config({ path: '.env.test' });

Recursos Adicionais

Logs e Debug

# Ver logs do Docker
docker-compose logs -f app

# Ver apenas erros
docker-compose logs app | grep -i error

# Debug do Node.js
NODE_ENV=development DEBUG=* npm run dev

Verificar Configuração

# Verificar variáveis de ambiente
env | grep DB_
env | grep GOOGLE_

# Verificar portas em uso
netstat -tuln | grep LISTEN

# Verificar processos Node
ps aux | grep node

Ferramentas Úteis

• Postman/Insomnia: Testar queries GraphQL
• pgAdmin: Gerenciar banco PostgreSQL
• Docker Desktop: Monitorar containers
• Chrome DevTools: Debug do frontend

Precisa de Mais Ajuda?

Se o problema persistir:

1. Consulte a documentação completa
2. Verifique issues abertas no GitHub
3. Entre em contato com a equipe Tekoporã: info@tekopora.top

Próximos Passos

• Configuração do Ambiente - Voltar ao guia de configuração
• Autenticação e Autorização - Resolver problemas de autenticação
• Como Contribuir - Continuar contribuindo com o projeto