Capítulo 2: Troubleshooting e Resolução de Problemas

Objetivos

• Identificar e resolver problemas comuns
• Utilizar os guias de troubleshooting do projeto
• Dominar técnicas de debug com Spring Boot

---

Recurso Principal

Documentação Oficial

Todos os guias de troubleshooting estão disponíveis no repositório:

** Pasta Troubleshooting**

---

Lista de Guias Disponíveis

A pasta troubleshooting contém vários guias numerados para te ajudar:

Guia	Assunto	Descrição
01-xx	Configuração inicial	Setup do projeto
10-xx	Banco de dados	PostgreSQL, H2, conexões
15-xx	Spring Security	Configuração de segurança
20-xx	JWT	Tokens, autenticação
25-xx	API REST	Endpoints, CORS
27	Frontend Codespaces	Integração frontend
28-xx	Testes	Testes unitários e de integração

---

Problemas Frequentes e Soluções

1. Erro ao Iniciar a Aplicação

Sintoma

***************************
APPLICATION FAILED TO START
***************************

Possíveis Causas e Soluções

Banco de dados não configurado:

# application.yml - Configuração H2 para desenvolvimento
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true

Porta já está em uso:

# Verificar a porta
lsof -i :8080

# Usar outra porta
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

---

2. Erro 401 Unauthorized

Sintoma

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required"
}

Solução

O endpoint requer um token JWT. Siga estes passos:

# 1. Registrar-se (se o endpoint estiver disponível)
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 2. Fazer login para obter o token
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 3. Usar o token recebido
curl http://localhost:8080/api/admin/leads \
  -H "Authorization: Bearer SEU_TOKEN_JWT"

---

3. Erro CORS

Sintoma (no console do navegador)

Access to fetch at 'http://localhost:8080/api/contact' from origin 
'http://localhost:3000' has been blocked by CORS policy

Solução

Verifique a configuração CORS em SecurityConfig.java:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList("*"));
    configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
    configuration.setAllowedHeaders(Arrays.asList("*"));
    
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

---

4. Erro de Validação

Sintoma

{
  "status": 400,
  "errors": {
    "email": "must be a valid email",
    "fullName": "must not be blank"
  }
}

Solução

Verifique os dados enviados. Todos os campos obrigatórios devem estar presentes:

{
  "fullName": "Nome Completo",      // Obrigatório
  "email": "email@valido.com",      // Obrigatório, formato de e-mail
  "company": "Opcional",            // Opcional
  "phone": "Opcional",              // Opcional
  "requestType": "INFO",            // Obrigatório: INFO, QUOTE, SUPPORT, PARTNERSHIP, OTHER
  "message": "Pelo menos 10 caracteres mínimos para esta mensagem"  // Obrigatório
}

---

5. Problema com Banco de Dados PostgreSQL

Sintoma

Connection to localhost:5432 refused

Soluções

Opção A - Usar H2 em desenvolvimento:

# application.yml
spring:
  profiles:
    active: dev
    
---
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb

Opção B - Rodar PostgreSQL com Docker:

docker run -d \
  --name postgres-econtact \
  -e POSTGRES_DB=econtactdb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:14-alpine

---

6. Token JWT Expirado

Sintoma

{
  "status": 401,
  "error": "Token expired"
}

Solução

Faça login novamente para obter um novo token:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "seu@email.com", "password": "suasenha"}'

---

7. Erro 500 Internal Server Error

Diagnóstico

1. Verifique os logs:

# No terminal onde a aplicação está rodando
# As stack traces aparecem automaticamente

2. Ative os logs de debug:

# application.yml
logging:
  level:
    com.example.econtact: DEBUG
    org.springframework.security: DEBUG

3. Verifique o console H2:
   • URL: http://localhost:8080/h2-console
   • JDBC URL: jdbc:h2:mem:testdb

---

🛠️ Ferramentas de Debug

Postman / Insomnia

Importe a coleção Postman do repositório para testar todos os endpoints facilmente.

Console H2

Acessível em http://localhost:8080/h2-console para inspecionar o banco de dados.

Logs Spring Boot

# Ativar logs detalhados
logging:
  level:
    root: INFO
    com.example.econtact: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG

Actuator (se ativado)

# Verificar a saúde da aplicação
curl http://localhost:8080/actuator/health

# Ver os beans carregados
curl http://localhost:8080/actuator/beans

---

Guia Específico: Frontend com Codespaces

Guia Essencial

Para integração do frontend no ambiente Codespaces, consulte o guia detalhado:

** 27-guide-formulaire-frontend-codespaces.md**

---

Checklist de Debug

Antes de pedir ajuda, verifique:

• Os logs de erro no terminal
• A configuração em application.yml
• A disponibilidade do banco de dados
• O formato dos dados enviados (JSON válido)
• A presença do token JWT para endpoints protegidos
• A configuração CORS para chamadas frontend

---

Próximo Passo

Capítulo 3: Integração Frontend →

---

Voltar ao índice do módulo