# Especificación del Proyecto Bot de Discord

## 1. Introducción

Este documento detalla los requisitos y funcionalidades para el desarrollo de un proyecto independiente que gestione un bot de Discord y su interfaz web asociada. El objetivo es crear una aplicación autónoma que permita la administración y operación de un bot de Discord, incluyendo la programación de mensajes, gestión de usuarios y funcionalidades avanzadas de interacción y traducción.

## 2. Requisitos Generales

*   **Lenguaje:** PHP (versión compatible con las librerías).
*   **Base de Datos:** MySQL/MariaDB.
*   **Gestor de Dependencias:** Composer.
*   **Variables de Entorno:** Uso de archivos `.env` para configuración sensible (tokens, credenciales DB, URLs de webhooks).
*   **Logging:** Implementación de un sistema de logging robusto (ej. Monolog).
*   **Seguridad:** Protección contra CSRF en la web, validación de entradas.

## 3. Funcionalidades del Bot de Discord (Backend)

El bot de Discord debe ser una aplicación PHP que se conecta a la API de Discord y escucha eventos.

### 3.1. Conexión y Eventos

*   **Librería:** Uso de `discord-php/DiscordPHP` para la interacción con la API de Discord.
*   **Token:** Conexión mediante `DISCORD_BOT_TOKEN` (variable de entorno).
*   **Intents:** Configuración de `Intents` necesarios (ej. `GUILDS`, `GUILD_MESSAGES`, `DIRECT_MESSAGES`, `GUILD_MEMBERS`, `GUILD_MESSAGE_REACTIONS`).
*   **Eventos Escuchados:**
    *   `ready`: Confirmación de conexión y logging.
    *   `GUILD_MEMBER_ADD`: Para registrar nuevos miembros.
    *   `INTERACTION_CREATE`: Para manejar interacciones de botones.
    *   `MESSAGE_CREATE`: Para procesar mensajes entrantes.

### 3.2. Gestión de Usuarios y Modos de Chat

*   **Registro Automático:**
    *   Cuando un nuevo miembro se une a un servidor, el bot debe registrarlo o actualizarlo en la tabla `recipients` (ID de Discord, nombre, `platform='discord'`, `language_code`).
*   **Modos de Interacción (en DM):**
    *   **Modo `agent` (por defecto para nuevos DM):** Presenta al usuario un menú con botones para elegir entre "Platicar con bot" o "Usar IA".
    *   **Modo `bot`:** El bot procesa los mensajes como comandos normales.
    *   **Modo `ia`:** Todos los mensajes del usuario son reenviados a un servicio de IA externo.
*   **Cambio de Modo:** Los usuarios deben poder cambiar de modo mediante botones o el comando `/agente` (que los devuelve al modo `agent`).
*   **Persistencia:** El `chat_mode` del usuario debe almacenarse en la tabla `recipients`.

### 3.3. Comandos y Mensajes

*   **Comandos Estándar:**
    *   `!ping`: Comando de prueba simple que responde "pong!".
    *   `/setlang <código_idioma>`: Permite al usuario establecer su idioma preferido (actualiza `recipients.language_code`).
    *   `/bienvenida`: Envía un mensaje de bienvenida configurable (desde la base de datos) con un botón de enlace.
    *   `/comandos`: Lista todos los comandos `#` personalizados disponibles, con su descripción.
    *   `/agente <prompt>`: Envía un prompt específico al agente de IA a través de N8N, similar al modo `ia` pero como un comando único.
*   **Comandos Personalizados (`#<comando>`):**
    *   El bot debe buscar el `<comando>` en la tabla `recurrent_messages`.
    *   Si se encuentra, el `message_content` (HTML) debe ser convertido a Markdown compatible con Discord.
    *   El mensaje debe ser enviado al chat.
    *   **Botones de Traducción Dinámicos:** Después de enviar un comando `#`, el mensaje enviado debe ser editado para incluir botones que permitan la traducción manual a otros idiomas activos.

### 3.4. Funcionalidades de Traducción

*   **Detección de Idioma:** Capacidad para detectar el idioma de los mensajes entrantes.
*   **Traducción Manual (Botones):**
    *   Los botones de traducción dinámica deben permitir al usuario solicitar una traducción de un mensaje específico a un idioma.
    *   La traducción debe mostrarse como un mensaje efímero o una respuesta directa.
*   **Traducción Automática (Mensajes Regulares):**
    *   Los mensajes de texto que no son comandos deben ser encolados en la tabla `translation_queue` para ser traducidos automáticamente a todos los idiomas activos (excepto el idioma detectado).
    *   Se asume un proceso externo (`process_translation_queue.php`) que consumirá esta cola.
*   **Conversión HTML:** Los contenidos HTML almacenados en la base de datos deben ser convertidos a Markdown compatible con Discord antes de ser enviados.

### 3.5. Integración con IA (N8N)

*   **Webhook:** Cuando el usuario está en modo `ia` o usa el comando `/agente`, los mensajes deben ser reenviados a un webhook externo (URL configurable en `.env`, ej. `N8N_IA_WEBHOOK_URL_DISCORD`).
*   **Datos Enviados:** El webhook debe recibir `chat_id`, `user_id`, `message` y `name` del usuario.

## 4. Interfaz Web (para la Gestión del Bot de Discord)

Se requiere una interfaz web completa para administrar el bot de Discord. Esta interfaz debe ser una aplicación PHP independiente.

### 4.1. Autenticación y Seguridad

*   Sistema de login/logout para usuarios administradores.
*   Protección CSRF en formularios.
*   Gestión de sesiones.

### 4.2. Dashboard

*   Vista general de la actividad del bot de Discord.
*   Estadísticas relevantes (ej. número de usuarios de Discord, mensajes enviados).

### 4.3. Gestión de Mensajes

*   **Creación/Edición de Mensajes:** Interfaz para crear y editar mensajes que se usarán como respuestas a comandos `#`.
    *   Editor HTML para el contenido del mensaje.
    *   Asociación con un comando de Discord (ej. `#mi_comando`).
*   **Mensajes Programados:** Gestión de mensajes que se enviarán en fechas y horas específicas a usuarios o canales de Discord.
*   **Mensajes Recurrentes:** Configuración de mensajes que se envían periódicamente.

### 4.4. Gestión de Usuarios de Discord

*   Listado de todos los `recipients` de la plataforma `discord`.
*   Posibilidad de ver/editar el `language_code` y `chat_mode` de los usuarios.
*   Posibilidad de enviar mensajes directos a usuarios específicos de Discord desde la web.

### 4.5. Configuración del Bot

*   **Idiomas Soportados:** Gestión de los idiomas activos (`supported_languages`), incluyendo código, nombre y emoji de bandera.
*   **Mensaje de Bienvenida:** Configuración del mensaje de bienvenida para nuevos miembros del servidor (texto, botón, enlace de invitación, activación/desactivación).
*   **Conexión:** Interfaz para verificar la conexión del bot de Discord.

## 5. Componentes Técnicos Compartidos

Aunque el proyecto será independiente, se espera que utilice o replique la lógica de los siguientes componentes del proyecto original:

*   **`config/config.php`:** Para cargar variables de entorno y configuraciones.
*   **`includes/db.php`:** Clase para la conexión a la base de datos (PDO Singleton).
*   **`src/Translate.php`:** Clase para la detección y traducción de idiomas.
*   **`src/CommandLocker.php`:** Clase para el bloqueo de comandos.
*   **`src/DiscordSender.php`:** Clase para interactuar con la API de Discord.
*   **`src/HtmlToDiscordMarkdownConverter.php`:** Clase para convertir HTML a formato Markdown de Discord.

## 6. Estructura de la Base de Datos (Relevante para Discord)

Se espera que el proyecto utilice tablas similares a las identificadas en el análisis:

*   `recipients`: Para usuarios de Discord.
*   `recurrent_messages`: Para comandos `#` de Discord.
*   `supported_languages`: Para idiomas activos.
*   `translation_queue`: Para mensajes de Discord pendientes de traducción.
*   `telegram_bot_messages`: (Nota: esta tabla podría necesitar ser renombrada o generalizada a `bot_messages` si contiene configuraciones para ambos bots, o se crearía una `discord_bot_messages` específica).
*   `telegram_interactions`: (Nota: esta tabla podría necesitar ser renombrada o generalizada a `bot_interactions` si contiene interacciones para ambos bots, o se crearía una `discord_interactions` específica).
*   `activity_log`: Para registrar actividades de la interfaz web.

--- End of content ---