nickpons666/lastwar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
lastwar/DOCUMENTACION_COMPLEMENTO.md

14 KiB
Executable File
Raw Permalink 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:

  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

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

Reference in New Issue View Git Blame Copy Permalink