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
Httpdirecto contrahttps://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_iddel grupo (normalmente empieza con-100). - [x] Configurar las reglas de alertas en la tabla
configurations(componenteSERVICES, id 4). - [x] Configurar
TELEGRAM_ALERT_BOT_TOKENyTELEGRAM_ALERT_CHAT_IDen.env. - [x] Configurar las credenciales de Telegram en
.env(config/alerts.phplas 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_IDestá 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.sendestá 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): boolconparse_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::errory 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
ListUsersCreateAction - [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(componenteSERVICES, id 4), clavealerts:
{
"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]
AlertConfigurationlee las reglas desdeconfigurations(global + plataforma) y las credenciales desde.env. - [x]
ALERTS_ENABLEDen.enves el interruptor maestro; losenabledpor evento siguen enconfigurations. - [x] Las credenciales de Telegram se leen de
.envy no se guardan enconfigurations. - [x] Respetar
ALERTS_ENABLED(.env) yalerts.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(colavortex-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
syncejecuta 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
.envde cada entorno; reglas enconfigurations. - [ ] Desplegar con
ALERTS_ENABLED=falseoalerts.enabled=falsey probar primero en un canal de pruebas. - [ ] Activar en producción.
- [ ] Verificar logs y recepción real.
- [x] Documentar en
docs/(alerts.md) y actualizarCHANGELOG.mden 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
Userpara detectar cambios destatusypassword. - [x] Alerta al cambiar el estado (activo/bloqueado).
- [x] Alerta al cambiar la contraseña.
- [x] Alerta al cambiar roles desde el
EditActionde 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=falseen.envno se envía nada. Conalerts.enabled=falseenconfigurationstampoco.
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_iddel grupo.