🤖 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 y solicitudes de RH, todo orquestado desde Telegram y conectado a flujos de n8n, servicios de correo y bases de datos MySQL.

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 (/registro, alias /welcome): Recolecta datos, valida que no existan duplicados en la DB, y ejecuta un registro en dos fases. Debe completarse una vez para habilitar el resto de comandos.
1. Crea un usuario de acceso en la tabla USERS_ALMA.users para la autenticación del bot.
2. Crea un perfil de empleada completo en la tabla vanity_hr.data_empleadas, que es la tabla maestra de RRHH.
Definición de horario semanal (/horario): Captura guiada día a día que termina en un upsert por día dentro de vanity_hr.horario_empleadas y dispara un webhook operativo; sólo se habilita si ya estás registrada.
Solicitud de vacaciones (/vacaciones): Flujo dinámico para gestionar días de descanso, disponible sólo si tu telegram_id ya existe en la base vía /registro.
Solicitud de permisos por horas (/permiso): Incluye clasificación de motivos mediante IA (Gemini) y requiere que el onboarding haya terminado.

Cada flujo es un módulo independiente que interactúa con la base de datos y flujos de n8n.

📂 Estructura del Proyecto

vanity_bot/
│
├── .env                  # Variables sensibles (tokens, URLs, credenciales)
├── .env.example          # Archivo de ejemplo para variables de entorno
├── 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
│
├── models/               # Modelos de base de datos (SQLAlchemy)
│   ├── users_alma_models.py
│   ├── vanity_hr_models.py
│   └── vanity_attendance_models.py
│
├── conv-flows/           # Plantillas JSON de flujos declarativos (p. ej. horario.json)
└── modules/              # Habilidades del bot y utilidades
    ├── ai.py             # Clasificación de motivos con Gemini
    ├── database.py       # Conexión a DB y lógica de negocio (registro/verificación)
    ├── finalizer.py      # Acciones finales por flujo (webhooks + persistencia)
    ├── flow_builder.py   # Loader que convierte las plantillas JSON en ConversationHandlers
    ├── logger.py         # Registro de auditoría
    ├── onboarding.py     # Flujo /registro (/welcome)
    ├── rh_requests.py    # /vacaciones y /permiso
    └── ui.py             # Teclados y componentes de interfaz

🔐 Configuración (.env)

Vanessa utiliza múltiples bases de datos y webhooks. Asegúrate de configurar correctamente los nombres de las bases de datos.

# --- TELEGRAM ---
TELEGRAM_TOKEN=TU_TOKEN_AQUI

# --- AI (Gemini) ---
GOOGLE_API_KEY=AIzaSy...

# --- WEBHOOKS N8N ---
WEBHOOK_ONBOARDING=https://...
WEBHOOK_VACACIONES=https://...
WEBHOOK_PERMISOS=https://...
WEBHOOK_SCHEDULE=https://...

# --- DATABASE SETUP ---
MYSQL_HOST=db
MYSQL_USER=user
MYSQL_PASSWORD=password
MYSQL_ROOT_PASSWORD=rootpassword

# Nombres de las Bases de Datos
MYSQL_DATABASE_USERS_ALMA=USERS_ALMA
MYSQL_DATABASE_VANITY_HR=vanity_hr
MYSQL_DATABASE_VANITY_ATTENDANCE=vanity_attendance

🔄 Flujos declarativos

El bot puede registrar conversaciones complejas sin código específico gracias a:

conv-flows/*.json: Describe cada paso del flujo (texto, teclados, variables y transiciones). Actualmente horario.json define /horario.
modules/flow_builder.py: Lee los JSON y crea dinámicamente los ConversationHandler.
modules/finalizer.py: Ejecuta la acción final de cada flujo. Para /horario convierte las horas a formato 24 h, envía WEBHOOK_SCHEDULE y distribuye los registros por día en vanity_hr.horario_empleadas.

Si un flujo requiere lógica adicional, se agrega un finalizer nuevo y se anota en el map FINALIZATION_MAP.

🐳 Ejecución con Docker (Recomendado)

El proyecto está dockerizado para facilitar su despliegue y aislamiento.

1. Pre-requisitos

Docker y Docker Compose instalaros.

2. Levantar los servicios

docker-compose up --build -d

Este comando levantará el bot y un contenedor de MySQL (si se usa el compose por defecto). El bot se reconectará automáticamente a la DB si esta tarda en iniciar.

🧩 Arquitectura Interna

main.py (El Cerebro)

Inicializa el bot de Telegram y carga variables de entorno.
Registra los handlers de cada módulo y define el menú principal y comandos persistentes.

modules/database.py

Centraliza la conexión a las 3 bases de datos (USERS_ALMA, vanity_hr, vanity_attendance).
Verificación de duplicados: Verifica el telegram_id en USERS_ALMA.users para evitar registros duplicados.
Registro de usuarias: La función register_user implementa un registro en dos pasos:
1. Crea o actualiza el registro en USERS_ALMA.users para control de acceso.
2. Crea o actualiza el perfil completo de la empleada en vanity_hr.data_empleadas.

modules/onboarding.py

Recolección exhaustiva de datos. Al finalizar:

Valida y formatea datos (RFC, CURP, fechas).
Registra a la empleada en la base de datos MySQL.
Envía el payload completo al webhook de n8n para generación de contratos.

modules/ai.py & modules/rh_requests.py

Integración con Google Gemini para clasificar automáticamente los motivos de los permisos (Médico, Trámite, etc.) y envío sincronizado a webhooks de gestión humana.

🗒️ Registro de versiones

1.3 (2025-12-18) — Adiós Google Sheets: Migración total a base de datos MySQL para verificación de existencia y registro de nuevas socias. Limpieza de .env y optimización de arquitectura de modelos.
1.2 (2025-01-25) — Onboarding: selector de año 2020–2026; numero_empleado dinámico; mejoras en flujos de vacaciones/permiso.
1.1 — Implementación inicial de webhooks y Docker.

6.5 KiB Raw Blame History Unescape Escape