# 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.
