Initial commit: SaveUrl project migration from Drive

2026-05-09 14:20:17 -04:00
commit 9f799c9398
16 changed files with 1439 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Runbook de operación
+
+## Objetivo operacional
+
+Mantener la sincronización:
+
+- FTP (archivos del mes/carpeta) → SQL Server (`URL_FTP`)
+
+con observabilidad en Kafka y alerta por webhook.
+
+## Qué esperar en una ejecución “sana”
+
+Por cada item en `INFORMATIONS` se esperan, en logs de Airflow:
+
+- `✅ FTP ... <N> archivos en <code_folder>`
+- `✅ SQL ... <M> registros existentes`
+- `ℹ️  DIFF ... A insertar: <K>`
+- `✅ INSERT ... Insertados: <K>` (o warning de “Sin registros nuevos”)
+
+Al final:
+
+- `⏹ FINALIZADO ...`
+
+## Inputs críticos (pre-flight)
+
+- **Airflow Variables** existen y tienen valores válidos:
+  - FTP: `FTP_000oqta_SERVER`, `FTP_000oqta_USER`, `FTP_000oqta_PASSWORD`
+  - SQL: `DB_MSSQ_SERVER`, `DB_MSSQ_USER`, `DB_MSSQ_PASSWORD`
+  - Kafka: `BOOTSTRAP_SERVERS_DOCKER`, `KAFKA_USE_SSL`
+  - Webhook: `WEBHOOK_URL_NOTIFICATION`
+- El worker donde corre el DAG tiene:
+  - driver ODBC 18 instalado
+  - conectividad a FTP/SQL/Kafka/webhook
+
+## Procedimiento ante incidentes (rápido)
+
+1. Revisar logs del task `save_url_ftp` en Airflow.
+2. Identificar el “BD lógico” afectado (ej. `glm_pmi`, `IS001`, etc.).
+3. Clasificar el fallo:
+   - FTP (login, path, listing)
+   - SQL (conexión, permisos, tabla)
+   - INSERT (schema/constraint)
+   - Kafka (broker/SSL/SASL)
+   - Webhook (endpoint caído / 4xx/5xx)
+4. Ejecutar acciones según tipo (ver `08_TROUBLESHOOTING.md`).
+
+## Operación programada del DAG
+
+El DAG corre cada 2 horas (`0 */2 * * *`).
+
+Si necesitas ejecución manual:
+
+- Ejecuta el task `save_url_ftp` desde la UI de Airflow (Trigger DAG / Run Task).
+
+## Indicadores recomendados (SLOs simples)
+
+- **Frescura**: últimas URLs del FTP aparecen en SQL < 2–4 horas.
+- **Cobertura**: por cada item, `A insertar` tiende a 0 tras una corrida exitosa.
+- **Errores**: tasa de `FAILED` por item debe ser baja; si sube, revisar conectividad o cambios de naming en FTP.
+
+## Mantenimiento preventivo
+
+- Revisar que `FTP_BASE_PATH` (año) sea correcto cuando cambie el año.
+- Verificar que las rutas/certificados SSL (si aplica) sean válidos dentro del contenedor.
+- Confirmar que el naming en FTP siga el patrón esperado (contiene `_{YYYY}-{MM}` e `identity_id`).
+