Capítulo 2: Solución de Problemas y Resolución de Incidencias

Objetivos

• Identificar y resolver problemas comunes
• Utilizar las guías de troubleshooting del proyecto
• Dominar las técnicas de depuración en Spring Boot

---

Recurso Principal

Documentación Oficial

Todas las guías de troubleshooting están disponibles en el repositorio:

** Carpeta Troubleshooting**

---

Lista de Guías Disponibles

La carpeta troubleshooting contiene numerosas guías numeradas para ayudarle:

Guía	Tema	Descripción
01-xx	Configuración inicial	Configuración del proyecto
10-xx	Base de datos	PostgreSQL, H2, conexiones
15-xx	Spring Security	Configuración de seguridad
20-xx	JWT	Tokens, autenticación
25-xx	API REST	Endpoints, CORS
27	Frontend Codespaces	Integración frontend
28-xx	Pruebas	Pruebas unitarias e integración

---

Problemas Frecuentes y Soluciones

1. Error al Iniciar la Aplicación

Síntoma

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

Posibles Causas y Soluciones

Base de datos no configurada:

# application.yml - Configuración H2 para desarrollo
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true

Puerto ya en uso:

# Verificar el puerto
lsof -i :8080

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

---

2. Error 401 Unauthorized

Síntoma

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

Solución

El endpoint requiere un token JWT. Siga estos pasos:

# 1. Registrarse (si el endpoint está disponible)
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

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

# 3. Usar el token recibido
curl http://localhost:8080/api/admin/leads \
  -H "Authorization: Bearer SU_TOKEN_JWT"

---

3. Error CORS

Síntoma (en la consola del navegador)

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

Solución

Verifique la configuración CORS en 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. Error de Validación

Síntoma

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

Solución

Verifique los datos enviados. Todos los campos obligatorios deben estar presentes:

{
  "fullName": "Nombre Completo",      // Obligatorio
  "email": "email@valido.com",        // Obligatorio, formato email
  "company": "Opcional",              // Opcional
  "phone": "Opcional",                // Opcional
  "requestType": "INFO",              // Obligatorio: INFO, QUOTE, SUPPORT, PARTNERSHIP, OTHER
  "message": "Al menos 10 caracteres como mínimo para este mensaje"  // Obligatorio
}

---

5. Problema con la Base de Datos PostgreSQL

Síntoma

Connection to localhost:5432 refused

Soluciones

Opción A - Usar H2 en desarrollo:

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

Opción B - Iniciar PostgreSQL con 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

Síntoma

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

Solución

Vuelva a iniciar sesión para obtener un nuevo token:

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

---

7. Error 500 Internal Server Error

Diagnóstico

1. Consultar los logs:

# En la terminal donde la aplicación está corriendo
# Los stack traces aparecen automáticamente

2. Activar los logs de depuración:

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

3. Verificar la consola H2:
   • URL: http://localhost:8080/h2-console
   • JDBC URL: jdbc:h2:mem:testdb

---

🛠️ Herramientas de Depuración

Postman / Insomnia

Importe la colección Postman desde el repositorio para probar todos los endpoints fácilmente.

Consola H2

Accesible en http://localhost:8080/h2-console para inspeccionar la base de datos.

Logs de Spring Boot

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

Actuator (si está activado)

# Verificar el estado de la aplicación
curl http://localhost:8080/actuator/health

# Ver los beans cargados
curl http://localhost:8080/actuator/beans

---

Guía Específica: Frontend con Codespaces

Guía Esencial

Para la integración del frontend en el entorno Codespaces, consulte la guía detallada:

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

---

Checklist de Depuración

Antes de solicitar ayuda, verifique:

• Los logs de error en la terminal
• La configuración en application.yml
• La disponibilidad de la base de datos
• El formato de los datos enviados (JSON válido)
• La presencia del token JWT para los endpoints protegidos
• La configuración CORS para las llamadas frontend

---

Próximo Paso

Capítulo 3: Integración Frontend →

---

Volver al índice del módulo