128 lines
8.0 KiB
Markdown
Executable File
128 lines
8.0 KiB
Markdown
Executable File
# 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 --- |