Habitaclia Scraper - Troubleshooting y Mejoras

Mejoras Implementadas (Mayo 2025)

1. Manejo Robusto de Errores en got-scraping

Problema: El error ENOENT: no such file or directory, open 'C:\ROOT\node_modules\header-generator\data_files\headers-order.json' ocurría cuando got-scraping intentaba acceder a archivos de configuración de header-generator pero fallaba por problemas de ruta o permisos.

Solución:

• Implementado fallback automático a node-fetch cuando got-scraping falla por errores de header-generator
• Sistema de reintentos con backoff exponencial (hasta 3 intentos con pausas de 2s)
• Detección específica de errores de header-generator y ENOENT para usar estrategia alternativa

// Flujo mejorado en fetchHabitacliaHtml()
1. Intenta got-scraping (con TLS fingerprinting avanzado)
2. Si falla por header-generator → fallback a node-fetch con headers estáticos
3. Si falla por timeout/red → reintenta hasta 3 veces
4. Si todo falla → devuelve null y activa fallback a Playwright

2. Descarga de Imágenes con Reintentos

Problema: Imágenes que no se descargaban por errores temporales de red o servidores sobrecargados.

Solución:

• Reintentos automáticos en downloadAndSaveImage() con backoff exponencial
• Reintenta automáticamente en casos de:
  • Errores HTTP 5xx (servidor caído temporalmente)
  • Error 429 (rate limiting)
  • Error 408 (timeout de petición)
  • Errores de red: ETIMEDOUT, ECONNRESET, ENOTFOUND
• Máximo 3 reintentos con pausas progresivas (1s, 2s, 4s)

Ejemplo de log exitoso:

⚠️ Failed to download image: https://... (HTTP 503)
🔄 Retrying image download (1/3) after 1000ms...
✅ Successfully downloaded image

3. Validación y Logs Mejorados

Cambios:

• Emojis descriptivos en logs para facilitar seguimiento:
  • ✅ Operaciones exitosas
  • ⚠️ Advertencias
  • ❌ Errores críticos
  • 🔄 Reintentos en progreso
  • 🌐 Operaciones con proxy
• Mensajes de log más descriptivos con:
  • Tamaño de respuesta HTTP
  • Número de reintento actual
  • Motivo específico del error

Diagnóstico de Problemas

Error: header-generator no encuentra archivos

Síntomas:

[GOT-SCRAPING] Request failed for https://...: ENOENT: no such file or directory

Causa: got-scraping depende de header-generator, que necesita archivos JSON de configuración. En algunos entornos (especialmente Windows o con rutas no estándar), puede fallar al localizarlos.

Solución Automática: El código ahora detecta este error y usa node-fetch como fallback inmediato.

Solución Manual (si persiste):

1. Verificar instalación:

   npm list header-generator
   

2. Reinstalar dependencias:

   npm install --force
   

3. Verificar permisos de lectura en node_modules/header-generator/data_files/

Imágenes no se descargan

Síntomas:

⚠️ Failed to download image: https://... (HTTP 403/404/503)

Diagnóstico:

1. 403 Forbidden: El servidor rechaza la petición

   • ✅ Solución implementada: Se envían headers Referer correctos automáticamente

2. 404 Not Found: La imagen ya no existe

   • ✅ Solución implementada: Para Fotocasa, se prueban automáticamente URLs de menor resolución

3. 503 Service Unavailable: Servidor temporalmente caído

   • ✅ Solución implementada: Reintentos automáticos con backoff

4. Timeout de red: Conexión lenta o inestable

   • ✅ Solución implementada: Reintentos con timeout de 30s

Datos incompletos (falta rooms, bathrooms, etc.)

Síntomas:

⚠️ [RETRY] Habitaclia discovery incomplete for https://.... Missing: [rooms, bathrooms]

Flujo de recuperación automático:

1. Primera extracción con got-scraping
2. Si falta información → reintenta con forceProxy: true (Google Translate)
3. Si sigue incompleto → combina datos de múltiples fuentes
4. Como último recurso → usa Jina AI Reader

Verificación manual:

• Abrir la URL en el navegador y verificar si la información existe en la página
• Si existe pero no se extrae → revisar selectores CSS en parseHabitacliaHtml()
• Si no existe en la página → es limitación de la fuente (propiedad sin esa info)

Estrategias de Extracción (en orden)

1. Fast HTTP (got-scraping)

• Velocidad: ⚡⚡⚡ Muy rápida
• Tasa de éxito: ~85%
• Ventajas: No usa navegador, bajo consumo de recursos
• Fallback automático: Si falla por header-generator → usa node-fetch

2. Playwright Directo

• Velocidad: ⚡⚡ Moderada
• Tasa de éxito: ~70% (puede ser bloqueado en servidores)
• Ventajas: Renderiza JavaScript completo
• Limitación: Detectado como bot en algunos entornos

3. Google Translate Proxy

• Velocidad: ⚡ Lenta (frames + traducción)
• Tasa de éxito: ~95%
• Ventajas: Bypasea casi todos los bloqueos antibot
• Estrategia: Rota entre 5 pares de idiomas (en→es, fr→es, de→es, it→es, pt→es)

4. Jina AI Reader (último recurso)

• Velocidad: ⚡⚡ Rápida
• Tasa de éxito: 100% (siempre devuelve algo)
• Limitación: No extrae imágenes, datos básicos solamente
• Uso: Solo cuando todos los métodos anteriores fallan

Configuración Recomendada

Entorno Local (desarrollo)

const options = {
    forceProxy: false,  // Permite usar got-scraping primero
    maxPages: 3
};

Entorno Servidor (producción)

const options = {
    forceProxy: true,   // Evita bloqueos, va directo a proxy
    maxPages: 5
};

Monitorización

Logs a observar para detectar problemas:

✅ Todo funcional:

✅ [GOT-SCRAPING] Successfully fetched HTML (45231 bytes)
✅ [GOT-SCRAPING] Successfully extracted details for https://...
✅ Successfully downloaded 8/8 images for property 1234

⚠️ Problemas menores (auto-recuperables):

[GOT-SCRAPING] Header-generator error, falling back to native fetch
🔄 Retrying image download (1/3) after 1000ms...
⚠️ [RETRY] Habitaclia discovery incomplete. Retrying with proxy...

❌ Problemas críticos (requieren atención):

❌ Error downloading image: ... (persiste después de 3 reintentos)
[PROXY EXTRACTION] All 5 language pairs exhausted for https://...
[JINA FALLBACK] Response too short (última línea de defensa falló)

Mantenimiento

Cuando actualizar selectores CSS

Si ves errores como:

--- SCRAPER: WARNING - No images found for https://...

1. Inspeccionar la página en el navegador
2. Actualizar selectores en parseHabitacliaHtml():
   • Imágenes: .wide-media img, #js-gallery img, etc.
   • Habitaciones: feature-container li con regex (\d+)\s*hab
   • Baños: Similar con regex (\d+)\s*bañ

Testear cambios

# Test unitarios
npm run test:habitaclia:unit

# Test de integración (scraping real)
npm run test:habitaclia:smoke

Contacto y Soporte

Para problemas persistentes, revisar:

• Logs del sistema en src/actions/sync-actions.ts
• Estado de CircuitBreakers en src/lib/ai/state.ts
• Diagnósticos con diagnostics tool