874 lines
28 KiB
Markdown
Executable File
874 lines
28 KiB
Markdown
Executable File
# Documentación Técnica del Sistema de Bots de Mensajería
|
|
|
|
## 1. Visión General del Sistema
|
|
|
|
Este es un **sistema de mensajería multiplataforma** desarrollado en PHP que permite gestionar y enviar notificaciones automatizadas a través de **Discord** y **Telegram**. El sistema incluye:
|
|
|
|
- Programación de mensajes (una vez o recurrentes)
|
|
- Traducción automática mediante LibreTranslate
|
|
- Galería de imágenes para usar en mensajes
|
|
- Plantillas de mensajes recurrentes
|
|
- Panel de administración completo
|
|
- Integración con n8n para automatización/IA
|
|
|
|
---
|
|
|
|
## 2. Tecnologías y Herramientas Utilizadas
|
|
|
|
### Backend
|
|
- **PHP 8.3+** - Lenguaje principal del servidor
|
|
- **MySQL 9.5+** - Base de datos relacional
|
|
- **Composer** - Gestión de dependencias PHP
|
|
|
|
### APIs y Servicios Externos
|
|
- **Discord API v10** - Bot de Discord (librería discord-php)
|
|
- **Telegram Bot API** - Envío de mensajes via HTTP
|
|
- **LibreTranslate** - Servicio de traducción automática
|
|
- **n8n** - Plataforma de automatización (webhooks para IA)
|
|
|
|
### Frontend
|
|
- **Bootstrap 5.3** - Framework CSS responsivo
|
|
- **Bootstrap Icons** - Iconos
|
|
- **Summernote** - Editor WYSIWYG para mensajes HTML
|
|
- **jQuery** - Manipulación del DOM
|
|
|
|
### Infraestructura
|
|
- **Zone Horaria**: America/Mexico_City (UTC-6)
|
|
- **Entornos**: pruebas, reod (producción)
|
|
- **Sistema de Logs**: Monolog + logs nativos PHP
|
|
|
|
---
|
|
|
|
## 3. Estructura de Archivos del Proyecto
|
|
|
|
```
|
|
/var/www/html/bot/
|
|
├── index.php # Dashboard principal
|
|
├── login.php # Página de inicio de sesión
|
|
├── logout.php # Cerrar sesión
|
|
├── profile.php # Perfil del usuario
|
|
│
|
|
├── create_message.php # Crear nuevo mensaje
|
|
├── edit_message.php # Editar mensaje existente
|
|
├── scheduled_messages.php # Ver mensajes programados
|
|
├── sent_messages.php # Ver mensajes enviados
|
|
├── recurrentes.php # Gestionar plantillas recurrentes
|
|
├── preview_message.php # Previsualizar mensaje
|
|
├── enviar_plantilla.php # Enviar plantilla a usuarios
|
|
│
|
|
├── gallery.php # Galería de imágenes
|
|
├── upload.php # Subir imágenes
|
|
├── delete_image.php # Eliminar imágenes
|
|
├── rename_image.php # Renombrar imágenes
|
|
├── upload_editor_image.php # Subir imágenes desde editor
|
|
│
|
|
├── change_language.php # Cambiar idioma de la interfaz
|
|
│
|
|
├── discord_bot.php # Bot de Discord (proceso largo)
|
|
├── telegram_bot_webhook.php # Webhook de Telegram
|
|
├── process_queue.php # Procesador de cola de mensajes
|
|
│
|
|
├── config/
|
|
│ └── config.php # Configuración principal
|
|
│
|
|
├── includes/ # Archivos incluidos
|
|
│ ├── db.php # Conexión a base de datos
|
|
│ ├── session_check.php # Verificación de sesión
|
|
│ ├── auth.php # Autenticación
|
|
│ ├── logger.php # Funciones de logging
|
|
│ ├── activity_logger.php # Registro de actividades
|
|
│ ├── message_handler.php # Procesamiento de mensajes
|
|
│ ├── message_handler_edit.php
|
|
│ ├── schedule_helpers.php # Funciones de programación
|
|
│ ├── schedule_actions.php # Acciones de programación
|
|
│ ├── recurrent_message_handler.php
|
|
│ ├── translation_helper.php # Helper de traducción
|
|
│ ├── url_helper.php # Helper de URLs
|
|
│ ├── emojis.php # Emojis disponibles
|
|
│ ├── get_gallery.php # Obtener imágenes galería
|
|
│ ├── error_handler.php # Manejo de errores
|
|
│ ├── telegram_actions.php # Acciones de Telegram
|
|
│ ├── discord_actions.php # Acciones de Discord
|
|
│ ├── tren_handler.php # Manejo de eventos de tren
|
|
│ ├── command_locker.php # Bloqueo de comandos
|
|
│ └── get_chat_history.php # Historial de chat
|
|
│
|
|
├── src/ # Clases principales
|
|
│ ├── Translate.php # Clase de traducción
|
|
│ ├── TelegramSender.php # Envío a Telegram
|
|
│ ├── DiscordSender.php # Envío a Discord
|
|
│ ├── HtmlToTelegramHtmlConverter.php
|
|
│ ├── HtmlToDiscordMarkdownConverter.php
|
|
│ ├── TranslationWorker.php # Worker de traducción
|
|
│ ├── TranslationCache.php # Cache de traducciones
|
|
│ ├── CommandLocker.php # Bloqueo de comandos
|
|
│ └── TranslationWorkerPool.php
|
|
│
|
|
├── discord/ # Módulo Discord
|
|
│ ├── DiscordSender.php
|
|
│ ├── converters/
|
|
│ │ └── HtmlToDiscordMarkdownConverter.php
|
|
│ └── actions/
|
|
│ └── discord_actions.php
|
|
│
|
|
├── telegram/ # Módulo Telegram
|
|
│ ├── TelegramSender.php
|
|
│ ├── converters/
|
|
│ │ └── HtmlToTelegramHtmlConverter.php
|
|
│ ├── actions/
|
|
│ │ ├── telegram_actions.php
|
|
│ │ └── send_telegram_reply.php
|
|
│ ├── admin/
|
|
│ │ ├── telegram_bot_interactions.php
|
|
│ │ ├── telegram_welcome.php
|
|
│ │ └── chat_telegram.php
|
|
│ └── webhook/
|
|
│ └── telegram_bot_webhook.php
|
|
│
|
|
├── admin/ # Panel de Administración
|
|
│ ├── users.php # Gestión de usuarios
|
|
│ ├── recipients.php # Gestión de destinatarios
|
|
│ ├── languages.php # Gestión de idiomas
|
|
│ ├── comandos.php # Gestión de comandos
|
|
│ ├── activity.php # Ver actividad del sistema
|
|
│ ├── test_discord_connection.php
|
|
│ ├── set_test_webhook.php
|
|
│ ├── sync_languages.php # Sincronizar idiomas
|
|
│ ├── get_user_groups.php
|
|
│ ├── update_language_status.php
|
|
│ └── update_language_flag.php
|
|
│
|
|
├── templates/ # Plantillas UI
|
|
│ ├── header.php # Encabezado con menú
|
|
│ └── footer.php # Pie de página
|
|
│
|
|
├── galeria/ # Imágenes del sistema
|
|
│
|
|
├── db/
|
|
│ └── bot.sql # Esquema de base de datos
|
|
│
|
|
├── logs/ # Archivos de log
|
|
│ ├── discord_bot.log
|
|
│ ├── telegram_bot_webhook.log
|
|
│ ├── process_queue.log
|
|
│ └── php_errors.log
|
|
│
|
|
├── vendor/ # Dependencias Composer
|
|
└── config/ # Configuraciones adicionales
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Estructura de la Base de Datos
|
|
|
|
### Tablas Principales
|
|
|
|
#### `users` - Usuarios del sistema
|
|
- `id` (INT, PK)
|
|
- `username` (VARCHAR)
|
|
- `password` (VARCHAR, hashed)
|
|
- `role` (ENUM: 'user', 'admin')
|
|
- `telegram_chat_id` (VARCHAR, nullable)
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `recipients` - Destinatarios (canales/usuarios)
|
|
- `id` (INT, PK)
|
|
- `platform_id` (BIGINT) - ID en Discord/Telegram
|
|
- `name` (VARCHAR)
|
|
- `type` (ENUM: 'channel', 'user')
|
|
- `platform` (ENUM: 'discord', 'telegram')
|
|
- `language_code` (VARCHAR, default 'es')
|
|
- `chat_mode` (VARCHAR) - Modo de chat: agent, bot, ia
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `messages` - Contenido de mensajes
|
|
- `id` (INT, PK)
|
|
- `user_id` (INT, FK)
|
|
- `content` (TEXT) - HTML del mensaje
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `schedules` - Programaciones de envío
|
|
- `id` (INT, PK)
|
|
- `message_id` (INT, FK)
|
|
- `recipient_id` (INT, FK)
|
|
- `send_time` (DATETIME)
|
|
- `status` (ENUM: 'draft', 'pending', 'processing', 'sent', 'failed')
|
|
- `is_recurring` (BOOLEAN)
|
|
- `recurring_days` (VARCHAR) - Días separados por coma
|
|
- `recurring_time` (TIME)
|
|
- `sent_at` (DATETIME)
|
|
- `error_message` (TEXT)
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `recurrent_messages` - Plantillas de mensajes
|
|
- `id` (INT, PK)
|
|
- `name` (VARCHAR)
|
|
- `message_content` (TEXT)
|
|
- `telegram_command` (VARCHAR) - Comando sin #
|
|
- `created_at` (TIMESTAMP)
|
|
- `updated_at` (TIMESTAMP)
|
|
|
|
#### `sent_messages` - Mensajes enviados
|
|
- `id` (INT, PK)
|
|
- `schedule_id` (INT, FK)
|
|
- `recipient_id` (INT, FK)
|
|
- `platform_message_id` (VARCHAR) - ID del mensaje en plataforma
|
|
- `message_count` (INT)
|
|
- `sent_at` (DATETIME)
|
|
|
|
#### `supported_languages` - Idiomas disponibles
|
|
- `id` (INT, PK)
|
|
- `language_code` (VARCHAR) - Código (es, pt, en, etc.)
|
|
- `language_name` (VARCHAR) - Nombre del idioma
|
|
- `flag_emoji` (VARCHAR) - Emoji de bandera
|
|
- `is_active` (BOOLEAN) - Si está activo para traducción
|
|
- `created_at` (TIMESTAMP)
|
|
- `updated_at` (TIMESTAMP)
|
|
|
|
#### `telegram_bot_messages` - Configuración de Bienvenida Telegram
|
|
- `id` (INT, PK)
|
|
- `message_text` (TEXT) - Mensaje de bienvenida (soporta {user_name})
|
|
- `button_text` (VARCHAR) - Texto del botón
|
|
- `group_invite_link` (VARCHAR) - Enlace de invitación al grupo
|
|
- `is_active` (BOOLEAN) - Si el mensaje está activo
|
|
- `register_users` (BOOLEAN) - Si se registran automáticamente los usuarios
|
|
- `updated_at` (TIMESTAMP)
|
|
|
|
#### `telegram_bot_interactions` - Registro de Interacciones Telegram
|
|
- `id` (INT, PK)
|
|
- `user_id` (BIGINT) - ID del usuario en Telegram
|
|
- `username` (VARCHAR) - Username de Telegram
|
|
- `first_name` (VARCHAR) - Nombre del usuario
|
|
- `last_name` (VARCHAR) - Apellido del usuario
|
|
- `interaction_type` (VARCHAR) - Tipo: 'message', 'start', etc.
|
|
- `interaction_date` (TIMESTAMP)
|
|
|
|
#### `settings` - Configuraciones Generales
|
|
- `setting_key` (VARCHAR, PK)
|
|
- `setting_value` (VARCHAR)
|
|
|
|
#### `telegram_welcome_messages` - Mensajes de Bienvenida por Grupo
|
|
- `id` (INT, PK)
|
|
- `chat_id` (BIGINT) - ID del grupo de Telegram
|
|
- `welcome_message` (TEXT) - Mensaje personalizado
|
|
- `button_text` (VARCHAR)
|
|
- `group_invite_link` (VARCHAR)
|
|
- `is_active` (BOOLEAN)
|
|
- `created_at` (TIMESTAMP)
|
|
- `updated_at` (TIMESTAMP)
|
|
- `language_code` (VARCHAR)
|
|
- `language_name` (VARCHAR)
|
|
- `flag_emoji` (VARCHAR)
|
|
- `is_active` (BOOLEAN)
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `translation_queue` - Cola de traducciones
|
|
- `id` (INT, PK)
|
|
- `platform` (VARCHAR)
|
|
- `message_id` (BIGINT)
|
|
- `chat_id` (BIGINT)
|
|
- `user_id` (BIGINT)
|
|
- `text_to_translate` (TEXT)
|
|
- `source_lang` (VARCHAR)
|
|
- `target_lang` (VARCHAR)
|
|
- `status` (ENUM: 'pending', 'completed', 'failed')
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `activity_log` - Registro de actividades
|
|
- `id` (INT, PK)
|
|
- `user_id` (INT)
|
|
- `username` (VARCHAR)
|
|
- `action` (VARCHAR)
|
|
- `details` (TEXT)
|
|
- `timestamp` (DATETIME)
|
|
|
|
#### `telegram_interactions` - Interacciones Telegram
|
|
- `id` (INT, PK)
|
|
- `chat_id` (BIGINT)
|
|
- `message_text` (TEXT)
|
|
- `direction` (ENUM: 'in', 'out')
|
|
- `language_code` (VARCHAR)
|
|
- `created_at` (TIMESTAMP)
|
|
|
|
#### `command_locks` - Bloqueos de comandos
|
|
- `id` (INT, PK)
|
|
- `chat_id` (BIGINT)
|
|
- `command` (VARCHAR)
|
|
- `type` (ENUM: 'command', 'translation')
|
|
- `data` (JSON)
|
|
- `message_id` (BIGINT)
|
|
- `status` (ENUM: 'processing', 'completed', 'failed')
|
|
- `created_at` (TIMESTAMP)
|
|
- `expires_at` (DATETIME)
|
|
|
|
---
|
|
|
|
## 5. Análisis del Menú y Rutas
|
|
|
|
### 5.1 Menú Principal (templates/header.php)
|
|
|
|
```
|
|
├── INICIO (index.php)
|
|
│ └── Dashboard - Vista de mensajes programados del usuario
|
|
│
|
|
├── MENSAJES (dropdown)
|
|
│ ├── Crear Mensaje (create_message.php)
|
|
│ │ ├── Carga plantillas
|
|
│ │ ├── Editor HTML (Summernote)
|
|
│ │ ├── Selección de plataforma (Discord/Telegram)
|
|
│ │ ├── Selección de destinatario
|
|
│ │ ├── Programación (ahora/fecha/recurrente)
|
|
│ │ └── Envío → includes/message_handler.php
|
|
│ │
|
|
│ ├── Programados (scheduled_messages.php)
|
|
│ │ └── Lista de mensajes pendientes/enviados
|
|
│ │
|
|
│ ├── Plantillas (recurrentes.php)
|
|
│ │ ├── Crear plantilla
|
|
│ │ ├── Editor HTML
|
|
│ │ ├── Comando Telegram (sin #)
|
|
│ │ └── includes/recurrent_message_handler.php
|
|
│ │
|
|
│ └── Enviados (sent_messages.php)
|
|
│ └── Historial de mensajes enviados
|
|
│
|
|
├── GALERÍA (gallery.php)
|
|
│ ├── Ver todas las imágenes
|
|
│ ├── Subir imagen → upload.php
|
|
│ ├── Renombrar → rename_image.php
|
|
│ └── Eliminar → delete_image.php
|
|
│
|
|
├── ADMIN (solo admins)
|
|
│ ├── Gestión
|
|
│ │ ├── Usuarios (admin/users.php)
|
|
│ │ │ ├── Crear usuario
|
|
│ │ │ ├── Editar usuario
|
|
│ │ │ ├── Asignar rol (user/admin)
|
|
│ │ │ └── Vincular Telegram
|
|
│ │ │
|
|
│ │ └── Destinatarios (admin/recipients.php)
|
|
│ │ ├── Listar canales/usuarios Discord
|
|
│ │ ├── Listar canales/usuarios Telegram
|
|
│ │ ├── Editar idioma
|
|
│ │ └── Eliminar destinatario
|
|
│ │
|
|
│ ├── Configuración
|
|
│ │ ├── Idiomas (admin/languages.php)
|
|
│ │ │ ├── Lista de idiomas soportados
|
|
│ │ │ ├── Activar/desactivar idioma
|
|
│ │ │ ├── Editar bandera emoji
|
|
│ │ │ └── Sincronizar con LibreTranslate
|
|
│ │ │
|
|
│ │ └── Comandos (admin/comandos.php)
|
|
│ │ └── Lista de comandos disponibles
|
|
│ │
|
|
│ ├── Bots (Telegram)
|
|
│ │ ├── Config (telegram/admin/telegram_welcome.php)
|
|
│ │ │ └── Configurar mensaje de bienvenida
|
|
│ │ │
|
|
│ │ ├── Interacciones Bot (telegram/admin/telegram_bot_interactions.php)
|
|
│ │ │ └── Ver interacciones de usuarios
|
|
│ │ │
|
|
│ │ └── Chat Telegram (telegram/admin/chat_telegram.php)
|
|
│ │ └── Ver historial de chat
|
|
│ │
|
|
│ └── Monitoreo
|
|
│ ├── Actividad (admin/activity.php)
|
|
│ │ └── Log de actividades del sistema
|
|
│ │
|
|
│ └── Test (admin/test_discord_connection.php)
|
|
│ └── Probar conexión con Discord
|
|
│
|
|
├── PERFIL (profile.php)
|
|
│ └── Configuración de cuenta de usuario
|
|
│
|
|
└── CERRAR SESIÓN (logout.php)
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Flujo de Funcionamiento
|
|
|
|
### 6.1 Creación y Envío de Mensaje
|
|
|
|
```
|
|
1. Usuario inicia sesión (login.php)
|
|
└── Valida credenciales → includes/auth.php
|
|
└── Crea sesión PHP
|
|
|
|
2. Usuario crea mensaje (create_message.php)
|
|
├── Selecciona plantilla (opcional)
|
|
├── Escribe/edita contenido HTML (Summernote)
|
|
├── Selecciona plataforma (Discord/Telegram)
|
|
├── Selecciona destinatario(s)
|
|
├── Selecciona programación:
|
|
│ ├── Enviar ahora
|
|
│ ├── Programar para fecha/hora
|
|
│ └── Programación recurrente (días + hora)
|
|
└── Envía formulario
|
|
|
|
3. Procesamiento (includes/message_handler.php)
|
|
├── Valida datos
|
|
├── Inserta mensaje en tabla `messages`
|
|
├── Inserta programación en tabla `schedules`
|
|
└── Si es "enviar ahora":
|
|
└── Ejecuta process_queue.php en background
|
|
|
|
4. Cola de procesamiento (process_queue.php)
|
|
├── Se ejecuta cada minuto (cron job)
|
|
├── Busca mensajes pending con send_time <= ahora
|
|
├── Marca como 'processing'
|
|
├── Convierte HTML a formato de plataforma:
|
|
│ ├── Discord → DiscordSender + HtmlToDiscordMarkdownConverter
|
|
│ └── Telegram → TelegramSender + HtmlToTelegramHtmlConverter
|
|
├── Envía mensaje a API de plataforma
|
|
├── Registra en `sent_messages`
|
|
├── Si es recurrente, calcula próximo envío
|
|
└── Marca como 'sent' o 'failed'
|
|
|
|
5. Usuario puede ver:
|
|
├── Mensajes programados (scheduled_messages.php)
|
|
├── Mensajes enviados (sent_messages.php)
|
|
└── Plantillas guardadas (recurrentes.php)
|
|
```
|
|
|
|
### 6.2 Flujo de Traducción Automática
|
|
|
|
```
|
|
1. Mensaje se crea con atributo data-translate="true"
|
|
→ Se encola para traducción
|
|
|
|
2. Translation Worker (process_translation_queue.php)
|
|
├── Detecta idioma original (LibreTranslate /detect)
|
|
├── Traduce a cada idioma activo (LibreTranslate /translate)
|
|
├── Guarda en translation_queue
|
|
└── Envía resultado a usuario
|
|
|
|
3. Botones de traducción en Telegram
|
|
├── Se añaden después de enviar mensaje
|
|
├── Callback: translate:{message_id}:{lang}
|
|
└── Usuario puede traducir manualmente
|
|
|
|
4. Botones de traducción en Discord
|
|
├── Se añaden después de enviar mensaje
|
|
├── Botones con estilo: translate_manual:{lang}
|
|
└── Traducción inline en canal
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Bots de Mensajería
|
|
|
|
### 7.1 Bot de Discord (discord_bot.php)
|
|
|
|
**Tecnologías:**
|
|
- Librería `discord-php` (v7+)
|
|
- WebSockets para eventos en tiempo real
|
|
- API REST para envío de mensajes
|
|
|
|
**Eventos manejados:**
|
|
|
|
| Evento | Acción |
|
|
|--------|--------|
|
|
| `GUILD_MEMBER_ADD` | Registra nuevo miembro en recipients |
|
|
| `MESSAGE_CREATE` | Procesa mensajes entrantes |
|
|
| `INTERACTION_CREATE` | Maneja clics en botones |
|
|
|
|
**Comandos disponibles:**
|
|
|
|
| Comando | Descripción |
|
|
|---------|-------------|
|
|
| `#comando` | Envía plantilla de mensaje |
|
|
| `/comandos` | Lista de comandos disponibles |
|
|
| `/setlang XX` | Establece idioma del usuario |
|
|
| `/bienvenida` | Envía mensaje de bienvenida |
|
|
| `/agente [prompt]` | Envía a n8n para IA |
|
|
| `!ping` | Responde "pong!" |
|
|
|
|
**Modos de Chat:**
|
|
- `agent`: Menú de selección (bot/IA)
|
|
- `bot`: Comandos normales
|
|
- `ia`: Todo se envía a n8n
|
|
|
|
**Traducción:**
|
|
- Detecta idioma automáticamente
|
|
- Encola traducciones para todos los idiomas activos
|
|
- Botones para traducir manualmente
|
|
|
|
### 7.2 Bot de Telegram (telegram_bot_webhook.php)
|
|
|
|
**Tecnologías:**
|
|
- API de Webhooks de Telegram
|
|
- cURL para llamadas HTTP
|
|
|
|
**Flujo de un mensaje:**
|
|
|
|
```
|
|
1. Telegram envía Update al webhook
|
|
└── Autenticación por auth_token
|
|
|
|
2. Determina tipo de chat:
|
|
├── Chat privado → Modo agente/IA
|
|
│ ├── Registro de nuevo usuario
|
|
│ ├── Menú de bienvenida
|
|
│ └── Modos: agent, bot, ia
|
|
│
|
|
└── Grupo/Canal → Lógica de bot
|
|
├── Nuevos miembros → Se registran
|
|
├── Comandos (/) → Se procesan
|
|
├── #comando → Envía plantilla
|
|
└── Mensajes normales → Traducción
|
|
|
|
3. Comandos disponibles:
|
|
├── /setlang XX - Idioma
|
|
├── /bienvenida - Mensaje de bienvenida
|
|
├── /comandos - Lista de comandos
|
|
└── /agente - Cambiar a modo IA
|
|
|
|
4. Traducción:
|
|
├── Automática en cola
|
|
└── Botones inline para traducir
|
|
|
|
### 7.3 Registro de Usuarios y Mensajes de Bienvenida
|
|
|
|
#### Discord - Registro de Nuevos Miembros
|
|
|
|
Cuando un nuevo miembro se une al servidor de Discord, el bot ejecuta el evento `GUILD_MEMBER_ADD`:
|
|
|
|
```
|
|
Evento: GUILD_MEMBER_ADD
|
|
└── Se ejecuta en: discord_bot.php (líneas 53-66)
|
|
│
|
|
├── 1. Obtiene datos del miembro:
|
|
│ ├── platform_id = member.id (ID de Discord)
|
|
│ ├── name = member.user.username
|
|
│ └── platform = 'discord'
|
|
│
|
|
├── 2. Inserta/actualiza en tabla 'recipients':
|
|
│ └── INSERT INTO recipients (platform_id, name, type, platform, language_code)
|
|
│ VALUES (?, ?, 'user', 'discord', 'es')
|
|
│ ON DUPLICATE KEY UPDATE name = VALUES(name)
|
|
│
|
|
└── 3. Queda registrado para recibir mensajes
|
|
```
|
|
|
|
**Ubicación en código:** `discord_bot.php:53-66`
|
|
|
|
#### Telegram - Registro de Nuevos Usuarios
|
|
|
|
Cuando un usuario interactúa por primera vez con el bot de Telegram:
|
|
|
|
```
|
|
Evento: Primer mensaje / interacción
|
|
└── Se ejecuta en: telegram_bot_webhook.php (líneas 99-142)
|
|
│
|
|
├── 1. Verifica configuración de registro:
|
|
│ └── SELECT * FROM telegram_bot_messages WHERE id = 1
|
|
│ └── register_users = 1 (habilitado por defecto)
|
|
│
|
|
├── 2. Obtiene datos del usuario:
|
|
│ ├── platform_id = from.id
|
|
│ ├── name = first_name + last_name
|
|
│ ├── language_code = from.language_code
|
|
│ └── platform = 'telegram'
|
|
│
|
|
├── 3. Inserta en tabla 'recipients':
|
|
│ └── INSERT INTO recipients (platform_id, name, type, platform, language_code, chat_mode)
|
|
│ VALUES (?, ?, 'user', 'telegram', ?, 'agent')
|
|
│ ON DUPLICATE KEY UPDATE name = VALUES(name)
|
|
│
|
|
└── 4. Si está activo, envía mensaje de bienvenida:
|
|
├── Lee configuración: telegram_bot_messages
|
|
├── Reemplaza {user_name} con el nombre del usuario
|
|
├── Envía botón con enlace al grupo
|
|
└── Registra interacción en telegram_bot_interactions
|
|
```
|
|
|
|
**Ubicación en código:** `telegram_bot_webhook.php:99-142`
|
|
|
|
#### Telegram - Nuevos Miembros en Grupos
|
|
|
|
Cuando un nuevo miembro se une a un grupo de Telegram:
|
|
|
|
```
|
|
Evento: new_chat_members (en grupos)
|
|
└── Se ejecuta en: telegram_bot_webhook.php (líneas 222-234)
|
|
│
|
|
├── 1. Detecta nuevos miembros:
|
|
│ └── message['new_chat_members']
|
|
│
|
|
├── 2. Para cada nuevo miembro (si no es bot):
|
|
│ ├── Registra en recipients
|
|
│ └── Language code del usuario
|
|
│
|
|
└── 3. No envía bienvenida automática (solo en chat privado)
|
|
```
|
|
|
|
**Ubicación en código:** `telegram_bot_webhook.php:222-234`
|
|
|
|
#### Mensaje de Bienvenida - Configuración
|
|
|
|
Los mensajes de bienvenida se configuran desde el panel de admin:
|
|
|
|
**Para Telegram:**
|
|
- **Ubicación**: `telegram/admin/telegram_bot_interactions.php`
|
|
- **Tabla**: `telegram_bot_messages`
|
|
- **Campos configurables**:
|
|
- `message_text`: Texto del mensaje (soporta `{user_name}`)
|
|
- `button_text`: Texto del botón de invitación
|
|
- `group_invite_link`: Enlace al grupo de Telegram
|
|
- `is_active`: Habilitar/deshabilitar mensaje
|
|
- `register_users`: Registrar automáticamente usuarios
|
|
|
|
**Ejemplo de mensaje de bienvenida:**
|
|
```
|
|
¡Hola {user_name}! 👋
|
|
|
|
Puedes usar /comandos para obtener una lista de comandos con
|
|
la información que tenemos sobre el juego y solicitarla con el #comando.
|
|
|
|
También puedes usar /agente, para interactuar con los comandos
|
|
o con la AI que tenemos.
|
|
|
|
Gracias por interactuar con nuestro bot de REOD.
|
|
Únete a nuestro grupo principal para mantenerte actualizado.
|
|
```
|
|
|
|
**Tabla de Interacciones:**
|
|
- Los usuarios quedan registrados en `telegram_bot_interactions`
|
|
- Tipos de interacción: 'message', 'start', 'callback', etc.
|
|
- Permite hacer auditoría de uso del bot
|
|
|
|
---
|
|
|
|
## 8. Páginas Principales y sus Archivos
|
|
|
|
### index.php (Dashboard)
|
|
- **Propósito**: Mostrar mensajes programados del usuario
|
|
- **Archivos incluidos**:
|
|
- `includes/session_check.php`
|
|
- `includes/db.php`
|
|
- `templates/header.php`
|
|
- `templates/footer.php`
|
|
- **Datos**: Query de `schedules` + `messages` + `recipients`
|
|
|
|
### create_message.php (Crear Mensaje)
|
|
- **Propósito**: Formulario para crear nuevo mensaje
|
|
- **Archivos incluidos**:
|
|
- `includes/session_check.php`
|
|
- `includes/db.php`
|
|
- `templates/header.php`
|
|
- `templates/footer.php`
|
|
- **Funcionalidades**:
|
|
- Carga plantillas de `recurrent_messages`
|
|
- Editor Summernote
|
|
- Galería de imágenes (modal)
|
|
- Selección de plataforma/destinatario
|
|
- Programación (ahora/fecha/recurrente)
|
|
|
|
### scheduled_messages.php
|
|
- **Propósito**: Lista de mensajes programados
|
|
- **Procesa**: Tabla `schedules` con JOINs
|
|
|
|
### recurrentes.php (Plantillas)
|
|
- **Propósito**: Gestionar plantillas de mensajes
|
|
- **Archivos incluidos**:
|
|
- `includes/recurrent_message_handler.php`
|
|
- **Funcionalidades**:
|
|
- CRUD de plantillas
|
|
- Comando Telegram asociado
|
|
- Preview de contenido
|
|
|
|
### gallery.php
|
|
- **Propósito**: Gestión de imágenes
|
|
- **Archivos**: `upload.php`, `delete_image.php`, `rename_image.php`
|
|
- **Carpeta**: `/galeria/`
|
|
|
|
### admin/users.php
|
|
- **Propósito**: Gestión de usuarios del sistema
|
|
- **Acceso**: Solo admins (`role = 'admin'`)
|
|
- **Funcionalidades**:
|
|
- Crear/editar usuarios
|
|
- Asignar roles
|
|
- Vincular Telegram
|
|
|
|
### admin/recipients.php
|
|
- **Propósito**: Gestión de destinatarios
|
|
- **Plataformas**: Discord + Telegram
|
|
- **Tipos**: Canales + Usuarios
|
|
|
|
### admin/languages.php
|
|
- **Propósito**: Configurar idiomas de traducción
|
|
- **Proveedor**: LibreTranslate
|
|
- **Funcionalidades**:
|
|
- Activar/desactivar idiomas
|
|
- Editar emoji de bandera
|
|
- Sincronización con API
|
|
|
|
### telegram/admin/telegram_bot_interactions.php
|
|
- **Propósito**: Configurar mensaje de bienvenida de Telegram
|
|
- **Tabla**: `telegram_bot_messages`
|
|
- **Funcionalidades**:
|
|
- Editar mensaje de bienvenida
|
|
- Configurar botón de invitación
|
|
- Establecer enlace al grupo
|
|
- Activar/desactivar registro automático de usuarios
|
|
|
|
### telegram/admin/telegram_welcome.php
|
|
- **Propósito**: Configurar mensajes de bienvenida por grupo
|
|
- **Tabla**: `telegram_welcome_messages`
|
|
- **Funcionalidades**:
|
|
- Configurar mensaje por cada grupo
|
|
- Personalizar botón e invitación
|
|
|
|
### telegram/admin/chat_telegram.php
|
|
- **Propósito**: Ver historial de interacciones con el bot
|
|
- **Tabla**: `telegram_bot_interactions`
|
|
- **Funcionalidades**:
|
|
- Lista de usuarios que han interactuado
|
|
- Tipo de interacción (message, start, etc.)
|
|
- Fecha de última interacción
|
|
|
|
### admin/activity.php
|
|
- **Propósito**: Ver registro de actividades del sistema
|
|
- **Tabla**: `activity_log`
|
|
- **Acciones registradas**:
|
|
- Inicio/cierre de sesión
|
|
- Creación de mensajes
|
|
- Eliminación de mensajes
|
|
- Actualizaciones de usuarios
|
|
- Eliminación de imágenes
|
|
|
|
---
|
|
|
|
## 9. Variables de Entorno (.env)
|
|
|
|
```env
|
|
# Entorno
|
|
APP_ENVIRONMENT=pruebas # o 'reod' para producción
|
|
|
|
# Base de datos
|
|
DB_HOST=10.10.4.17
|
|
DB_PORT=3390
|
|
DB_NAME=bot
|
|
DB_USER=root
|
|
DB_PASS=*****
|
|
|
|
# Discord
|
|
DISCORD_BOT_TOKEN=*****
|
|
DISCORD_GUILD_ID=*****
|
|
DISCORD_CLIENT_ID=*****
|
|
DISCORD_CLIENT_SECRET=*****
|
|
|
|
# Telegram
|
|
TELEGRAM_BOT_TOKEN=*****
|
|
TELEGRAM_WEBHOOK_TOKEN=*****
|
|
|
|
# Traducción
|
|
LIBRETRANSLATE_URL=http://libretranslate:5000
|
|
|
|
# n8n (Automatización/IA)
|
|
N8N_URL=*****
|
|
N8N_TOKEN=*****
|
|
N8N_IA_WEBHOOK_URL=*****
|
|
N8N_IA_WEBHOOK_URL_DISCORD=*****
|
|
N8N_PROCESS_QUEUE_WEBHOOK_URL=*****
|
|
|
|
# Seguridad
|
|
JWT_SECRET=*****
|
|
APP_URL=https://tu-dominio.com
|
|
|
|
# API Interna
|
|
INTERNAL_API_KEY=*****
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Configuración de Producción
|
|
|
|
### Cron Jobs Recomendados
|
|
|
|
```bash
|
|
# Procesar cola de mensajes cada minuto
|
|
* * * * * /usr/bin/php /var/www/html/bot/process_queue.php
|
|
|
|
# Limpiar logs antiguos (semanalmente)
|
|
0 0 * * 0 find /var/www/html/bot/logs -name "*.log" -mtime +30 -delete
|
|
|
|
# Reiniciar bots si fallan (cada 5 minutos)
|
|
*/5 * * * * pgrep -f "discord_bot.php" || /usr/bin/php /var/www/html/bot/discord_bot.php >> /var/www/html/bot/logs/discord_bot.out.log 2>&1 &
|
|
```
|
|
|
|
### Webhooks
|
|
|
|
```
|
|
# Telegram Webhook
|
|
https://tu-dominio.com/telegram_bot_webhook.php?auth_token=TOKEN
|
|
|
|
# n8n (procesamiento)
|
|
URL configurable desde admin
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Funcionalidades por Archivo
|
|
|
|
| Archivo | Función Principal |
|
|
|---------|-------------------|
|
|
| `discord_bot.php` | Bot de Discord en tiempo real |
|
|
| `telegram_bot_webhook.php` | Recibe mensajes de Telegram |
|
|
| `process_queue.php` | Procesa mensajes programados |
|
|
| `includes/message_handler.php` | Maneja creación/edición de mensajes |
|
|
| `src/Translate.php` | Wrapper para LibreTranslate |
|
|
| `discord/DiscordSender.php` | Envía mensajes a Discord |
|
|
| `telegram/TelegramSender.php` | Envía mensajes a Telegram |
|
|
| `common/helpers/converter_factory.php` | Convierte HTML entre formatos |
|
|
|
|
---
|
|
|
|
## 12. Resumen de Flujos
|
|
|
|
### Flujo Completo de un Mensaje Programado
|
|
|
|
```
|
|
Usuario → create_message.php → message_handler.php
|
|
→ schedules (DB) → process_queue.php (cron)
|
|
→ DiscordSender/TelegramSender → API Plataforma
|
|
→ sent_messages (DB) → (si recurrente) → recalcular próximo
|
|
```
|
|
|
|
### Flujo de Traducción
|
|
|
|
```
|
|
Mensaje con data-translate="true"
|
|
→ translation_queue (DB)
|
|
→ TranslationWorker
|
|
→ LibreTranslate
|
|
→ Envío a usuario
|
|
```
|
|
|
|
### Flujo de Bot (Discord/Telegram)
|
|
|
|
```
|
|
Plataforma → Webhook/Bot Event
|
|
→ Verificar usuario
|
|
→ Procesar comando/traducción
|
|
→ Responder
|
|
→ Actualizar DB
|
|
```
|
|
|
|
---
|
|
|
|
## 13. Conclusiones
|
|
|
|
El sistema está bien estructurado y cumple con los siguientes objetivos:
|
|
|
|
1. **Multiplataforma**: Soporta Discord y Telegram desde una sola interfaz
|
|
2. **Flexible**: Permite programación simple o recurrente
|
|
3. **Traducible**: Integración con LibreTranslate para automático y manual
|
|
4. **Escalable**: Uso de colas y workers para procesamiento asíncrono
|
|
5. **Administrable**: Panel completo para gestión de usuarios, destinatarios e idiomas
|
|
6. **Integrado**: Conexión con n8n para automatización avanzada e IA
|
|
|
|
El código utiliza patrones modernos de PHP (PDO, Composer, Namespaces) y sigue una estructura modular que facilita el mantenimiento y expansión futura.
|