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