RPA Tracker

Bot RPA para procesamiento automatizado de solicitudes desde archivos CSV/XLSX organizados por fecha, con validación estricta, deduplicación, clasificación y envío a formulario web mediante Playwright.

Descripción

RPA Tracker es un bot de automatización que procesa archivos de solicitudes almacenados en una estructura de directorios por fecha (YYYY/MM/DD/). Cada archivo se lee, valida contra modelos Pydantic, se deduplica por email, se clasifica por tipo de solicitud y se envía a un formulario web configurable. El sistema detecta automáticamente qué archivos ya fueron procesados comparando rutas relativas entre input/ y output/ usando conjuntos (set difference).

Arquitectura

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌────────────────┐     ┌─────────────┐
│  Tracker    │───> │  Readers    │────>│  Services   │───> │  Submitter     │────>│  Reporter   │
│ (set diff)  │     │ (Strategy+  │     │(validate,   │     │  (Playwright)  │     │(Loguru +    │
│             │     │ Factory)    │     │ dedup,      │     │                │     │ CSV)        │
└─────────────┘     └─────────────┘     │ classify)   │     └────────────────┘     └─────────────┘
                                        └─────────────┘

Patrones de diseño:

• Template Method: BaseProcessableFile con igualdad polimórfica por path_dir
• Strategy + Factory: BaseReader → CsvReader / XlsxReader via reader_factory()

Estructura de Directorios

rpa_tracker/
├── input/                      # Archivos entrada: YYYY/MM/DD/*.csv|xlsx
├── output/                     # Archivos salida: plano con sufijo _YYYYMMDD
├── logs/                       # Logs rotativos diarios (retención 7 días)
├── src/rpa_tracker/            # Paquete principal
│   ├── config.py               # Carga .env (INPUT_PATH, OUTPUT_PATH, WEB_FORM_URL, HEADLESS)
│   ├── exceptions.py           # BotException, FileReadError, ValidationFailedError, SubmissionError
│   ├── models.py               # Template Method tracking + Pydantic (Persona, Solicitud)
│   ├── readers.py              # Strategy+Factory (CsvReader, XlsxReader)
│   ├── services.py             # validate, deduplicate, classify
│   ├── submitter.py            # WebSubmitter (Playwright, headless=True)
│   ├── tracker.py              # get_unprocessed_files (set difference)
│   ├── reporter.py             # Loguru setup, guardar_resultados, resúmenes
│   ├── utils.py                # output_filename (sufijo fecha de input)
│   ├── orchestrator.py         # Pipeline completo
│   ├── main.py                 # Entrypoint
│   └── generate_test_data.py   # Generador de datos de prueba
├── tests/
│   └── test_bot.py             # 17 tests unitarios/integración
├── pyproject.toml              # Configuración PDM
├── .env.example                # Plantilla variables de entorno
├── LICENSE                     # Licencia MIT
├── run.bat                     # Windows: loop 60s con pausa/reanudación
└── run.sh                      # Linux/macOS: loop 60s con pausa/reanudación

Requisitos

• Python ≥ 3.11
• PDM (Python Dependency Manager)
• Playwright Chromium (se instala automáticamente)

Dependencias principales (ver pyproject.toml):

• pandas ≥ 2.0
• pydantic ≥ 2.0 (con email-validator)
• python-dotenv ≥ 1.0
• loguru ≥ 0.7
• playwright ≥ 1.40
• openpyxl ≥ 3.1

Instalación

# Clonar repositorio
git clone https://github.com/AngBan2x/rpa_tracker.git
cd rpa_tracker

# Instalar dependencias con PDM
pdm install

# Instalar navegador Playwright (Chromium)
pdm run python -m playwright install chromium

Configuración

Copiar .env.example a .env y ajustar valores:

# Directorio de archivos de entrada (estructura YYYY/MM/DD/)
INPUT_PATH=input

# Directorio de archivos de salida (plano con sufijo de fecha)
OUTPUT_PATH=output

# Directorio de logs
LOGS_DIR=logs

# URL del formulario web a rellenar
WEB_FORM_URL=https://example.com/form

# Modo headless para Playwright (true/false)
HEADLESS=true

Uso

Ejecución única (modo interactivo)

pdm run python -m rpa_tracker.main

Modo demonio (loop 60s con pausa/reanudación)

Windows:

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

Ambos scripts ejecutan el bot cada 60 segundos. En Windows usa timeout /t 60 (pausa con cualquier tecla). En Linux usa sleep 60 & wait (click en consola = pausa, Enter = reanuda). Detener con Ctrl+C.

Tests

pdm run pytest tests/test_bot.py -v

Generador de Datos de Prueba

Genera archivos CSV/XLSX válidos con estructura de directorios por fecha:

# Básico: 5 archivos x 20 filas (CSV + XLSX) en input/ con fecha de hoy
pdm run python -m rpa_tracker.generate_test_data --count 5 --rows 20

# Solo CSV con casos edge (inválidos, duplicados, fechas malformadas)
pdm run python -m rpa_tracker.generate_test_data --format csv --scenarios --count 3

# Limpiar input/ antes de generar 10 archivos
pdm run python -m rpa_tracker.generate_test_data --clean --count 10

# Fecha específica y seed reproducible
pdm run python -m rpa_tracker.generate_test_data --date 2028/01/15 --seed 42

Opciones disponibles:

• -c, --count: Número de archivos (default: 5)
• -r, --rows: Filas por archivo (default: 20)
• -d, --date: Fecha objetivo YYYY/MM/DD (default: hoy)
• -f, --format: csv, xlsx o both (default: both)
• -s, --scenarios: Incluye casos edge (campos faltantes, emails inválidos, fechas malformadas, enums inválidos, emails duplicados)
• --clean: Elimina input/ antes de generar
• -o, --output-dir: Directorio base (default: input/)
• --seed: Semilla para reproducibilidad

Casos edge con --scenarios:

• Filas con campos obligatorios vacíos
• Emails con formato inválido
• Fechas en formato incorrecto (DD/MM/YYYY en lugar de YYYY/MM/DD)
• Valores inválidos en prioridad (ej: "urgente") y estado (ej: "cancelada")
• Emails duplicados entre filas
• Archivos vacíos

Formato de Entrada

Los archivos CSV/XLSX deben contener exactamente 13 columnas (orden indistinto):

Columna	Tipo	Validación
First Name	string	No vacío
Last Name	string	No vacío
Company Name	string	No vacío
Role in Company	string	No vacío
Address	string	No vacío
Email	string	Email válido (EmailStr)
Phone Number	string	No vacío
tipo_solicitud	string	Libre
fecha	date	Formato YYYY/MM/DD
prioridad	enum	alta | media | baja
identificador	string	No vacío
descripcion	string	No vacío
estado	enum	pendiente | en_proceso | completada

Ejemplo fila válida:

First Name,Last Name,Company Name,Role in Company,Address,Email,Phone Number,tipo_solicitud,fecha,prioridad,identificador,descripcion,estado
Juan,Pérez,ACME,Developer,"Calle 123",juan@acme.com,555-1234,reclamo,2028/01/15,alta,REC-001,Reclamo por servicio,pendiente

Salida

Por cada archivo procesado se genera en output/:

{stem}_{YYYYMMDD}.csv

Donde YYYYMMDD es la fecha extraída de la carpeta de entrada (YYYY/MM/DD/).

Columnas de salida = 13 originales +:

• resultado_envio: exitoso | fallido
• error_envio: mensaje de error si falló

Logs

• Consola: Resúmenes por archivo y global con conteos
• Archivo: logs/bot.log (rotación diaria, retención 7 días, nivel DEBUG)

Casos de Uso

• Procesamiento masivo de solicitudes/reclamos/consultas desde archivos estructurados
• Automatización de formularios web repetitivos (onboarding, tickets, encuestas)
• Auditoría de procesados vs pendientes mediante tracking por conjuntos
• Deduplicación automática por email antes de envío

Limitaciones

• Selectores fijos: El formulario web debe usar name o id estándar (first_name, last_name, email, etc.)
• Solo Chromium: Playwright configurado solo para Chromium headless
• Sin autenticación web: No maneja login, cookies, tokens ni MFA
• Validación estricta de columnas: Falla si faltan columnas (no ignora extras)
• Una solicitud por fila: No agrupa múltiples filas en un solo envío
• Formato fecha único: Solo acepta YYYY/MM/DD en columna fecha

Licencia

MIT License - Ver LICENSE para detalles.

---

Autor: Angel Bandres
Versión: 1.1.0