Commit inicial con archivos existentes
This commit is contained in:
130
requerimientos/discord_project_spec.md
Executable file
130
requerimientos/discord_project_spec.md
Executable file
@@ -0,0 +1,130 @@
|
||||
# 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 ---
|
||||
Reference in New Issue
Block a user