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