# Bot de Telegram con FlightPHP

Bot webhook que conecta Telegram con una API de Google Apps Script (que lee/escribe en Google Sheets).

```
Telegram ─POST─> VPS Apache (FlightPHP) ─GET─> Google Apps Script API ─> Google Sheets
```

---

## Instalación

```bash
cd /var/www/bot-telegram
composer install
cp .env.example .env
nano .env          # Rellenar todos los valores
chmod 600 .env
```

---

## Configuración de Apache

Crea el virtual host en `/etc/apache2/sites-available/bot-telegram.conf`:

```apache
<VirtualHost *:80>
    ServerName tu-dominio.com
    DocumentRoot /var/www/bot-telegram/public

    <Directory /var/www/bot-telegram/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/bot-telegram-error.log
    CustomLog ${APACHE_LOG_DIR}/bot-telegram-access.log combined
</VirtualHost>
```

Activar y recargar:

```bash
sudo a2ensite bot-telegram
sudo a2enmod rewrite
sudo systemctl reload apache2
```

---

## HTTPS con Let's Encrypt

Telegram **requiere HTTPS** para webhooks.

```bash
sudo apt install certbot python3-certbot-apache -y
sudo certbot --apache -d tu-dominio.com
```

Certbot modifica el virtual host automáticamente y configura la renovación automática.

Verificar renovación:
```bash
sudo certbot renew --dry-run
```

---

## Registrar webhook en Telegram

```bash
# Pasar el dominio como argumento o definir APACHE_DOMAIN en .env
php scripts/setup_webhook.php tu-dominio.com

# Confirmar que quedó registrado
php scripts/webhook_info.php
```

---

## Probar todo

```bash
# 1. Verificar token de Telegram
php tests/test_telegram_token.php

# 2. Verificar API de Apps Script (5 pruebas)
php tests/test_appscript_api.php

# 3. Simular un mensaje local (requiere Apache corriendo)
php tests/test_simulate_message.php "/start"
php tests/test_simulate_message.php "/vincular octocat"
php tests/test_simulate_message.php "/mi_estado"
```

---

## Comandos disponibles del bot

| Comando | Descripción |
|---|---|
| `/start` o `/inicio` | Mensaje de bienvenida |
| `/vincular <usuario_github>` | Vincula tu Telegram con GitHub |
| `/mi_estado` o `/estado` | Muestra tu actividad en GitHub |
| `/ayuda` o `/help` | Ayuda |

---

## Estructura de logs

Los logs se escriben en `storage/logs/bot-YYYY-MM-DD.log`:

```
[2026-05-10 16:30:15] [INFO] [chat_id:123456] Mensaje recibido {"username":"octocat","texto":"/start"}
[2026-05-10 16:30:16] [WARN] [chat_id:-] Secret path inválido recibido {"path":"ruta-invalida"}
[2026-05-10 16:30:20] [ERROR] [chat_id:123456] Error fatal en BotHandler {"error":"..."}
```

Nivel de log configurable en `.env` con `LOG_LEVEL=debug|info|warn|error`.

---

## Troubleshooting

**Telegram dice "webhook failed"**
- Verifica que HTTPS esté activo y el certificado sea válido
- Revisa `php scripts/webhook_info.php` para ver el `last_error_message`
- Asegúrate de que el puerto 443 esté abierto en el firewall

**La API de Apps Script no responde**
- Verifica que la URL en `.env` no tenga espacios ni saltos de línea
- Asegúrate de que `allow_redirects => true` (Apps Script siempre redirige 302)
- Prueba la URL directamente en el navegador con los parámetros

**El bot no responde a los mensajes**
- Revisa los logs en `storage/logs/`
- Verifica permisos: `sudo chown -R www-data:www-data storage/`
- Comprueba que `WEBHOOK_SECRET_PATH` coincide entre `.env` y la URL registrada

**Error "Variable de entorno requerida no configurada"**
- Asegúrate de que `.env` tiene todos los campos llenos (sin espacios ni comillas extra)
- Verifica que PHP puede leer el archivo: `ls -la .env` debe mostrar `-rw-------`

**Composer install falla**
- Verifica PHP >= 8.1: `php --version`
- Instala extensiones necesarias: `sudo apt install php8.1-curl php8.1-mbstring php8.1-json`