telegram_new_socias/Readme.md

🤖 Vanessa Bot – Asistente de RH para Vanity

Vanessa es un bot de Telegram escrito en Python que automatiza procesos internos de Recursos Humanos en Vanity. Su objetivo es eliminar fricción operativa: onboarding, solicitudes de RH e impresión de documentos, todo orquestado desde Telegram y conectado a flujos de n8n.

Este repositorio está pensado como proyecto Python profesional, modular y listo para correr 24/7 en producción.

---

🧠 ¿Qué hace Vanessa?

Vanessa no es un chatbot genérico: es una interfaz conversacional para procesos reales de negocio.

• Onboarding completo de nuevas socias (/welcome)
• Envío de archivos a impresión (/print)
• Solicitud de vacaciones (/vacaciones)
• Solicitud de permisos por horas (/permiso)

Cada flujo es un módulo independiente y todos los datos se envían a webhooks de n8n para su procesamiento posterior.

---

📂 Estructura del Proyecto

vanity_bot/
│
├── .env                  # Variables sensibles (tokens, URLs)
├── main.py               # Cerebro principal del bot
├── requirements.txt      # Dependencias
├── Dockerfile            # Definición del contenedor del bot
├── docker-compose.yml    # Orquestación de servicios (bot + db)
├── README.md             # Este documento
│
└── modules/              # Habilidades del bot
    ├── __init__.py
    ├── database.py       # Módulo de conexión a la base de datos
    ├── onboarding.py     # Flujo /welcome (onboarding RH)
    ├── printer.py        # Flujo /print (impresión)
    └── rh_requests.py    # /vacaciones y /permiso

---

🔐 Configuración (.env)

Crea un archivo .env en la raíz del proyecto con el siguiente contenido:

# --- TELEGRAM ---
TELEGRAM_TOKEN=TU_TOKEN_AQUI

# --- WEBHOOKS N8N ---
WEBHOOK_ONBOARDING=https://flows.soul23.cloud/webhook/contrato
WEBHOOK_PRINT=https://flows.soul23.cloud/webhook/impresion
WEBHOOK_VACACIONES=https://flows.soul23.cloud/webhook/vacaciones

# --- DATABASE ---
# Esta URL es para la conexión interna de Docker, no la modifiques si usas Docker Compose.
DATABASE_URL=mysql+mysqlconnector://user:password@db:3306/vanessa_logs

Nunca subas este archivo al repositorio.

---

🐳 Ejecución con Docker (Recomendado)

El proyecto está dockerizado para facilitar su despliegue.

1. Pre-requisitos

• Docker
• Docker Compose

2. Levantar los servicios

Con el archivo .env ya configurado, simplemente ejecuta:

docker-compose up --build

Este comando construirá la imagen del bot, descargará la imagen de MySQL, creará los volúmenes y redes, y lanzará ambos servicios. El bot se conectará automáticamente a la base de datos para registrar los logs.

3. Detener los servicios

Para detener los contenedores, presiona Ctrl+C en la terminal donde se están ejecutando, o ejecuta desde otro terminal:

docker-compose down

---

📦 Instalación Manual

Se recomienda usar un entorno virtual.

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

▶️ Ejecución Manual

python main.py

Si el token es válido, verás:

🧠 Vanessa Brain iniciada y escuchando...

Nota: Para que la ejecución manual funcione, necesitarás tener una base de datos MySQL corriendo localmente y accesible en la URL especificada en DATABASE_URL dentro de tu archivo .env.

---

🧩 Arquitectura Interna

main.py (El Cerebro)

• Inicializa el bot de Telegram
• Carga variables de entorno
• Registra los handlers de cada módulo
• Define el menú principal (/start, /help)

modules/database.py

• Gestiona la conexión a la base de datos MySQL con SQLAlchemy.
• Define el modelo RequestLog para la tabla de logs.
• Provee la función log_request para registrar interacciones.

modules/onboarding.py

Flujo conversacional complejo basado en ConversationHandler.

• Recolecta información personal, laboral y de emergencia
• Normaliza datos (RFC, CURP, fechas)
• Usa teclados guiados para reducir errores
• Envía un payload estructurado a n8n

modules/printer.py

• Recibe documentos o imágenes desde Telegram
• Obtiene el enlace temporal de Telegram
• Envía el archivo a una cola de impresión vía webhook

modules/rh_requests.py

• Maneja solicitudes simples de RH: Vacaciones y Permisos por horas.

---

🧠 Filosofía del Proyecto

• Telegram como UI
• Python como cerebro
• n8n como sistema nervioso
• Docker para despliegue
• MySQL para persistencia de logs
• Datos estructurados, no mensajes sueltos
• Modularidad total: cada habilidad se enchufa o se quita

Vanessa no reemplaza RH: elimina fricción humana innecesaria.

---

🚀 Extensiones Futuras

• Firma digital de contratos
• Finder de documentos
• Reportes automáticos
• Roles y permisos
• Modo administrador

---

🧪 Estado del Proyecto

✔ Funcional en producción ✔ Modular ✔ Escalable ✔ Auditable

Vanessa está viva. Y aprende con cada flujo nuevo.