sistema_funcionando_lastwar/requerimientos/discord_project_spec.md

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