# Checklist: configurar Telegram en la VM

Todo lo que hay que revisar/configurar en el servidor para que las notificaciones
de Telegram funcionen. Para entender *cómo* funciona el sistema (triggers, cola,
mantenimiento anual), ver [`telegram-notificaciones.md`](telegram-notificaciones.md) —
este documento es solo el checklist de puesta en marcha.

## 1. Requisitos del servidor

- [ ] **Extensión `curl` de PHP habilitada** — `php -m | grep curl`. Es nueva para
      este repo (antes no se usaba); si no aparece, instalar `php-curl` (o el
      paquete equivalente de la distro) y reiniciar PHP-FPM/Apache.
- [ ] **Extensión `openssl` habilitada** — `php -m | grep openssl` (ya la usa
      `encriptar()`/`desencriptar()` en `core/funciones.php`, debería estar).
- [ ] **Dominio con HTTPS válido** apuntando a la VM (Telegram *rechaza* webhooks
      sin TLS válido — no sirve un certificado autofirmado). Let's Encrypt está bien.
- [ ] **Acceso a cron** (`crontab -e` o el equivalente) para programar el envío.
- [ ] **Salida a internet habilitada** desde la VM hacia `api.telegram.org` en el
      puerto 443 (si hay firewall saliente restrictivo, agregar la excepción).

## 2. Variables de entorno (`.env`)

- [ ] `PORTAL_URL` debe ser el dominio público real con HTTPS, ej.:
      ```
      PORTAL_URL=https://micolegio.jesistemas.com.ve
      ```
      (`telegram-set-webhook.php` arma la URL del webhook a partir de esta
      constante — si queda en `http://` o en un dominio no público, Telegram
      rechaza el registro).

## 3. Código desplegado

- [ ] `core/telegram.php`
- [ ] `telegram-webhook.php`
- [ ] `telegram-set-webhook.php`
- [ ] `telegram-enviar-notificaciones.php`
- [ ] `admin_alumnos/layout/base.php` (banner)
- [ ] `db/colegios/colegiojuanxxiii-telegram.sql`

No se agregó ninguna dependencia nueva de Composer — no hace falta `composer install`.

## 4. Migración de base de datos

- [ ] Aplicar contra la BD del colegio (**una vez**, no se reaplica):
      ```
      mysql -u root jesistem_juanxxiii < db/colegios/colegiojuanxxiii-telegram.sql
      ```
- [ ] Verificar que quedó aplicada:
      ```sql
      SHOW COLUMNS FROM represe LIKE 'telegram_chat_id';
      SHOW TABLES LIKE 'notif_telegram_queue';
      SHOW TRIGGERS WHERE `Trigger` LIKE 'trg_%_notif';
      ```
      Deben aparecer: la columna, la tabla, y `trg_evalua_calendario_notif` +
      `trg_cortes2627_notif`.

## 5. Constantes institucionales

En `panel_admin` → colegio (id 11, jesistem_juanxxiii) → **Constantes institucionales**:

- [ ] `TELEGRAM_BOT_TOKEN` — el token de @BotFather.
- [ ] `TELEGRAM_BOT_NAME` — el username del bot **sin** `@` (ej. `ColegioJuanXXIIIBot`).

No cargar `TELEGRAM_WEBHOOK_SECRET` a mano: se genera solo en el paso 6 (si igual se
cargó a mano, el paso 6 lo reemplaza por uno válido).

## 6. Registrar el webhook

- [ ] Con el botón **"Registrar webhook en Telegram"** en `panel_admin` → colegio →
      tarjeta *Notificaciones Telegram*; o por CLI:
      ```
      php telegram-set-webhook.php 11
      ```
- [ ] La respuesta debe ser `{"ok":true,"result":true,"description":"Webhook was set"}`
      (por el botón: `✓ Webhook was set`).
      Si sale `false`, ver la sección de errores comunes más abajo.
- [ ] Confirmar que quedó registrado correctamente:
      ```
      curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"
      ```
      Revisar que `"url"` sea `https://<tu-dominio>/telegram-webhook.php?colegio=11`
      y que `"last_error_message"` no tenga nada reciente.

## 7. Cron de envío

- [ ] Agregar (una sola entrada cubre **todos** los colegios que tengan
      `TELEGRAM_BOT_TOKEN` configurado, no solo el 11):
      ```
      */10 * * * * php /ruta/al/repo/telegram-enviar-notificaciones.php >> /ruta/al/repo/logs/telegram.log 2>&1
      ```
- [ ] Crear la carpeta `logs/` si no existe y confirmar que el usuario del cron
      tiene permiso de escritura ahí.
- [ ] Correrlo una vez a mano para confirmar que no tira errores:
      ```
      php telegram-enviar-notificaciones.php
      ```

## 8. Prueba end-to-end

- [ ] Entrar al portal como un alumno cuyo representante no esté vinculado
      (`represe.telegram_chat_id IS NULL`) → debe verse el banner.
- [ ] Presionar "Vincular ahora" → abre Telegram → presionar "Iniciar".
- [ ] Confirmar el mensaje de bienvenida del bot.
- [ ] Recargar el portal → el banner debe desaparecer.
- [ ] Generar un evento real (una evaluación o una nota cargada para ese alumno)
      y esperar al siguiente ciclo de cron (o correrlo a mano) → debe llegar la
      notificación a Telegram.

## Errores comunes

| Síntoma | Causa probable |
|---|---|
| `setWebhook` responde `"HTTPS url must be provided"` | `PORTAL_URL` no es HTTPS, o el certificado no es válido para la CA de Telegram. |
| `setWebhook` responde `ok:true` pero nunca llegan updates | Revisar `getWebhookInfo` → `last_error_message`. Frecuente: el firewall bloquea la IP de Telegram, o el vhost no enruta `/telegram-webhook.php` (revisar `.htaccess`/reglas de reescritura). |
| El banner no aparece nunca | `TELEGRAM_BOT_TOKEN`/`TELEGRAM_BOT_NAME` no están en Constantes institucionales, o el alumno no tiene `ced_rep` válido en `alumcer`. |
| El banner aparece pero el botón no vincula | El webhook no está registrado (paso 6) o el secreto no coincide — revisar logs de `telegram-webhook.php` (agregar temporalmente un `error_log()` si hace falta). |
| Se genera la evaluación/nota pero nunca llega el mensaje | El representante nunca se vinculó (`telegram_chat_id IS NULL` → el trigger no encola nada a propósito) o el cron no está corriendo. |
| El cron manda notificaciones pero MySQL no tiene privilegio para crear el trigger | Confirmar que el usuario de `mysql -u root` (o el que uses) tiene `CREATE TRIGGER` en `jesistem_juanxxiii`. |