Files

nickpons666 38a8447a64 Initial commit - Last War messaging system

2026-02-19 01:33:28 -06:00

14 KiB

Executable File

Raw Blame History

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:

Detecta el idioma del mensaje
Traduce a todos los idiomas activos configurados
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

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

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

14 KiB Executable File Raw Blame History