vanessa_bot_vanity/Readme.md

# Vanessa Bot - README Final

## Resumen del Proyecto
Vanessa Bot es un asistente virtual modular para Recursos Humanos en Vanity/Soul, construido con una arquitectura desacoplada. Temporalmente, el bot solo envía solicitudes vía webhooks a n8n sin esperar respuesta inmediata, enfocándonos en flujos conversacionales dinámicos. La DB está removida inicialmente, con roadmap para implementar persistencia externa o nativa.

## Nueva Estructura del Proyecto
- **main.py**: Orquestador puro que registra handlers y coordina módulos. No contiene lógica de negocio.
- **/modules/**: Módulos especializados (rh_requests.py, flow_builder.py, ui.py, logger.py, ai.py, finalizer.py).
- **/conv-flows/**: Archivos JSON que definen flujos conversacionales (e.g., horario.json).
- **.env.example**: Variables de entorno (Telegram token, webhooks; sin DB).
- **requirements.txt**: Dependencias Python.
- **Docker**: Para despliegue (Dockerfile, docker-compose.yml).
- **Archivos eliminados**: db_logic.md, bot_brain.md, Vanessa.md, Readme.md (original), models/, init/ (temporalmente, ya que DB está fuera).

## Arquitectura y Funcionamiento
### Flujo Actual (Temporal: Solo Envío de Webhooks)
1. Usuario inicia comando (e.g., /vacaciones).
2. main.py enruta a handler en módulo.
3. Módulo procesa conversación, valida, envía webhook a n8n.
4. n8n procesa y guarda en DB remota.
5. Bot responde inmediatamente al usuario (sin esperar confirmación).

### Nuevo Enfoque Propuesto (Bidireccional)
Cambiar a webhooks bidireccionales donde el bot espera respuesta de n8n antes de notificar al usuario, garantizando persistencia.

## Componentes Clave
### 1. main.py
- Registra comandos y handlers desde módulos.
- Setup de Telegram bot.

### 2. /modules
- **rh_requests.py**: Solicitudes de vacaciones/permisos; envía webhooks.
- **flow_builder.py**: Carga y ejecuta flujos desde JSON en /conv-flows.
- **ui.py**: Teclados y menús.
- **logger.py**: Logging.
- **ai.py**: Clasificación IA.
- **finalizer.py**: Finaliza flujos.

### 3. /conv-flows
- JSON con steps: state, type (keyboard/text/info), question, options, next_step.
- Ejemplo: horario.json para definir horarios.

## Roadmap
### Fase 1 (Actual): Sin DB, Webhooks Unidireccionales
- Flujos conversacionales funcionales.
- Envío de payloads a n8n.

### Fase 2: Webhooks Bidireccionales
- Agregar receptor de webhooks (Flask en main.py).
- Esperar respuesta de n8n para confirmar usuario.
- Storage temporal para solicitudes pendientes.

### Fase 3: Implementar DB
- DB nativa (SQLite/PostgreSQL) o acceso remoto en VPS.
- Persistencia local para reporting.

### Fase 4: Escalabilidad y Mejoras
- Manejo concurrente, logging avanzado, integraciones.

## Instalación y Ejecución
1. Clonar repo.
2. `cp .env.example .env` y configurar (TOKEN, WEBHOOK_*).
3. `pip install -r requirements.txt`
4. `python main.py` o `docker-compose up`

## Problema Actual y Solución
- **Problema**: Pérdida de datos en DB al mover desde n8n.
- **Temporal**: Bot responde inmediatamente.
- **Futuro**: Esperar confirmación para asegurar persistencia.

## Beneficios del Approach
- Modularidad: Fácil extender.
- Desacoplamiento: Sin DB local inicial.
- Escalabilidad: Webhooks para cualquier backend.
- Mantenibilidad: Código limpio.

## Pasos de Implementación (Detalle en new_plan.md)
- Análisis de flujo actual.
- Diseño bidireccional.
- Agregar receptor webhooks.
- Modificar módulos.
- Storage pendiente.
- Actualizar n8n.
- Pruebas.

## Timeline
- Análisis: 1-2 días
- Diseño: 1 día
- Implementación: 3-5 días
- Pruebas: 2-3 días

## Consideraciones Técnicas
- Timeout para callbacks.
- Seguridad en webhooks.
- Escalabilidad con Redis si necesario.