Validador de Registros Tabulares

Automatización que actúa como filtro de calidad entre la captación de registros y el sistema que va a consumirlos: lee una hoja de cálculo, bloquea lo que es inconsistente explicando el motivo de cada rechazo, prioriza lo que es válido por un criterio de urgencia y además intenta recuperar automáticamente, con IA, los registros que fueron bloqueados.

El caso de origen son pedidos de fábrica (producción bajo demanda), pero la lógica sirve para cualquier conjunto de registros tabulares que llega inconsistente y necesita revisión antes de seguir adelante — importaciones, altas, integración entre sistemas. Las reglas de negocio viven en config.yaml; cambiar el dominio es editar YAML, no código.

Servicio en línea: https://validador-pedidos-gocase.onrender.com

El problema

Siempre que los registros entran en un sistema procedentes de varios orígenes, cada origen valida en la entrada de una manera diferente — o no valida. El resultado es un lote donde conviven registros perfectos y registros con campo obligatorio vacío, correo roto, número a cero, valor que no cuadra, fecha en el pasado o duplicidad.

Revisar esto a mano es lento, agotador y deja pasar errores sutiles — una diferencia de céntimos, un duplicado separado por decenas de líneas. Peor: un registro válido puede ser rechazado por error de cumplimentación, no de contenido — un nombre que faltó, una @ que desapareció del correo. El dato correcto existe; solo no llegó formateado.

En el caso de origen, cada registro es un pedido que se convierte en orden de producción física. Un pedido con dato roto no es solo un registro erróneo — es material personalizado gastado, hora-máquina perdida y cliente sin recibir. Es el mismo patrón de cualquier flujo en el que el registro malo cuesta caro más adelante.

Related MCP server: fcp-sheets

Cómo funciona

El núcleo es un pipeline de cuatro etapas, expuesto por tres superficies (terminal, API HTTP, MCP) que llaman a la misma función:

flowchart LR
    A[Planilha .xlsx] --> B[Leitura + schema]
    B --> C[Validação<br/>9 regras]
    C -->|válidos| D[Priorização<br/>por prazo]
    C -->|rejeitados| E[Recuperação por IA]
    E -->|corrigido| C
    E -->|indeduzível| F[Revisão humana]
    D --> G[3 planilhas .xlsx]
    C --> G

1. Lectura (src/leitor.py) — lee el Excel, tipa columnas y comprueba el esquema esperado. Una columna que falta se convierte en error legible, no en fallo genérico.

2. Validación (src/validador.py) — aplica las 9 reglas a cada registro; separa válidos de rechazados; acumula todos los motivos por registro.

3. Priorización (src/organizador.py) — calcula dias_restantes y ordena los válidos en cola de urgencia.

4. Informe (src/relatorio.py) — genera las 3 hojas de cálculo formateadas.

5. Recuperación por IA (src/assistente_ia.py, opcional) — intenta recuperar los rechazados; lo que la IA corrige vuelve a pasar por la validación, que no hace excepciones.

Cómo lo usa el operador

1. Abre el formulario en el navegador.

2. Sube la hoja de cálculo .xlsx.

3. Recibe de vuelta un .zip con las tres hojas de cálculo listas.

No se instala nada en la máquina de nadie: el procesamiento se ejecuta en el servidor y el resultado vuelve por el navegador. El formulario se publica mediante el flujo n8n que acompaña al proyecto en integracoes/, importado una única vez. Quien no usa n8n consume la API directamente — el contrato está en la misma guía.

Para experimentar sin preparar datos, el repositorio incluye exemplo/pedidos_exemplo.xlsx: 50 registros, de los cuales 10 contienen defectos representativos.

Primera ejecución del día. El servicio está alojado en plan gratuito y hiberna tras algunos minutos sin uso. La primera llamada tarda unos 50 segundos en despertar el servidor; las siguientes responden en menos de 1 segundo. Si el flujo acusa tiempo agotado en el primer intento, basta con repetir.

Reglas de validación

Cada registro se evalúa contra todas las reglas. Un registro puede acumular varios motivos, concatenados en la columna motivo_rejeicao — la lista completa de problemas de una vez, no un error por reprocesamiento.

Los nombres de campo anteriores son los del dominio de origen (pedidos). El mapa_colunas del config.yaml traduce los encabezados de cualquier exportación a esos nombres, así que una hoja de cálculo de otro sistema no exige código nuevo.

Prioridad

Los aprobados reciben dias_restantes y entran en una cola ordenada por urgencia — los más ajustados primero. Las franjas (nombres, intervalos y colores) viven en el config.yaml.

Lo que se entrega

Stack

Python 3.10+.

Resultado medido

Lote de demostración: 50 registros, con 10 problemas reales.

Los números anteriores provienen de la ejecución sobre exemplo/pedidos_exemplo.xlsx (datos sintéticos), medidos localmente. No son proyección de volumen real de producción.

Lo que la IA corrigió en la ejecución real

Lo que correctamente no resolvió

De los 10 rechazados, 5 permanecieron — y así debe ser:

• 2 duplicados — exigen decisión humana sobre qué registro vale.

• 1 plazo vencido — no es error de dato, es problema operativo.

• 2 valores incoherentes — la IA ajustó la cantidad, pero el valor_total no cuadró, así que el registro siguió rechazado. La validación no hace excepciones para la IA.

Capa de IA — recuperación de registros rechazados

Bloquear un registro resuelve la mitad del problema. La otra mitad es recuperarlo cuando el error es de cumplimentación, no de contenido. La división de trabajo es explícita:

• Error mecánico (valor que no cuadra, espacio sobrante, correo a normalizar) → resuelto por regla, sin IA.

• Error semántico (nombre que falta, correo incompleto) → la IA infiere cruzando los otros campos del propio registro.

• Dato imposible de deducir → señalado para revisión humana, nunca inventado.

Rastro de auditoría

La corrección automática solo es fiable si es auditable. La IA firma lo que hizo, dentro de las hojas de cálculo entregadas:

• La columna corrigido_por_ia marca los registros recuperados.

• La columna correcao_ia registra el antes → después de cada campo modificado.

• El resumen incluye la línea "Registros recuperados por la IA".

Deducir el nombre a partir del correo es una inferencia plausible, no un dato confirmado. Por eso existe el rastro: la IA acelera la recuperación y la decisión final sigue siendo verificable por una persona.

Arquitectura

Responsabilidad única por módulo — cada archivo hace una cosa y es comprobable de forma aislada.

Fuente única de verdad. El flujo vive en executar_pipeline; las métricas se montan una vez y las reutilizan el informe, el log y la API. Nombres, orden y colores de las franjas de prioridad existen solo en el config.yaml.

Formas de consumo

Una lógica de validación, tres superficies — sin regla duplicada.

El n8n ejecuta la automatización en lote; el MCP permite interrogarla en lenguaje natural — "¿cuántos registros fueron bloqueados y por qué?". Para habilitarlo en un cliente compatible (Claude Desktop, por ejemplo), apúntelo al servidor:

{
  "mcpServers": {
    "validador-gocase": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "caminho/para/validador-pedidos-gocase"
    }
  }
}

Herramientas expuestas: validar_pedidos, consultar_resumo, analisar_rejeitados, revalidar_com_correcoes y gerar_dados_exemplo, más un prompt guía. Las dos del medio forman el ciclo de corrección asistida: el modelo del propio cliente propone las correcciones y el servidor revalida.

La integración no ata la herramienta: al ser HTTP puro, Make, Power Automate o código propio consumen la misma API. El n8n es el camino documentado y probado.

Configuración sin código

Las reglas de negocio quedan fuera del código, en config.yaml: tolerancia de valor, patrón de correo electrónico, columnas obligatorias y los rangos de prioridad (nombres, intervalos y colores). Un gestor ajusta límites sin abrir Python.

El mapa_colunas traduce los encabezados de una exportación real a los nombres esperados — es el punto de intercambio de dominio: otra hoja de cálculo, misma lógica.

Configuración ausente o inválida no derriba nada: el sistema avisa y usa los valores predeterminados integrados.

Pruebas

testar.py ejecuta 13 verificaciones de extremo a extremo, sin framework externo — es un script que ejecuta el flujo real y comprueba invariantes:

• generación de la hoja de cálculo de ejemplo y ejecución del pipeline;

• existencia y contenido de las 3 hojas de cálculo y del log;

• consistencia (aprovados + reprovados = total);

• presencia de motivo en todos los reprobados;

• la API (validación, descarga del paquete, rechazo de hoja de cálculo fuera del formato con error legible);

• el MCP Server, ejercitado por el protocolo real: handshake, catálogo de herramientas y una herramienta ejecutada de extremo a extremo.

Otras salvaguardas integradas: informe abierto en Excel se trata con nuevos intentos y mensaje claro; corrección malformada proveniente de la IA se descarta sin derribar el lote; archivos temporales del servidor expiran solos en 1 hora.

python testar.py

Cómo ejecutar

Requisitos previos: Python 3.10+.

# 1. Dependências
pip install -r requirements.txt

# 2a. Modo terminal — gera dados de exemplo se não houver planilha real
python main.py

# 2b. Modo API HTTP
uvicorn api:app --host 0.0.0.0 --port 8000
# Docs interativas em http://localhost:8000/docs

Para colocar la hoja de cálculo real, guárdela en data/pedidos_entrada.xlsx antes de ejecutar main.py.

Variables de entorno (opcionales)

Todas tienen valor predeterminado; ninguna es obligatoria para validar. La corrección por IA solo se activa con la clave presente.

La clave nunca queda en el repositorio — solo en el entorno del servidor.

Limitaciones y próximos pasos

Alcance de esta entrega. La API está publicada sin autenticación, por decisión de alcance. La URL debe usarse solo con la hoja de cálculo de demostración (datos sintéticos); los registros reales contienen datos personales y exigen autenticación por clave antes de transitar por una URL abierta. Es un paso consciente del roadmap, no un olvido.

Lo que se rompería a mayor escala. El procesamiento es síncrono y carga la hoja de cálculo completa en memoria (pandas) — adecuado para lotes de miles de filas, no de millones. La detección de duplicados mira solo dentro del lote actual, no entre ejecuciones.

Evolución natural. Leer los registros directamente de la fuente (ERP, base de datos) en lugar de hoja de cálculo; escribir el estado de vuelta en el sistema de origen; notificación activa cuando el índice de reprobación suba; historial entre lotes para detectar duplicidad que atraviesa ejecuciones.

Origen del proyecto

Este proyecto nació como business case para el proceso selectivo de Prácticas en RPA en GoCase (GoGroup), área de Operaciones de Fábrica. El dominio original es la validación de pedidos de producción bajo demanda, donde cada registro roto se convierte en material personalizado gastado y hora-máquina perdida.

La documentación se generalizó porque la solución — verificación automática de registros tabulares que llegan inconsistentes, con recuperación de lo que es error de llenado y no de contenido — se aplica a cualquier flujo del mismo tipo. El vocabulario de pedidos permanece en las reglas y en los ejemplos por ser el caso real medido, no por ser el único aplicable.