# Guía de instalación — Telegram multi-tenant evasoftpro
## Una sola instalación, funciona para todos los colegios

---

## ESTRUCTURA DE ARCHIVOS

Crea una carpeta `telegram/` dentro de tu plataforma:

```
tu_plataforma/
├── conexion/
│   ├── conexion.php
│   └── conexion_usuarios.php
├── telegram/                      ← carpeta nueva
│   ├── TelegramBot.php
│   ├── notificar_falta.php
│   └── webhook_registro.php       ← debe ser accesible por URL pública
└── modulos/
    └── asistencia/
        └── guardar_falta.php      ← aquí agregas 1 línea
```

---

## POR CADA COLEGIO NUEVO (10 minutos)

### Paso 1 — Crear el bot en Telegram

1. Abre Telegram → busca **@BotFather** → escribe `/newbot`
2. Nombre del bot: `Colegio San José Notificaciones` (el nombre del colegio)
3. Username: `colegiosanjose_notif_bot` (debe terminar en `bot`)
4. Copia el **token** que te da BotFather

### Paso 2 — Ejecutar la migración en la BD del colegio

En phpMyAdmin, selecciona la BD `evasoftpro_2026_CODIGO` y ejecuta `migracion.sql`.

Solo son 2 cosas: agrega el campo `telegram_chat_id` a `matricula` y crea la tabla `configuracion_telegram`.

Luego actualiza el token en esa misma BD:
```sql
INSERT INTO configuracion_telegram (bot_token, bot_username)
VALUES ('TOKEN_DEL_BOT_AQUI', 'colegiosanjose_notif_bot');
```

### Paso 3 — Registrar el webhook del colegio

Abre esta URL en el navegador (reemplaza TOKEN y CODIGO):
```
https://api.telegram.org/botTOKEN_DEL_COLEGIO/setWebhook?url=https://tusitio.com/telegram/webhook_registro.php?c=CODIGO_COLEGIO
```

Ejemplo real para colegio con código `SJB`:
```
https://api.telegram.org/bot1234567890:ABC.../setWebhook?url=https://evasoftpro.com/telegram/webhook_registro.php?c=SJB
```

Debes ver: `{"ok":true,"description":"Webhook was set"}`

✅ Listo. El colegio ya está configurado.

---

## INTEGRACIÓN EN EL FORMULARIO DE ASISTENCIA

Busca el archivo PHP donde haces el INSERT en `asistencia_dX` y agrega estas líneas:

```php
// ── Al inicio del archivo ──────────────────────────────────────
require_once '../telegram/notificar_falta.php';

// ── Tu INSERT existente (no lo tocas) ─────────────────────────
$sql = "INSERT INTO asistencia_d{$periodo}
        (codigo, idmatricula, idcurso, tipo_falta, fecha_hora, observacion, fecha, mes)
        VALUES (?, ?, ?, ?, NOW(), ?, CURDATE(), MONTH(NOW()))";
$stmt = $pdo->prepare($sql);
$stmt->execute([$codigo, $idmatricula, $idcurso, $tipo_falta, $observacion]);

// ── Agregar SOLO esta línea después del execute ────────────────
notificarFaltaTelegram($pdo, (int)$idmatricula, (int)$periodo, date('Y-m-d'), $tipo_falta, $observacion ?? '');
```

El `$pdo` ya está disponible porque viene de `conexion.php`.
El token del bot lo lee solo desde la BD del colegio activo.
No tienes que pasar el código del colegio ni ningún otro parámetro extra.

---

## CÓMO SE REGISTRAN LOS PADRES

Genera el enlace de cada estudiante con su `idmatricula`:

```
https://t.me/NOMBRE_DEL_BOT?start=IDMATRICULA
```

Ejemplo: `https://t.me/colegiosanjose_notif_bot?start=1042`

**Puedes automatizar esto** generando una página en la plataforma que muestre el enlace
o el QR a cada acudiente cuando inicia sesión en el portal de padres.

El padre:
1. Toca el enlace → se abre Telegram
2. Presiona el botón START
3. Recibe confirmación con el nombre de su hijo(a)
4. Listo — ya recibirá todas las notificaciones

---

## AGREGAR UN COLEGIO NUEVO EN EL FUTURO

1. Crear el bot en @BotFather (3 min)
2. Ejecutar migracion.sql en su BD + insertar el token (2 min)
3. Registrar el webhook con su código (1 min)
4. Compartir los enlaces a los padres (el colegio lo hace)

**Total: menos de 10 minutos por colegio.**
El archivo `webhook_registro.php` ya maneja todos — no hay que duplicar nada.

---

## VERIFICAR QUE FUNCIONA

```sql
-- Ver padres registrados en un colegio específico
SELECT
    idmatricula,
    CONCAT(nombres, ' ', apellidos) AS estudiante,
    curso,
    nombre_acudi,
    CASE WHEN telegram_chat_id IS NOT NULL THEN 'Registrado' ELSE 'Pendiente' END AS telegram
FROM matricula
ORDER BY curso, apellidos;
```

---

## MENSAJES QUE RECIBEN LOS PADRES

**Falta por INASISTE:**
```
⚠️ Ausencia registrada

Su hijo(a) Juan Pérez no asistió a clases hoy.

📅 Fecha: 23/03/2026
🏫 Curso: 8°A
📝 Observación: Sin justificación

Si tiene alguna inquietud, comuníquese con el colegio.
```

**Falta por LLEGA TARDE:**
```
🕐 Llegada tarde registrada

Su hijo(a) Juan Pérez llegó tarde a clases hoy.

📅 Fecha: 23/03/2026
🏫 Curso: 8°A

Si tiene alguna inquietud, comuníquese con el colegio.
```
