Initial commit - Last War messaging system

2026-02-19 01:33:28 -06:00
commit 38a8447a64
2162 changed files with 216183 additions and 0 deletions
--- a/DOCUMENTACION_COMPLEMENTO.md
+++ b/DOCUMENTACION_COMPLEMENTO.md
@@ -0,0 +1,469 @@
+# Complemento de Documentación - Funcionalidades Adicionales
+
+Este documento complementa el archivo principal `DOCUMENTACION_SISTEMA.md` con funcionalidades adicionales descubiertas.
+
+---
+
+## 1. Sistema de Traducción
+
+### 1.1 Proceso de Traducción Automática
+
+El sistema tiene múltiples capas de traducción:
+
+#### A) Traducción en Tiempo Real (durante envío)
+Cuando se envía un mensaje con el flag `data-translate="true"`, el sistema:
+1. Detecta el idioma del mensaje
+2. Traduce a todos los idiomas activos configurados
+3. Envía las traducciones junto con el mensaje original
+
+**Archivos involucrados:**
+- `src/Translate.php` - Clase principal de traducción
+- `process_queue.php` - Procesa el envío y traducción
+
+#### B) Cola de Traducción Asíncrona (`process_translation_queue.php`)
+Procesa traducciones de mensajes de usuarios en background:
+
+```
+Flujo:
+1. Mensaje de usuario entra al sistema
+2. Se encola en tabla translation_queue
+3. Worker procesa la cola:
+   - Detecta idioma origen
+   - Traduce a todos los idiomas activos
+   - Envía embed con traducciones
+4. Marca como completed/failed
+```
+
+**Características:**
+- Usa `pcntl` para señales (SIGINT, SIGTERM)
+- Bloqueo de filas con `FOR UPDATE SKIP LOCKED`
+- Reintentos (attempts < 5)
+- Manejo de menciones de Discord (protege durante traducción)
+
+**Tabla: `translation_queue`**
+- `id`, `platform`, `message_id`, `chat_id`, `user_id`
+- `text_to_translate`, `source_lang`, `target_lang`
+- `status` (pending/processing/completed/failed)
+- `attempts`, `error_message`, `created_at`, `processed_at`
+
+#### C) Traducción Manual (Botones)
+
+**Discord:**
+- Después de enviar una plantilla, se añaden botones de traducción
+- Botón: `translate_manual:{lang}` o `translate_template:{command}:{lang}`
+- Traduce el mensaje al idioma seleccionado
+
+**Telegram:**
+- Botones inline con callback `translate:{message_id}:{lang}`
+- Traduce y envía como mensaje nuevo
+
+### 1.2 Proxy de Traducción (`translate_proxy.php`)
+
+API REST que permite traducciones externas:
+- Expone endpoints de LibreTranslate
+- Maneja CORS
+- Lee configuración de entorno
+
+---
+
+## 2. Sistema de Mensajería
+
+### 2.1 Tipos de Programación
+
+El sistema soporta múltiples tipos de envío:
+
+| Tipo | Descripción | Campo |
+|------|-------------|-------|
+| `now` | Envío inmediato | send_time = NOW() |
+| `later` | Programado para fecha/hora específica | send_time = fecha futura |
+| `recurring` | Recurrente (días de la semana) | is_recurring=1 + recurring_days + recurring_time |
+
+### 2.2 Estados de un Mensaje
+
+| Estado | Significado |
+|--------|-------------|
+| `draft` | Guardado sin programar |
+| `pending` | Esperando fecha de envío |
+| `processing` | Siendo enviado en este momento |
+| `sent` | Enviado exitosamente |
+| `failed` | Error en el envío |
+| `cancelled` | Cancelado por usuario |
+| `disabled` | Deshabilitado temporalmente |
+
+### 2.3 Acciones sobre Mensajes Programados (`schedule_actions.php`)
+
+| Acción | Descripción |
+|--------|-------------|
+| `disable` | Deshabilita el mensaje (status = disabled) |
+| `enable` | Habilita mensaje deshabilitado (status = pending) |
+| `cancel` | Cancela el envío (status = cancelled) |
+| `retry` | Reintenta envío fallido (status = pending) |
+| `delete` | Elimina la programación completamente |
+
+---
+
+## 3. Plantillas y Comandos
+
+### 3.1 Sistema de Comandos
+
+Las plantillas pueden tener comandos asociados (sin #) que los usuarios pueden ejecutar en Discord/Telegram:
+
+```
+Comando en Telegram/Discord: #Dia6
+└── Sistema busca en recurrent_messages WHERE telegram_command = 'Dia6'
+    └── Envía el message_content convertido al formato de la plataforma
+```
+
+### 3.2 Envío desde Plantillas (`enviar_plantilla.php`)
+
+Página para enviar rápidamente una plantilla a múltiples destinatarios:
+- Seleccionar plantilla
+- Elegir plataforma (Discord/Telegram)
+- Seleccionar múltiples destinatarios
+- Programar o enviar inmediatamente
+
+---
+
+## 4. Galería de Imágenes
+
+### 4.1 Gestión de Imágenes
+
+**Ubicación:** `/galeria/`
+
+**Operaciones:**
+- `upload.php` - Subir nuevas imágenes
+- `delete_image.php` - Eliminar imágenes
+- `rename_image.php` - Renombrar imágenes
+- `upload_editor_image.php` - Subir desde el editor de mensajes
+
+### 4.2 Uso en Mensajes
+
+Las imágenes se insertan en el editor HTML (Summernote):
+- Modal de galería en `create_message.php` y `recurrentes.php`
+- Las URLs se almacenan relativas: `galeria/nombre.jpg`
+- Al enviar, se convierten a URLs absolutas
+
+---
+
+## 5. Conversores de Formato
+
+El sistema necesita convertir HTML a los formatos de cada plataforma:
+
+### 5.1 Discord (`discord/converters/HtmlToDiscordMarkdownConverter.php`)
+- Convierte etiquetas HTML a Markdown de Discord
+- Maneja imágenes, negritas, énfasis, etc.
+
+### 5.2 Telegram (`telegram/converters/HtmlToTelegramHtmlConverter.php`)
+- Convierte HTML a formato HTML de Telegram
+- Soporta parse_mode=HTML
+
+### 5.3 Factory (`common/helpers/converter_factory.php`)
+- Patrón Factory para obtener el conversor correcto según plataforma
+
+---
+
+## 6. Remitentes (Senders)
+
+### 6.1 DiscordSender (`discord/DiscordSender.php`)
+- Envía mensajes via API REST de Discord
+- Divide mensajes largos (límite 2000 caracteres)
+- Maneja imágenes como adjuntos o embeds
+- Envía botones interactivos
+
+### 6.2 TelegramSender (`telegram/TelegramSender.php`)
+- Envía mensajes via API de Telegram Bot
+- Maneja múltiples partes (texto + imágenes)
+- Soporta botones inline
+- Reply markup
+
+---
+
+## 7. Autenticación y Sesiones
+
+### 7.1 Sistema de Login (`login.php` + `includes/auth.php`)
+- Autenticación con username/password
+- Hash de contraseñas con `password_hash()`
+- Sesiones PHP con verificación de rol
+
+### 7.2 Verificación de Sesión (`includes/session_check.php`)
+- Se incluye en todas las páginas protegidas
+- Verifica `$_SESSION['user_id']` y `$_SESSION['role']`
+- Redirige a login si no hay sesión
+
+### 7.3 Perfil de Usuario (`profile.php`)
+- Permite cambiar contraseña
+- Información de cuenta
+
+---
+
+## 8. Utilidades y Helpers
+
+### 8.1 Helpers Principales
+
+| Archivo | Función |
+|---------|---------|
+| `includes/url_helper.php` | Funciones de URL (site_url, asset, url) |
+| `includes/logger.php` | Función `custom_log()` para logs |
+| `includes/activity_logger.php` | Registro de actividades de usuarios |
+| `includes/emojis.php` | Utilidades de emojis |
+| `includes/schedule_helpers.php` | Cálculo de próximas fechas de envío |
+| `includes/error_handler.php` | Manejo de errores |
+
+### 8.2 Rutas de Archivos Comunes
+
+```
+includes/
+├── session_check.php     → Verifica sesión en cada página
+├── db.php              → Conexión PDO a MySQL
+├── auth.php            → Funciones de autenticación
+├── logger.php          → custom_log()
+├── activity_logger.php → log_activity()
+├── message_handler.php → Procesa create/edit de mensajes
+├── schedule_actions.php → Disable/enable/cancel/delete mensajes
+├── recurrent_message_handler.php → CRUD plantillas
+└── get_gallery.php     → Obtiene imágenes de galeria/
+
+common/helpers/
+├── sender_factory.php     → Factory para obtener sender correcto
+├── converter_factory.php  → Factory para obtener conversor
+├── schedule_helpers.php  → calculateNextSendTime()
+├── url_helper.php        → Funciones de URL
+└── emojis.php           → Utilidades de emojis
+```
+
+---
+
+## 9. Workers y Procesos en Background
+
+### 9.1 process_queue.php
+Procesa mensajes programados cada minuto (cron):
+- Busca schedules con status='pending' y send_time <= ahora
+- Marca como 'processing'
+- Envía mensaje
+- Registra en sent_messages
+- Si es recurrente, calcula próximo envío
+
+### 9.2 process_translation_queue.php
+Worker de traducción asíncrono:
+- Corre como proceso daemon
+- Procesa translation_queue
+- Envía traducciones a Discord/Telegram
+
+### 9.3 discord_bot.php
+Bot de Discord en tiempo real:
+- Corre como proceso largo (php discord_bot.php)
+- Escucha eventos via WebSocket
+- No usa cron, responde inmediatamente
+
+### 9.4 run_manual_translation.php
+Script CLI para traducciones manuales:
+- Uso: `php run_manual_translation.php <msgId> <targetLang> <userId> <channelId>`
+- Traduce plantillas bajo demanda
+
+---
+
+## 10. Configuración de Webhooks
+
+### 10.1 Telegram Webhook
+- **Archivo:** `telegram_bot_webhook.php` o `telegram/webhook/telegram_bot_webhook.php`
+- **URL:** `https://tu-dominio.com/telegram_bot_webhook.php?auth_token=TOKEN`
+- **Set webhook:** `set_webhook.php`
+
+### 10.2 Endpoints de Configuración
+
+| Archivo | Función |
+|---------|---------|
+| `set_webhook.php` | Configura webhook de Telegram |
+| `configure_webhook.php` | UI para configurar webhooks |
+| `check_webhook.php` | Verifica estado del webhook |
+
+---
+
+## 11. Páginas de Administración Adicionales
+
+### 11.1 Actividades (`admin/activity.php`)
+Muestra el log de actividades de la tabla `activity_log`:
+- Inicios/cierres de sesión
+- Creación/eliminación de mensajes
+- Actualizaciones de usuarios
+- Eliminación de imágenes
+
+### 11.2 Test de Conexión (`admin/test_discord_connection.php`)
+Permite probar la conexión con Discord:
+- Verifica token del bot
+- Prueba envío de mensaje de prueba
+
+### 11.3 Comandos (`admin/comandos.php`)
+Lista los comandos disponibles en el sistema.
+
+### 11.4 Opciones de Traducción Discord (`discord/admin/discord_translation_options.php`)
+Configuración específica de traducción para Discord.
+
+---
+
+## 12. Utilidades Varias
+
+### 12.1 Cambio de Idioma (`change_language.php`)
+Permite cambiar el idioma de la interfaz de la aplicación.
+
+### 12.2 Log Frontend (`log_frontend.php`)
+Muestra los logs de JavaScript del lado del cliente.
+
+### 12.3 Verificador de Contraseña (`verify_password.php`)
+API para verificar contraseñas (probablemente usado en algún proceso de autenticación externo).
+
+### 12.4 Verificador Directo (`direct_check.php`)
+Verificación directa de algún estado del sistema.
+
+### 12.5 Limpiar OPCache (`clear_opcache.php`)
+Utilidad para limpiar el OPCache de PHP.
+
+### 12.6 Reset de Estado (`reset_status.php`)
+Reinicia estados de mensajes (útil para debugging).
+
+---
+
+## 13. Variables de Entorno Completas
+
+```env
+# Aplicación
+APP_ENVIRONMENT=pruebas  # o 'reod'
+APP_URL=https://bot.tudominio.com
+
+# Base de datos
+DB_HOST=10.10.4.17
+DB_PORT=3390
+DB_NAME=bot
+DB_USER=root
+DB_PASS=***
+DB_DIALECT=mysql
+
+# Discord
+DISCORD_BOT_TOKEN=***
+DISCORD_GUILD_ID=***
+DISCORD_CLIENT_ID=***
+DISCORD_CLIENT_SECRET=***
+
+# Telegram
+TELEGRAM_BOT_TOKEN=***
+TELEGRAM_WEBHOOK_TOKEN=***
+
+# LibreTranslate
+LIBRETRANSLATE_URL=http://libretranslate:5000
+
+# n8n (Automatización)
+N8N_URL=https://n8n.tudominio.com
+N8N_TOKEN=***
+N8N_IA_WEBHOOK_URL=***
+N8N_IA_WEBHOOK_URL_DISCORD=***
+N8N_PROCESS_QUEUE_WEBHOOK_URL=***
+
+# Seguridad
+JWT_SECRET=***
+INTERNAL_API_KEY=***
+
+# Docker
+DOCKER_CONTAINER=1
+```
+
+---
+
+## 14. Estructura de la Base de Datos (Tablas Completas)
+
+```sql
+-- Tablas principales
+users              -- Usuarios del sistema
+recipients         -- Canales/usuarios de Discord/Telegram
+messages           -- Contenido de mensajes
+schedules          -- Programaciones de envío
+recurrent_messages -- Plantillas de mensajes
+sent_messages      -- Registro de mensajes enviados
+activity_log       -- Log de actividades
+
+-- Configuración
+settings                    -- Configuraciones generales
+supported_languages         -- Idiomas para traducción
+telegram_bot_messages       -- Mensaje de bienvenida Telegram
+telegram_bot_interactions  -- Interacciones de usuarios Telegram
+telegram_welcome_messages   -- Mensajes de bienvenida por grupo
+command_locks              -- Bloqueos de comandos (evitar duplicados)
+
+-- Traducción
+translation_queue         -- Cola de traducciones
+languages                  -- Tabla legacy de idiomas
+```
+
+---
+
+## 15. Flujo Completo: Desde la Creación hasta el Envío
+
+```
+1. USUARIO CREA MENSAJE
+   create_message.php
+   └─> Editor HTML (Summernote)
+   └─> Selecciona plataforma, destinatario, programación
+
+2. PROCESAMIENTO
+   includes/message_handler.php
+   └─> Valida datos
+   └─> Inserta en tabla 'messages'
+   └─> Inserta en tabla 'schedules'
+   └─> Si 'enviar ahora' → ejecuta process_queue.php
+
+3. COLA DE PROCESAMIENTO (cron cada minuto)
+   process_queue.php
+   └─> Busca schedules pending con send_time <= ahora
+   └─> Marca como 'processing'
+   └─> Convierte HTML → Formato plataforma
+   └─> Envía vía DiscordSender o TelegramSender
+   └─> Registra en 'sent_messages'
+   └─> Si recurrente → calcula próximo envío
+   └─> Marca 'sent' o 'failed'
+
+4. TRADUCCIÓN (opcional)
+   a) Automática: Se encola en translation_queue
+      └─> process_translation_queue.php
+      
+   b) Manual: Botones en mensaje enviado
+      └─> Usuario hace clic → traduce solo ese idioma
+
+5. RESULTADO
+   └─> Usuario puede ver en:
+       - scheduled_messages.php (pendientes)
+       - sent_messages.php (enviados)
+```
+
+---
+
+## 16. Resumen de Rutas del Menú
+
+```
+├── INICIO (index.php)
+│   └── Dashboard con mensajes programados
+│
+├── MENSAJES
+│   ├── Crear Mensaje (create_message.php)
+│   ├── Programados (scheduled_messages.php)
+│   ├── Plantillas (recurrentes.php)
+│   └── Enviados (sent_messages.php)
+│
+├── GALERÍA (gallery.php)
+│
+├── ADMIN (solo admins)
+│   ├── Usuarios (admin/users.php)
+│   ├── Destinatarios (admin/recipients.php)
+│   ├── Idiomas (admin/languages.php)
+│   ├── Comandos (admin/comandos.php)
+│   ├── Telegram Config (telegram/admin/telegram_welcome.php)
+│   ├── Interacciones Bot (telegram/admin/telegram_bot_interactions.php)
+│   ├── Chat Telegram (telegram/admin/chat_telegram.php)
+│   ├── Actividad (admin/activity.php)
+│   └── Test (admin/test_discord_connection.php)
+│
+├── PERFIL (profile.php)
+└── CERRAR SESIÓN (logout.php)
+```
+
+---
+
+Este complemento junto con el documento principal `DOCUMENTACION_SISTEMA.md` proporcionan una visión completa del sistema.