sistema_funcionando_lastwar/requerimientos/telegram_project_spec.md

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