# IpGuide Service - Documentación Técnica**

Esta librería es un wrapper profesional para la API de **ip.guide**, integrada en Laravel bajo el patrón de **Servicios y Facades**. Proporciona geolocalización robusta con manejo de errores resiliente.

## **🏗️ Arquitectura del Sistema**

El servicio se compone de tres pilares fundamentales:

1. **IpGuideService (Core):** Gestiona las peticiones HTTP, reintentos y lógica de fallos.  
2. **IpLocationData (DTO):** Objeto de transferencia de datos que asegura que el código sea tipado y predecible.  
3. **SlackMessageBundler:** Integración de alertas en tiempo real para monitoreo de salud del servicio.

## **🛠️ Guía de Implementación**

### **Uso Básico (Facade)**
```php	
use App\\Facades\\IpGuide;

// Retorna un objeto IpLocationData o null en caso de fallo  
$data \= IpGuide::lookup('2803:bc40:8185:20d7:59fb:7f1a:2261:7207');

if ($data) {  
    echo "Ubicación: {$data-\>city}, {$data-\>country}";  
}
```

## **📊 Matriz de Errores y Notificaciones**

El sistema está diseñado para fallar de forma silenciosa hacia el usuario pero ruidosa hacia el equipo de desarrollo.

| Escenario | Causa Probable | Acción del Sistema | Notificación Slack |
| :---- | :---- | :---- | :---- |
| **HTTP 404** | IP no encontrada o privada | Retorna null | Nivel: Advertencia |
| **HTTP 5xx** | Caída del servicio ip.guide | 2 Retries \-\> null | Nivel: Crítico |
| **Timeout (\>5s)** | Problemas de red / Latencia | null | Nivel: Salud del Servicio |
| **JSON Inválido** | Respuesta corrupta o HTML | null | Nivel: Error de Formato |
| **Exception** | Error de código o DTO | null \+ Log Stacktrace | Nivel: Alerta Técnica |

## **📂 Logs y Trazabilidad**

Todos los eventos se centralizan para facilitar la depuración sin contaminar el log principal de Laravel.

* **Ruta del Log:** storage/logs/services/ip-guide.log (gestionado vía TailLogger)  
* **Estructura del Log:**  
  * INFO: Consultas exitosas con el payload recibido para auditoría.  
  * ERROR: Detalles técnicos del fallo, incluyendo mensaje de excepción, archivo y línea.

### **Ejemplo de Log de Error:**

\[2024-05-20 10:00:00\] ERROR: IpGuide Lookup Failed for IP: 127.0.0.1  
Context: {"reason": "HTTP Error 404", "context": "Not Found"}

## **🚨 Manejo de Errores y Resiliencia**

| Característica | Descripción |
| :---- | :---- |
| **Timeout** | 5 segundos para evitar bloqueos en el hilo de ejecución. |
| **Retries** | 2 reintentos automáticos con 100ms de retraso ante fallos de red. |
| **Defensive Parsing** | Validación de JSON antes del mapeo al DTO para evitar excepciones null pointer. |
| **Global Catch** | Captura de Throwable para asegurar que el sistema reporte cualquier error inesperado. |

## **📝 Ejemplo de Alerta en Slack**

El reporte generado en Slack incluye:

* **Título:** ⚠️ IpGuide Service Alert  
* **Cuerpo:** Descripción del fallo (ej. "HTTP Error 404" o "Connection Timeout").  
* **Meta:** IP consultada, Fecha/Hora exacta y Traza del error.

*Documentación generada para integración en entornos Laravel con estándares PSR.*