## Planificación de Documentación Técnica: Telegram Bot API para el Ecosistema Erando

### 1. Objetivo de la documentación
Proveer una referencia completa, práctica y orientada a desarrolladores sobre la **API de bots de Telegram** (`https://core.telegram.org/bots/api`), con foco en la construcción de un asistente conversacional avanzado como el que se implementa en el proyecto `herandro-services-api` (Erando Ecosystem V8, NestJS Edition).  
La documentación cubrirá desde los fundamentos de la API hasta su integración con la arquitectura del proyecto: autenticación por Keycloak, enrutamiento basado en webhooks, procesamiento asincrónico con BullMQ, persistencia en SurrealDB y manejo de contenido multimedia.  
El resultado final debe permitir a cualquier miembro del equipo desarrollar nuevas funcionalidades del bot, comprender los contratos de la API y mantener el sistema con confianza.

### 2. Audiencia y nivel técnico
- **Desarrolladores backend** que trabajan con NestJS y TypeScript.
- **Ingenieros DevOps** o **arquitectos** que configuran el webhook y las colas de mensajería.
- Familiaridad esperada:  
  - TypeScript avanzado (tipos genéricos, modelos de datos).  
  - NestJS (módulos, controladores, pipes, guards).  
  - Conceptos de APIs REST, JSON, webhooks.  
  - Conocimiento básico de Telegram (chats, bots, tokens) es deseable pero no obligatorio; se explicarán los conceptos clave.

### 3. Alcance y versiones
- **API de Telegram documentada**: Se tomará como base la versión disponible a la fecha de redacción (previsiblemente Bot API 7.x, lanzada en 2024). Se indicará explícitamente si algún *endpoint* o tipo ha sido añadido o modificado en versiones posteriores.  
- **Incluye**:
  - Todos los métodos de la API de bots relevantes para el proyecto (mensajes, multimedia, comandos, teclados, *inline queries*, gestión de grupos, webhooks).
  - Tipos de objetos de Telegram (User, Chat, Message, etc.) modelados en TypeScript.
  - Manejo de archivos, *upload* y *download*.
  - Errores comunes, códigos de estado HTTP, gestión de límites de tasa.
  - Integración con el stack Erando (Keycloak, NestJS, BullMQ, SurrealDB, CDN).
- **Excluye**:
  - API de pagos, juegos y otras funcionalidades que no forman parte del *scope* actual del asistente (se mencionarán brevemente si se considera necesario).
  - Detalles operativos de SurrealDB, Redis o Keycloak más allá de lo necesario para la integración con Telegram.

### 4. Estructura del documento
Se organizará en los siguientes capítulos, cada uno con su propósito:

1. **Introducción a la API de Telegram Bots**  
   - Qué es un bot, tokens, cómo interactúa con Telegram.  
   - Modelo de comunicación: métodos → respuestas, actualizaciones entrantes.

2. **Métodos disponibles (Reference)**  
   - Listado completo de métodos, agrupados por categoría:
     - Mensajes (sendMessage, editMessageText, deleteMessage, etc.)
     - Multimedia (sendPhoto, sendVideo, sendDocument, etc.)
     - Chats y grupos (getChat, getChatMember, setChatPermissions, etc.)
     - Comandos (setMyCommands, getMyCommands)
     - Inline mode (answerInlineQuery)
     - Webhooks (setWebhook, deleteWebhook, getWebhookInfo)
   - Cada método incluirá:
     - Descripción y parámetros obligatorios/opcionales.
     - Ejemplo de llamada con `curl`.
     - Modelo de respuesta en TypeScript.
     - Notas de uso específicas para el proyecto (p.ej., cómo manejar `chat_id` con enlaces de Telegram).

3. **Tipos de objetos de Telegram**  
   - Modelado completo en TypeScript de los objetos más utilizados:
     - `User`, `Chat`, `Message`, `Update`, `CallbackQuery`, `InlineQuery`, etc.
     - Esquemas para *inline keyboards*, *reply keyboards*, *force reply*, etc.
   - Se incluirán las definiciones como interfaces/type de TypeScript, listas para importar en el código del proyecto.

4. **Obtención de actualizaciones: Webhooks vs Long Polling**  
   - Fundamentos de los dos mecanismos.
   - Implementación recomendada para el ecosistema (webhook obligatorio por requisitos de Telegram y del proyecto).
   - Flujo de verificación del webhook con NestJS y `@nestjs/telegraf`.

5. **Manejo de archivos y multimedia**  
   - Cómo enviar/recibir archivos (fotos, documentos, vídeos, etc.).
   - Rutas de *upload* usando `multipart/form-data`.
   - Integración con el CDN de Erando: *download* y almacenamiento de archivos enviados por usuarios.

6. **Errores, códigos de estado HTTP y límites de tasa**  
   - Códigos de error comunes de la API de Telegram (400, 403, 429, etc.) y cómo interpretarlos.
   - Estrategias para respetar los límites de tasa (20 mensajes por minuto en grupos, etc.).
   - Manejo de reintentos y *backoff* en el contexto del asistente.

7. **Integración con el Ecosistema Erando (Capítulo específico del proyecto)**  
   - Flujo de autenticación: vinculación de usuarios de Keycloak con `telegram_id` mediante bot *login* (deep-linking).
   - Arquitectura de ingesta: el controlador webhook de NestJS enruta las actualizaciones a BullMQ.
   - Dispatcher de colas: separación en `default_messaging_queue` y `heavy_asset_queue`.
   - Ejemplo de implementación de un *handler* para un mensaje de texto y para un archivo multimedia, mostrando cómo se extraen los datos relevantes y se programan las tareas asíncronas.
   - Diagramas Mermaid del flujo de actualización completo.

8. **Apéndices**  
   - A. Colección completa de ejemplos `curl` para los métodos principales.
   - B. Tipos TypeScript exportables (archivos `.d.ts` o código fuente).
   - C. Tabla de códigos de estado HTTP y sus significados.
   - D. Referencia rápida de comandos de bot útiles durante el desarrollo.

### 5. Aspectos técnicos a investigar
La investigación se dividirá en dos frentes:

**Investigación web (fuentes oficiales y comunidad)**  
- Revisión exhaustiva de la documentación oficial de Telegram Bot API (métodos, tipos, límites, ejemplos).
- Buscar tutoriales o *best practices* para bots avanzados (manejo de *webhooks* escalables, persistencia de estado, medios asincrónicos).
- Validar la estructura de las respuestas reales de la API (usar Postman o curl contra un bot de prueba) para confirmar campos opcionales, tipos y comportamiento de errores.
- Comprobar la versión más reciente de la librería `@nestjs/telegraf` y su compatibilidad con NestJS 10/11.

**Síntesis de conocimiento interno del proyecto**  
- Analizar el código base existente (si lo hay) en `herandro-services-api` para identificar cómo se está utilizando `@nestjs/telegraf` y el enrutamiento de actualizaciones.
- Revisar el esquema de SurrealDB para entender cómo se almacenan los `telegram_id` y los tokens de usuario.
- Coordinar con el equipo para definir la manera exacta de mapear los tipos de Telegram a los modelos internos (por ejemplo, `Message` → `ConversationTurn`).

### 6. Convenciones
- **Formato de código**:  
  - Bloques `bash` para comandos `curl`.  
  - Bloques `typescript` para modelos y ejemplos de código.  
  - Se usarán variables de entorno (`{{BOT_TOKEN}}`, `{{CHAT_ID}}`) para los placeholders en los ejemplos.  
- **Notas y advertencias**:  
  - Se emplearán *callouts* (admoniciones) como `> **Importante**`, `> **Precaución**`, `> **Nota**` para resaltar información crítica.  
  - Los diagramas se redactarán en Mermaid con ` ```mermaid ... ``` `.  
- **Idioma**: Todo el contenido estará en español, salvo nombres técnicos de métodos, tipos o códigos de error que se conservarán en inglés.  
- **Referencias**: Se incluirán enlaces a la documentación oficial de Telegram cuando sea pertinente.

### 7. Entregable esperado
Un único documento (o conjunto de documentos interconectados) en formato Markdown, organizado según la estructura anterior. Incluirá:
- **Texto explicativo** claro y completo.
- **Listados de métodos** de la API con tablas de parámetros y ejemplos `curl`.
- **Fragmentos de código TypeScript** listos para copiar y pegar (modelos de datos, handlers, configuración de webhook).
- **Diagramas Mermaid** del flujo de actualización y de la integración con el stack Erando.
- **Apéndices** con referencias rápidas.
- Todo el contenido estará orientado a que cualquier desarrollador del ecosistema pueda consultarlo sin necesidad de mirar la documentación oficial de Telegram, a menos que requiera información muy específica.

---

**Nota para el redactor**: El plan está diseñado para que la documentación sea **autosuficiente** para el equipo, cubriendo tanto los conocimientos genéricos de la API como las particularidades del proyecto `herandro-services-api`. La redacción final deberá mantener un tono técnico, directo y sin opiniones personales, siguiendo las convenciones indicadas.