QuebecRoundBot - Resumen del Proyecto

Descripción General

QuebecBot es un bot automatizado de Telegram diseñado para monitorear y notificar sobre las rondas de invitación del Programa de Inmigración de Quebec, así como proporcionar noticias relevantes sobre la provincia mediante feeds RSS.

Problema que Resuelve

El proyecto aborda las siguientes necesidades:

Monitoreo Manual Tedioso: Elimina la necesidad de revisar constantemente el sitio web oficial del gobierno de Quebec para conocer nuevas rondas de invitación del programa de inmigración.
Información Centralizada: Consolida información de múltiples fuentes RSS sobre Quebec en un único canal de Telegram, facilitando el acceso a noticias relevantes.
Notificaciones en Tiempo Real: Proporciona alertas automáticas cuando se publican nuevas invitaciones o noticias, permitiendo a los usuarios estar informados sin esfuerzo activo.
Accesibilidad: Ofrece la información de manera estructurada y formateada en Telegram, una plataforma familiar y accesible para la mayoría de los usuarios.

Funcionalidades Principales

1. Bot Interactivo de Telegram

Responde a comandos de usuarios en chats privados
Comando principal: "quebec round" - obtiene y muestra las últimas rondas de invitación

2. Web Scraping de Invitaciones

Utiliza Puppeteer para descargar páginas web del gobierno de Quebec
Extrae información detallada de las rondas de invitación:
- Fecha de la invitación
- Volet (categoría del programa)
- Número de invitaciones emitidas
- Puntos mínimos requeridos
- Criterios específicos de elegibilidad
Parsea fechas en formato francés y las convierte a formato ISO

3. Sistema de Notificaciones Automáticas

Detecta nuevas invitaciones comparando con la base de datos MongoDB
Envía mensajes formateados al canal de Telegram solo para invitaciones nuevas
Previene duplicados mediante verificación de existencia en la base de datos

4. Agregador de Noticias RSS

Obtiene noticias de múltiples fuentes RSS configurables:
- Quebec News RSS
- Estrie News RSS
Verifica si las noticias ya fueron enviadas antes de publicarlas
Implementa timeout de 30 segundos entre mensajes para evitar spam detection de Telegram

5. Persistencia de Datos

Almacena invitaciones en MongoDB con schema estructurado:
- Volet, fecha, puntos, número de invitaciones, criterios
Almacena noticias RSS para evitar duplicados:
- GUID, título, link, fecha de publicación

6. Automatización vía Cron

Script update.sh ejecutable mediante cron jobs
Actualiza automáticamente:
- Rondas de invitación (npm run updateRounds)
- Noticias RSS (npm run updateRSSNews)
Registra todas las operaciones en logs/cron.log con timestamps

Tecnologías Utilizadas

Backend y Runtime

Node.js (v22.18.0): Entorno de ejecución JavaScript
TypeScript: Superset de JavaScript con tipado estático para mayor robustez

Librerías Principales

node-telegram-bot-api (v0.63.0): API para interactuar con Telegram
Puppeteer (v21.3.8): Automatización de navegador para web scraping
Cheerio (v1.0.0-rc.12): Parser HTML tipo jQuery para Node.js
rss-parser (v3.13.0): Parser de feeds RSS/Atom
Mongoose (v8.18.0): ODM (Object Data Modeling) para MongoDB

Utilidades

dotenv (v17.2.2): Gestión de variables de entorno
ts-node (v10.9.2): Ejecución directa de TypeScript sin compilación previa

Base de Datos

MongoDB: Base de datos NoSQL para almacenar invitaciones y noticias

DevOps

Cron: Scheduler de Linux para ejecución automática periódica
Bash: Scripts de automatización

Arquitectura del Proyecto

QuebecRoundBot/
├── src/
│   ├── index.ts                  # Bot principal de Telegram
│   ├── updateRounds.ts           # Script para actualizar invitaciones
│   ├── postMessageTelegram.ts    # Módulo de envío de mensajes
│   ├── sendAllInvitations.ts     # Envío masivo de invitaciones
│   ├── models/
│   │   ├── Invitations.ts        # Schema de invitaciones
│   │   └── rssNews.ts            # Schema de noticias RSS
│   ├── rssNewsQuebec/
│   │   └── rssQuebec.ts          # Procesador de feeds RSS
│   ├── scrapper/
│   │   ├── scrapper.ts           # Lógica principal de scraping
│   │   ├── getHtml.ts            # Descarga de HTML con Puppeteer
│   │   ├── formatter.ts          # Formateo de mensajes
│   │   └── helper.ts             # Funciones auxiliares
│   └── lib/
│       └── mongo.ts              # Conexión a MongoDB
├── logs/
│   └── cron.log                  # Log de ejecuciones automáticas
├── update.sh                     # Script de actualización cron
├── expanded_page.html            # HTML descargado para parsing
└── package.json                  # Configuración del proyecto

Flujo de Trabajo

Actualización de Invitaciones

Puppeteer descarga la página web oficial (getHtml.ts)
Guarda el HTML en expanded_page.html
Cheerio parsea el HTML y extrae datos estructurados (scrapper.ts)
Compara con la base de datos MongoDB para detectar nuevas invitaciones
Inserta solo las nuevas invitaciones en MongoDB
Envía notificación formateada al canal de Telegram

Actualización de Noticias RSS

Parsea múltiples feeds RSS configurados
Itera sobre cada item del feed
Verifica si el GUID ya existe en MongoDB
Si es nueva, la inserta en MongoDB
Envía la noticia formateada al canal de Telegram
Espera 30 segundos antes del siguiente mensaje

Usabilidad

Para Usuarios Finales

Fácil Acceso: Solo necesitan Telegram, una app que probablemente ya usan
Comandos Simples: Texto en lenguaje natural (“quebec round”)
Notificaciones Pasivas: Reciben información sin tener que pedirla
Información Estructurada: Mensajes bien formateados con emojis para mejor legibilidad
Multilingüe: Interfaz en español, datos en francés (idioma oficial de Quebec)

Casos de Uso Típicos

Candidato a Inmigración: Recibe alertas automáticas cuando hay nuevas rondas de invitación, permitiéndole evaluar si cumple con los criterios sin revisar manualmente el sitio oficial.
Consultor de Inmigración: Mantiene a sus clientes informados sobre las últimas rondas y puede analizar tendencias en los puntos mínimos requeridos.
Comunidad de Inmigrantes: Canal de Telegram compartido donde todos los miembros reciben actualizaciones simultáneas sobre inmigración y noticias de Quebec.
Investigador: Puede analizar datos históricos de invitaciones almacenados en MongoDB para estudiar patrones y tendencias del programa de inmigración.

Última actualización: 14 de octubre de 2025 Versión: 1.0.0 Mantenedor: @datanarch