Saltar a contenido

Alertas operativas

El BackOffice envía alertas operativas a Telegram para eventos sensibles: intentos fallidos de login, bloqueo de cuentas, altas de usuarios, cambios en usuarios y movimientos de dinero por encima de un umbral. Este documento describe el comportamiento vigente; el detalle de fases y decisiones históricas está en telegram-alerts-roadmap.md.

Eventos

Evento Cuándo se envía Canal
Usuario creado Alta de jugador, agente o usuario de BackOffice users
Usuario actualizado Cambio de estado, contraseña o roles general (bloqueo → users)
Bloqueo de cuenta La cuenta pasa de activa a bloqueada users
Transacción Depósito, retiro o ajuste manual ≥ umbral de su moneda general
Login fallido Tercer intento fallido en la ventana configurada general

Los canales son grupos de Telegram:

  • general → TELEGRAM_ALERT_CHAT_ID.
  • users → TELEGRAM_ALERT_USERS_CHAT_ID; si está vacío cae al canal general.

Si faltan token o chat ID, la alerta se omite y se registra un warning en el log.

Flujo

Acción de negocio
  -> DB::afterCommit()
  -> Evento / Observer
  -> Listener
  -> SendTelegramAlertJob
  -> queue (SQS en producción)
  -> TelegramAlertService
  -> Telegram Bot API
  • Los eventos se despachan solo cuando la transacción de base de datos se confirma.
  • El mensaje se arma antes de encolar, para que el worker no dependa del request ni de Cloudflare.
  • Un fallo de Telegram nunca hace fallar la operación de negocio.

Permisos

Las alertas de alta/actualización de usuarios, transacciones y bloqueo manual requieren que el usuario que ejecuta la acción tenga alerts.send. Está asignado a los roles platform-admin, super-admin y master.

Se envían siempre, sin evaluar permiso:

  • Los logins fallidos, porque no hay un usuario autenticado que evaluar.
  • El bloqueo automático por intentos fallidos, para que el bloqueo siempre se notifique.

Configuración

Variables de entorno

Variable Default Uso
ALERTS_ENABLED true Interruptor maestro de alertas
ALERTS_QUEUE_CONNECTION QUEUE_CONNECTION (sync en local) Conexión de cola del job
ALERTS_QUEUE_NAME vortex-play-alerts Cola SQS de alertas
TELEGRAM_ALERT_BOT_TOKEN — Token del bot
TELEGRAM_ALERT_CHAT_ID — Chat del canal general
TELEGRAM_ALERT_USERS_CHAT_ID — Chat del canal de usuarios

El token y los chat IDs son secretos: se inyectan desde Secrets Manager y no se guardan en configurations.

Reglas en base de datos

Las reglas viven en configurations.data.alerts (componente SERVICES). Se pueden definir a nivel global y por plataforma; la configuración de la plataforma pisa a la global.

{
  "alerts": {
    "enabled": true,
    "failed_logins": {
      "enabled": true,
      "threshold": 3,
      "window_minutes": 1
    },
    "user_created": {
      "enabled": true
    },
    "user_updated": {
      "enabled": true
    },
    "transactions": {
      "credit": { "ARS": 1000, "BRL": 1000, "UYU": 1000 },
      "debit": { "ARS": 1000, "BRL": 1000, "UYU": 1000 }
    }
  }
}
  • Una moneda sin umbral no genera alerta.
  • Una configuración ausente o inválida deshabilita las alertas y deja un error en el log.
  • Para desactivar todo: ALERTS_ENABLED=false o alerts.enabled=false. Se necesitan ambos interruptores activos.
  • Para desactivar un evento: su enabled en configurations.
  • Para cambiar umbrales: editar transactions.credit / transactions.debit por moneda.

Logins fallidos y bloqueo

  • Rate limit de login: 3 intentos por minuto por IP y panel.
  • Alerta de login fallido: 3 intentos por panel e IP dentro de failed_logins.window_minutes (1 minuto por defecto). El contador vive en caché.
  • Bloqueo automático: 5 intentos acumulados por usuario y panel en 15 minutos. Al llegar al quinto, la cuenta pasa a status=false y se envía la alerta de bloqueo al canal de usuarios.
  • Un login exitoso reinicia el contador de bloqueo.
  • El bloqueo automático está desactivado en local (APP_ENV=local).
  • El mensaje incluye usuario, IP, panel, plataforma e intentos; nunca incluye la contraseña.

La IP se resuelve en este orden: CF-Connecting-IP → X-Forwarded-For → X-Real-IP → IP del request.

Cambios de usuario

El observer de User alerta cuando cambia:

  • status (activo ↔ bloqueado).
  • password (contraseña actualizada).

Además, la edición de usuarios del BackOffice alerta cuando cambian los roles (agregados o removidos). Los cambios de nombre, email u otros campos no generan alerta salvo que se agreguen al observer o a la acción correspondiente.

Cola y deploy

  • Producción: conexión sqs-alerts, cola vortex-play-alerts, job con 3 intentos.
  • Supervisor ejecuta php artisan queue:work sqs-alerts en el mismo contenedor que Octane.
  • Local y tests: conexión sync; un fallo de Telegram se registra pero no se relanza.
  • Al desplegar un cambio de alertas, se recomienda probar con ALERTS_ENABLED=false o en un canal de pruebas y luego activar en producción.

Verificación

# Logs de alertas
rg "Telegram alert" storage/logs/laravel.log

# Worker local
php artisan queue:work sqs-alerts

# Tests
php artisan test --filter=Alert

Comportamiento esperado ante fallos:

  • Falta de token/chat: warning y no se envía.
  • Error de red o respuesta no ok: error; en cola se reintenta hasta 3 veces.
  • El token se redacta en los mensajes de error.

Troubleshooting

Síntoma Revisar
No llega ninguna alerta ALERTS_ENABLED, alerts.enabled, token y chat IDs
Llegan al canal equivocado TELEGRAM_ALERT_USERS_CHAT_ID y el tipo de evento
No llegan transacciones Umbral de la moneda y permiso alerts.send
No llega el bloqueo configurations.data.alerts.failed_logins y el worker sqs-alerts
El job falla y reintenta Logs de Telegram, estado de SQS y credenciales AWS
El contador no avanza Store de caché (Redis) y window_minutes

Referencias