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 ---
|
||||
128
requerimientos/telegram_project_spec.md
Executable file
128
requerimientos/telegram_project_spec.md
Executable file
@@ -0,0 +1,128 @@
|
||||
# Especificación del Proyecto Bot de Telegram
|
||||
|
||||
## 1. Introducción
|
||||
|
||||
Este documento detalla los requisitos y funcionalidades para el desarrollo de un proyecto independiente que gestione un bot de Telegram 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 Telegram, 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, protección de webhook.
|
||||
|
||||
## 3. Funcionalidades del Bot de Telegram (Backend)
|
||||
|
||||
El bot de Telegram debe ser implementado como un webhook que procesa las actualizaciones enviadas por la API de Telegram.
|
||||
|
||||
### 3.1. Manejo de Webhook y Seguridad
|
||||
|
||||
* **Endpoint:** Un único endpoint PHP (`telegram_bot_webhook.php`) que reciba todas las actualizaciones de Telegram.
|
||||
* **Autenticación:** El webhook debe estar protegido mediante un `auth_token` en la URL, que se validará contra una variable de entorno (`TELEGRAM_WEBHOOK_TOKEN`).
|
||||
* **Validación:** Decodificación y validación de las actualizaciones JSON entrantes.
|
||||
|
||||
### 3.2. Gestión de Usuarios y Modos de Chat
|
||||
|
||||
* **Registro Automático:**
|
||||
* Cuando un usuario inicia un chat privado con el bot por primera vez, debe ser registrado en la tabla `recipients` (ID de Telegram, nombre, `platform='telegram'`, `chat_mode='agent'`, `language_code`).
|
||||
* Cuando el bot es añadido a un grupo, los nuevos miembros del grupo deben ser registrados en `recipients`.
|
||||
* **Mensaje de Bienvenida (DM):** Al registrar un nuevo usuario en DM, se debe enviar un mensaje de bienvenida configurable (desde la base de datos) que puede incluir un botón con un enlace de invitación a un grupo.
|
||||
* **Modos de Interacción (en DM):**
|
||||
* **Modo `agent` (por defecto):** Presenta al usuario un menú con botones inline 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 inline 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:**
|
||||
* `/start`: Mensaje de bienvenida básico.
|
||||
* `/setlang <código_idioma>` o `/setlanguage <código_idioma>`: Permite al usuario establecer su idioma preferido (actualiza `recipients.language_code`).
|
||||
* `/bienvenida`: Envía el mensaje de bienvenida configurable.
|
||||
* `/comandos`: Lista todos los comandos `#` personalizados disponibles, con su descripción.
|
||||
* `/agente`: Resetea el modo de chat del usuario a `agent` y muestra el menú de selección.
|
||||
* **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 HTML compatible con Telegram.
|
||||
* El mensaje debe ser enviado al chat.
|
||||
* **Bloqueo de Comandos:** Implementar un mecanismo (`CommandLocker`) para evitar que el mismo comando sea procesado múltiples veces simultáneamente por el mismo chat.
|
||||
* **Botones de Traducción Dinámicos:** Después de enviar un comando `#`, el mensaje enviado debe ser editado para incluir botones inline 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 Inline):**
|
||||
* 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 una alerta (`answerCallbackQuery` con `show_alert`).
|
||||
* **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 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 HTML compatible con Telegram antes de ser enviados.
|
||||
|
||||
### 3.5. Integración con IA (N8N)
|
||||
|
||||
* **Webhook:** Cuando el usuario está en modo `ia`, los mensajes deben ser reenviados a un webhook externo (URL configurable en `.env`, ej. `N8N_IA_WEBHOOK_URL`).
|
||||
* **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 Telegram)
|
||||
|
||||
Se requiere una interfaz web completa para administrar el bot de Telegram. 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 Telegram.
|
||||
* Estadísticas relevantes (ej. número de usuarios de Telegram, 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 Telegram (ej. `#mi_comando`).
|
||||
* **Mensajes Programados:** Gestión de mensajes que se enviarán en fechas y horas específicas a usuarios o grupos de Telegram.
|
||||
* **Mensajes Recurrentes:** Configuración de mensajes que se envían periódicamente.
|
||||
|
||||
### 4.4. Gestión de Usuarios de Telegram
|
||||
|
||||
* Listado de todos los `recipients` de la plataforma `telegram`.
|
||||
* Posibilidad de ver/editar el `language_code` y `chat_mode` de los usuarios.
|
||||
* Posibilidad de enviar mensajes directos a usuarios específicos de Telegram 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 usuarios de Telegram (texto, botón, enlace de invitación, activación/desactivación del registro).
|
||||
* **Webhooks:** Interfaz para configurar y verificar el webhook de Telegram.
|
||||
|
||||
## 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/TelegramSender.php`:** Clase para interactuar con la API de Telegram.
|
||||
* **`src/HtmlToTelegramHtmlConverter.php`:** Clase para convertir HTML a formato Telegram.
|
||||
|
||||
## 6. Estructura de la Base de Datos (Relevante para Telegram)
|
||||
|
||||
Se espera que el proyecto utilice tablas similares a las identificadas en el análisis:
|
||||
|
||||
* `recipients`: Para usuarios de Telegram.
|
||||
* `recurrent_messages`: Para comandos `#` de Telegram.
|
||||
* `supported_languages`: Para idiomas activos.
|
||||
* `translation_queue`: Para mensajes de Telegram pendientes de traducción.
|
||||
* `telegram_bot_messages`: Para configuraciones específicas del bot de Telegram (ej. bienvenida).
|
||||
* `telegram_interactions`: Para registrar interacciones del bot de Telegram.
|
||||
* `activity_log`: Para registrar actividades de la interfaz web.
|
||||
|
||||
--- End of content ---
|
||||
Reference in New Issue
Block a user