# Hapag Lloyd Web Scraper - Guía de Uso

## ✅ Implementación Completada

Se ha agregado soporte completo para **Hapag Lloyd** al sistema de scraping de ETAs.

### 🔧 Características

- **Scraper moderno**: Utiliza Playwright para navegar páginas JavaScript
- **Extracción automática**: Busca fechas en formato `YYYY-MM-DD` 
- **Integración BD**: Guarda automáticamente en `container_tracking_history`
- **Sincronización**: Actualiza la ETA en `container_shipment` cuando encuentra datos
- **Manejo de errores**: Diferencia entre "No Encontrado" y "Error"

---

## 🚀 Cómo Usar

### 1. Crear un Container en el Dashboard

En la interfaz de CarnTrack:

1. Ir a **Containers** → **Agregar Nuevo Container**
2. Llenar los campos:
   - **Container Number**: `HLBU6221765`
   - **Carrier**: `Hapag-Lloyd`
   - **Vessel Tracking URL**: 
     ```
     https://www.hapag-lloyd.com/en/online-business/track/track-by-container-solution.html?container=HLBU++6221765
     ```
   - Otros campos según corresponda

3. Guardar el container

### 2. Probar el Scraper Manualmente

```bash
# Ejecutar el script de prueba
npx tsx scripts/test-hapag-lloyd-scraper.ts
```

**Salida esperada:**
```
✅ Container found!
📥 Step 2: Scraping Hapag Lloyd website...
(This may take 10-15 seconds as Playwright needs to render the page)

✅ Scraping completed in 12500ms
   Status: success
   Raw ETA: 2026-06-18
   Formatted ETA: 2026-06-18

💾 Step 3: Updating database...
✅ Database updated!

🔍 Step 4: Verifying update...
✅ Container updated successfully!
   Container Number: HLBU6221765
   New ETA: 2026-06-18
```

### 3. Scraping Automático (Si tienes Cron activado)

Si tienes configurado el cron en Vercel o similar, el scraper de Hapag Lloyd se ejecutará automáticamente cada 2 horas junto con las otras navieras.

---

## 📊 Integración con el Dashboard

Una vez que el scraper actualiza la ETA:

1. La fecha aparecerá en la columna **ETA** del container
2. El histórico se guarda en `container_tracking_history`
3. Puedes ver el progreso en la vista de **Containers**

---

## 🔍 Formato de URL de Tracking

Hapag Lloyd usa esta estructura de URL:

```
https://www.hapag-lloyd.com/en/online-business/track/track-by-container-solution.html?container=XXXXX
```

Ejemplos:
- `HLBU6221765` → `?container=HLBU++6221765` (espacios como `+`)
- `HLBU 6221765` → `?container=HLBU++6221765`
- `HLBU  6221765` → `?container=HLBU++6221765` (múltiples espacios)

El scraper maneja estos formatos automáticamente.

---

## 📝 Datos Extraídos

El scraper busca en la tabla de tracking y extrae:

```html
<!-- Estructura HTML de Hapag Lloyd -->
<td><span class="nonEditableContent">Vessel arrival</span></td>
<td><span class="nonEditableContent">CALLAO</span></td>
<td><span class="nonEditableContent">2026-06-18</span></td>  <!-- ← ETA aquí
<td><span class="nonEditableContent">07:00</span></td>
<td><span class="nonEditableContent">SEASPAN THAMES</span></td>
```

- Busca todas las fechas en formato `YYYY-MM-DD`
- Usa la más reciente (últimas ETAs son generalmente las relevantes)
- Formato final: ISO `YYYY-MM-DD` (compatible con BD)

---

## 🐛 Solución de Problemas

### "No Encontrado"
- El container no existe en Hapag Lloyd
- La estructura HTML cambió (revisar el sitio manualmente)
- Verifica que la URL sea correcta

### "Error"
- Playwright no está disponible o falló a abrir navegador
- Timeout esperando que la página cargue
- Problema de red

**Solución:**
```bash
# Reinstalar Playwright
npm install --save-dev @playwright/test

# Revisar logs del scraper
npm run db:migrate  # Asegurar que la BD está actualizada
```

### Container no encontrado en BD
```bash
# Ver todos los containers Hapag Lloyd
npx tsx -e "
const db = require('./db/db-script').default;
db.query(\`SELECT id, container_number, eta FROM container_shipment WHERE carrier ILIKE '%hapag%'\`)
  .then(r => console.log(r.rows))
  .catch(e => console.error(e))
  .finally(() => process.exit());
"
```

---

## 🔄 Flujo Automático (Cron)

Si tienes cron activado (Vercel, Cloudflare):

```
POST /api/admin/eta-scraper
Authorization: Bearer {CRON_SECRET}
```

Esto ejecutará:
1. ✅ Maersk
2. ✅ CMA CGM
3. ✅ MSC
4. ✅ HMM
5. ✅ COSCO
6. ✅ ZIM
7. ✅ Yang Ming
8. ✅ Evergreen
9. ✅ **Hapag Lloyd** (NUEVO)

---

## 📚 Archivos Modificados

```
src/lib/shipping-scraper.ts
  - scrapHapag()      [Función mejorada con Playwright]
  - formatETA()       [Soporte para YYYY-MM-DD de Hapag Lloyd]
  - scrapeShippingETA() [Actualizado para pasar trackingUrl]

scripts/
  - test-hapag-lloyd-scraper.ts  [Script de prueba nuevo]

db/migrations/
  - 015_add_eta_raw_column.sql   [Guarda también eta_raw]
```

---

## 💡 Notas Técnicas

- **Browser**: Playwright Chromium (headless)
- **Timeout**: 45 segundos para cargar página
- **Espera**: 5 segundos adicionales para renderizado JS
- **Selectores**: `span.nonEditableContent` con regex `\d{4}-\d{2}-\d{2}`
- **Formato salida**: ISO 8601 `YYYY-MM-DD`

---

## ✨ Próximos Pasos

1. **Crear el container en el dashboard** con la URL de tracking
2. **Ejecutar el script de prueba** para verificar que funciona
3. **Revisar la ETA** en el dashboard del container
4. **Si usas cron**: el scraper se ejecutará automáticamente cada 2 horas

¡Listo! El scraper de Hapag Lloyd está integrado y funcionando.