Pipeline de Alertas Waypoint (GPS)

Flujo: IMAP (waypoint.cl) -> RAW parquet -> Parser HTML -> Excel multi-hoja + Data Warehouse (fact_alertas_waypoint + dim_vehiculo) -> Supabase -> Power BI

:::note Pipeline-REFERENCIA del patrón Hexagonal F2.1 Primer pipeline migrado a IMAPConnector directo (no usa el shim legacy run_imap_ingest). Sesión 2026-05-27.

Constructor con connector=None opcional (DI ligero para tests).
ingest() delega al helper ingest_with_connector(self.imap_source, self.config, self.log).
Ya no importa core.ingest_imap.

Para crear pipelines nuevos: copiar este patrón. Ver openspec/specs/imap-connector/spec.md (8 Requirements) y Plan-Migracion-F2.2-F2.6 para los 5 pipelines IMAP que aún usan el shim. ADR base: ADR-Source-Connectors (accepted). :::

1. Origen

Correos automaticos de alerta.sistemas@waypoint.cl a la cuenta de Nestor Cumin (nestor.cumin@ingelsur.cl). Plataforma Waypoint Net (servicio GPS via Tranciti para Grupo SAESA).

Tipos de alerta

Tipo	Subject pattern	Volumen (feb-may 2026)
Encendido No Autorizado	`Encendido no autorizado {PPU}`	811
Exceso de Velocidad	`Exceso de Velocidad en Zona (Flota) {zona}, {PPU}, {vel} Km/Hr`	915

2. Estructura del correo

Body HTML con pares Etiqueta: / Valor separados por lineas. Sin adjuntos.

Campos comunes (ambos tipos)

Campo	Ejemplo
Fecha Referencia del Evento	`16:52:02 25-02-2026 (GMT-03:00) America/Santiago`
Patente	`JWRP23`
Marca / Modelo / Ano	`Mitsubishi / KATANA CRT 4X4 / 2018`
Grupo	`BBPP Chiloe`
Flota	`CAMIONETA GG`
Conductor	`PAISIL RODRIGUEZ RAUL`
Zona de Referencia	`Castro`
Direccion	`Manuel Rodriguez, Castro, Provincia de Chiloe...`
Altitud / Horometro / Odometro	`82.0 mts / 206 Hrs / 286629 Kms`

Campos exclusivos de Exceso de Velocidad

Campo	Ejemplo
Zona	`Ciudad de Castro`
Velocidad	`60km/h (Configurada: 50 km/h)`

3. Procesamiento

process_alertas_waypoint_from_raw.py:

Carga RAW parquet (correos descargados)
Clasifica tipo de alerta por subject
Parsea HTML: extrae texto con BeautifulSoup, luego pares etiqueta/valor por linea
Campos derivados: exceso_kmh = velocidad real - configurada
Parsea fechas Waypoint (HH:MM:SS dd-mm-yyyy) a datetime

4. Salida

4.1 Excel (control de flota)

Excel en SALIDAS/alertas_waypoint_{timestamp}.xlsx con 3 hojas:

Hoja	Contenido	Columnas extra
Encendido No Autorizado	Solo alertas de encendido	—
Exceso Velocidad	Solo excesos	zona_velocidad, velocidad_real/config/exceso
Todas las Alertas	Ambos tipos combinados	Todos los campos

4.2 Data Warehouse (Power BI) — desde 2026-06-01

:::note Integración al DW — ADR ADR-Integracion-Alertas-Waypoint-DW (SDD alertas-waypoint-al-dw, archive #1326) El pipeline ahora también alimenta el star schema analítico para Power BI, vía una constelación propia (grano evento-vehículo, sin OT — reusa dim_calendario). :::

scripts/db/data_warehouse.py --alertas-waypoint construye en SALIDAS/db/data_warehouse.db:

Tabla	Tipo	Contenido
`fact_alertas_waypoint`	hecho	1 fila por alerta (dedup `message_id` + fallback hash sha1); medidas velocidad/exceso; `latitud`/`longitud` para mapa (extraídas del link Google Maps del HTML, `q=LAT,LONG`); `conductor`; FK fecha→`dim_calendario`
`dim_vehiculo`	dimensión	1 fila por patente (PK `upper().strip()`, SCD1 replace): marca, modelo, anio, grupo, flota

Validado con datos reales (1726 alertas): geo 100%, FK fecha 100%, 74 vehículos. Registrado en MAPPINGS_DATA_WAREHOUSE (scripts/db/migrate_config.py) → arrastrado al sync Supabase → Power BI Service.

Arquitectura clave: el parseo vive una sola vez en build_df_alertas_waypoint (función pura); el DW la importa (data_warehouse.py → domains/, unidireccional). _extract_latlong, _build_fact_alertas_waypoint y _build_dim_vehiculo son funciones puras aparte (SRP/testabilidad).

5. Ejecucion

# Run con defaults (desde 01-02-2026)
python main_alertas_waypoint.py

# Historico completo
python main_alertas_waypoint.py --all

# Reprocesar sin descargar
python main_alertas_waypoint.py --offline

# Via orquestador (incluido en --all, Wave 2)
python run_pipeline.py alertas_waypoint
python run_pipeline.py --all

6. Archivos

Archivo	Ubicacion
Spec YAML	`config/pipelines/alertas_waypoint.yaml`
CLI standalone	`main_alertas_waypoint.py`
Pipeline class	`domains/alertas_waypoint/pipeline.py`
Parser/Excel/build_df	`domains/alertas_waypoint/process_alertas_waypoint_from_raw.py`
Builder DW (fact+dim)	`scripts/db/data_warehouse.py` (`export_alertas_waypoint`)
Registro sink Supabase	`scripts/db/migrate_config.py` (`MAPPINGS_DATA_WAREHOUSE`)
RAW data	`data_raw/emails_alertas_waypoint_raw/`
Output Excel	`SALIDAS/alertas_waypoint_*.xlsx`
Output DW	`SALIDAS/db/data_warehouse.db` (`fact_alertas_waypoint`, `dim_vehiculo`)
Tests	`tests/test_alertas_waypoint_build_df.py`, `tests/test_export_alertas_waypoint.py`

7. Cuenta IMAP

Usuario: Nestor (en config.py)
Email: nestor.cumin@ingelsur.cl
Host: imap.gmail.com
Remitente: alerta.sistemas@waypoint.cl