Saltar a contenido

Roadmap — Alertas por Telegram

Estado: implementado (fases 0 a 10). La operación vigente está en alerts.md; este documento conserva el historial de decisiones y las fases pendientes.

1. Objetivo

Enviar alertas operativas a un grupo de Telegram cuando ocurran eventos relevantes en el BackOffice: creación de usuarios y movimientos de dinero que superen un umbral configurado por moneda.

2. Decisiones de alcance

  • Canal único: Telegram (grupo). Sin notificaciones in-app, email ni Slack.
  • Reglas globales, no por plataforma.
  • Los umbrales de transacciones se configuran por moneda.
  • Prioridad: máxima rapidez de entrega.
  • Envío síncrono después del commit de la operación, con timeout corto.
  • Una falla de Telegram nunca debe hacer fallar la operación de negocio.

3. Fuera de alcance de la v1

  • Alertas por plataforma o por tenant.
  • Administración de reglas desde la interfaz.
  • Transacciones originadas en platform-api, juegos o proveedores (solo operaciones ejecutadas desde este BackOffice).
  • Reintentos automáticos y deduplicación.
  • Enlaces profundos a los recursos (se evalúa en la fase 5).

4. Arquitectura

Acción de negocio
  -> DB::afterCommit()
  -> Evento de dominio
  -> Listener síncrono
  -> TelegramAlertService
  -> Telegram Bot API (sendMessage)
  • Los eventos se despachan solo cuando la transacción de base de datos se confirma.
  • El listener no se encola en v1 para minimizar la latencia.
  • El servicio usa Http directo contra https://api.telegram.org, sin paquetes nuevos.

5. Fases

Fase 0 — Preparación

  • [x] Crear el bot de Telegram con BotFather.
  • [x] Agregar el bot al grupo destino y verificar que pueda enviar mensajes.
  • [x] Obtener el chat_id del grupo (normalmente empieza con -100).
  • [x] Configurar las reglas de alertas en la tabla configurations (componente SERVICES, id 4).
  • [x] Configurar TELEGRAM_ALERT_BOT_TOKEN y TELEGRAM_ALERT_CHAT_ID en .env.
  • [x] Configurar las credenciales de Telegram en .env (config/alerts.php las expone).
  • [x] Confirmar los umbrales por moneda.
  • [x] Confirmar la lista final de eventos de la v1.

Las reglas viven en configurations.data.alerts. El token y los chat IDs de Telegram viven en .env porque son únicos y no cambian.

Canales de Telegram

  • TELEGRAM_ALERT_CHAT_ID: canal general (transacciones, logins fallidos y demás alertas).
  • TELEGRAM_ALERT_USERS_CHAT_ID: canal de usuarios (alta de jugadores, agentes y usuarios de BackOffice; y bloqueo de usuarios).
  • Si TELEGRAM_ALERT_USERS_CHAT_ID está vacío, las alertas de usuarios caen al canal general.

Permiso de envío

  • Las alertas de alta/actualización de usuarios, transacciones y bloqueo manual solo se envían si el usuario que ejecuta la acción tiene el permiso alerts.send.
  • alerts.send está asignado a los roles 1 (platform-admin), 2 (super-admin) y 5 (master).
  • Las alertas de login fallido y de bloqueo automático se envían siempre, porque no hay un usuario autenticado que evaluar.

Fase 1 — Núcleo de envío a Telegram

  • [x] Crear App\Services\TelegramAlertService.
  • [x] Método base sendMessage(string $text): bool con parse_mode=HTML.
  • [x] Timeouts de conexión y respuesta (2–3 segundos).
  • [x] Validar que existan token y chat ID; si faltan, omitir y registrar en log.
  • [x] Capturar excepciones de red/API; registrar con Log::error y continuar.
  • [ ] Valorar reintento simple ante 429 (opcional en v1).

Fase 2 — Evento: usuario creado

  • [x] Crear App\Events\UserCreated.
  • [x] Incluir: usuario creado, usuario creador, tipo (jugador/agente), saldo inicial, moneda y plataforma.
  • [x] Despachar desde:
  • [x] CreatePlayerAction
  • [x] CreateAgentAction
  • [x] CreateUser::afterCreate()
  • [x] BackOffice ListUsers CreateAction
  • [x] Envolver el dispatch con DB::afterCommit().
  • [x] Armar mensaje y enviarlo con SendUserCreatedAlert.

Fase 3 — Evento: transacción realizada

  • [x] Crear App\Events\TransactionPerformed.
  • [x] Incluir: usuario afectado, usuario ejecutor, tipo (crédito/débito), monto, moneda, proveedor y plataforma.
  • [x] Distinguir depósito, retiro y ajuste manual según el proveedor/tipo.
  • [x] Despachar desde:
  • [x] PerformTransactionsAction
  • [x] PerformTransactionAction
  • [x] Envolver el dispatch con DB::afterCommit().
  • [x] Evaluar el umbral de la moneda antes de enviar.
  • [x] Si la moneda no tiene umbral configurado, no enviar.
  • [x] Generar transacción para el saldo inicial al crear jugadores/agentes desde el módulo de agentes.

Fase 4 — Reglas y configuración

  • [x] Configuración en configurations (componente SERVICES, id 4), clave alerts:
{
  "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 }
    }
  }
}
  • [x] AlertConfiguration lee las reglas desde configurations (global + plataforma) y las credenciales desde .env.
  • [x] ALERTS_ENABLED en .env es el interruptor maestro; los enabled por evento siguen en configurations.
  • [x] Las credenciales de Telegram se leen de .env y no se guardan en configurations.
  • [x] Respetar ALERTS_ENABLED (.env) y alerts.enabled (configurations) como interruptores.
  • [x] Documentar cómo cambiar umbrales y activar/desactivar eventos (alerts.md).

Fase 5 — Formato y contenido de los mensajes

  • [x] Escapar todos los valores dinámicos para parse_mode=HTML.
  • [x] Formato propuesto para usuario creado:
Nuevo jugador
Usuario: juan123
IP: 203.0.113.10
Creado por: agente01
Plataforma: Casino X
Saldo inicial: 1000 ARS
  • [x] Formato propuesto para transacción:
Depósito
Usuario: juan123
IP: 203.0.113.10
Monto: 50000 ARS
Realizado por: agente01
Plataforma: Casino X
  • [x] Todas las alertas incluyen la IP del cliente.
  • [ ] Evaluar si se agregan enlaces al BackOffice (usuario/transacción).

La IP se resuelve con ClientIp: CF-Connecting-IP → X-Forwarded-For → X-Real-IP → IP del request. Esto cubre Cloudflare y el balanceador de carga.

Fase 6 — Robustez y observabilidad

  • [x] Garantizar que ninguna excepción de Telegram afecte la operación principal.
  • [x] Encolar el envío en SQS con SendTelegramAlertJob (cola vortex-play-alerts, 3 intentos).
  • [x] Capturar la IP antes de encolar para que el worker no dependa de Cloudflare.
  • [x] En local/tests la conexión sync ejecuta el job sin romper la operación si Telegram falla.
  • [ ] Registrar en log: evento, plataforma, resultado, error y tiempo de respuesta.
  • [ ] Manejar límites de Telegram (429) sin bloquear.
  • [x] Evitar incluir datos sensibles en los mensajes o logs.
  • [ ] Evaluar deduplicación o rate limit si el volumen genera ruido.

Fase 7 — Pruebas

  • [x] Test del servicio con Http::fake(): payload correcto.
  • [x] Test de usuario creado: envía mensaje.
  • [x] Test de transacción por debajo del umbral: no envía.
  • [x] Test de transacción en o por encima del umbral: envía.
  • [x] Test de moneda sin umbral: no envía.
  • [x] Test de Telegram caído: no lanza excepción.
  • [x] Test de alertas deshabilitadas: no envía.
  • [x] Prueba manual contra el canal real.

Fase 8 — Deploy y operación

  • [ ] Configurar token y chat ID en .env de cada entorno; reglas en configurations.
  • [ ] Desplegar con ALERTS_ENABLED=false o alerts.enabled=false y probar primero en un canal de pruebas.
  • [ ] Activar en producción.
  • [ ] Verificar logs y recepción real.
  • [x] Documentar en docs/ (alerts.md) y actualizar CHANGELOG.md en el release.

Fase 9 — Intentos fallidos de inicio de sesión (implementado)

  • [x] Listener sobre Illuminate\Auth\Events\Failed.
  • [x] Conteo por panel + IP en una ventana configurable.
  • [x] Alerta a Telegram al tercer intento fallido.
  • [x] Rate limit de login en 3 intentos / 60 s por IP y panel (Admin y BackOffice).
  • [x] Bloqueo de la cuenta (status=false) al quinto intento fallido, acumulado por usuario+panel en 15 minutos.
  • [x] El bloqueo de la cuenta envía la alerta al canal de usuarios.
  • [x] El contador de bloqueo se reinicia con un login exitoso.
  • [x] No incluye la contraseña ni datos sensibles.
  • [x] Tests del umbral, alerta deshabilitada, ausencia de contraseña y bloqueo de cuenta.

Configuración en configurations.data.alerts.failed_logins:

{
  "enabled": true,
  "threshold": 3,
  "window_minutes": 1
}

Fase 10 — Cambios de usuario (implementado)

  • [x] Observer de User para detectar cambios de status y password.
  • [x] Alerta al cambiar el estado (activo/bloqueado).
  • [x] Alerta al cambiar la contraseña.
  • [x] Alerta al cambiar roles desde el EditAction de usuarios del BackOffice.
  • [x] Configuración en configurations.data.alerts.user_updated.
  • [x] Tests del observer y del listener.

Fase 11 — Futuras extensiones (v2+)

  • [ ] Nuevos eventos: reset de contraseña, agente movido, cambio de comisión, cambio de RTP.
  • [ ] Reglas por plataforma/tenant.
  • [ ] Cola dedicada con reintentos y backoff.
  • [ ] Deduplicación y agrupación de alertas.
  • [ ] Administración de reglas desde el BackOffice.
  • [ ] Alertas de transacciones de juego/proveedores originadas fuera del BackOffice.
  • [ ] Canales adicionales: email, Slack, webhook.

6. Archivos previstos

config/alerts.php
app/Events/UserCreated.php
app/Events/TransactionPerformed.php
app/Events/UserUpdated.php
app/Jobs/SendTelegramAlertJob.php
app/Listeners/SendTelegramAlert.php
app/Listeners/SendFailedLoginAlert.php
app/Listeners/SendUserCreatedAlert.php
app/Listeners/SendUserUpdatedAlert.php
app/Observers/UserObserver.php
app/Services/AlertConfiguration.php
app/Services/ClientIp.php
app/Services/TelegramAlertService.php

Modificaciones:

app/Filament/Admin/Actions/Agents/CreateAgentAction.php
app/Filament/Admin/Actions/Users/CreatePlayerAction.php
app/Filament/Admin/Resources/Users/Pages/CreateUser.php
app/Filament/BackOffice/Resources/Users/Pages/ListUsers.php
app/Filament/BackOffice/Resources/Users/Tables/UsersTable.php
app/Models/User.php
app/Filament/Admin/Actions/Users/PerformTransactionsAction.php
app/Filament/Admin/Actions/Users/PerformTransactionAction.php
app/Filament/Admin/Resources/Users/Schemas/ManualBalanceAdjustmentSchema.php
.env.example

7. Criterios de aceptación

  • Al crear un jugador o agente desde el BackOffice llega una alerta al grupo.
  • Al cambiar estado, contraseña o roles de un usuario llega una alerta.
  • Todas las alertas incluyen la IP del cliente.
  • Las alertas se encolan en SQS en producción (cola vortex-play-alerts) y conservan la IP capturada.
  • Al realizar un depósito, retiro o ajuste manual en o por encima del umbral de su moneda llega una alerta.
  • Los movimientos por debajo del umbral no generan alerta.
  • Una moneda sin umbral no genera alerta.
  • Si Telegram falla, la operación de negocio termina correctamente.
  • Con ALERTS_ENABLED=false en .env no se envía nada. Con alerts.enabled=false en configurations tampoco.

8. Decisiones pendientes

  • [x] Lista definitiva de eventos de la v1.
  • [x] Valores de umbral por moneda.
  • [x] Los ajustes manuales usan el mismo umbral de crédito/débito.
  • [ ] ¿Se incluyen enlaces al BackOffice en los mensajes?
  • [x] Token del bot y chat_id del grupo.