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
erroren el log. - Para desactivar todo:
ALERTS_ENABLED=falseoalerts.enabled=false. Se necesitan ambos interruptores activos. - Para desactivar un evento: su
enabledenconfigurations. - Para cambiar umbrales: editar
transactions.credit/transactions.debitpor 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=falsey 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, colavortex-play-alerts, job con 3 intentos. - Supervisor ejecuta
php artisan queue:work sqs-alertsen 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=falseo 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:
warningy 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 |