Validator für tabellarische Datensätze

Automatisierung, die als Qualitätsfilter zwischen der Erfassung von Datensätzen und dem System, das sie konsumieren wird, fungiert: Sie liest eine Tabelle, blockiert inkonsistente Einträge und erklärt den Grund für jede Ablehnung, priorisiert gültige Einträge nach einem Dringlichkeitskriterium und versucht sogar, automatisch mit KI die blockierten Datensätze wiederherzustellen.

Der Ursprungsfall sind Fabrikbestellungen (Produktion auf Abruf), aber die Logik gilt für jede Menge tabellarischer Datensätze, die inkonsistent ankommen und vor der Weiterverarbeitung geprüft werden müssen – Importe, Registrierungen, Systemintegrationen. Die Geschäftsregeln leben in config.yaml; die Domäne zu wechseln bedeutet, YAML zu bearbeiten, nicht Code.

Laufender Dienst: https://validador-pedidos-gocase.onrender.com

Das Problem

Immer wenn Datensätze aus verschiedenen Quellen in ein System gelangen, validiert jede Quelle beim Eingang anders – oder gar nicht. Das Ergebnis ist eine Charge, in der perfekte Datensätze neben Datensätzen mit leerem Pflichtfeld, kaputter E-Mail, nulltem Wert, nicht stimmigem Betrag, vergangenem Datum oder Duplikaten koexistieren.

Das manuell zu prüfen ist langsam, ermüdend und lässt subtile Fehler durchgehen – eine Cent-Differenz, ein Duplikat, das durch Dutzende Zeilen getrennt ist. Schlimmer: Ein gültiger Datensatz kann wegen Ausfüllfehlern, nicht Inhaltsfehlern abgelehnt werden – ein fehlender Name, ein @, das aus der E-Mail verschwunden ist. Die richtigen Daten existieren; sie sind nur nicht formatiert angekommen.

Im Ursprungsfall ist jeder Datensatz eine Bestellung, die zu einem physischen Produktionsauftrag wird. Eine Bestellung mit kaputten Daten ist nicht nur ein falscher Datensatz – es ist verschwendetes personalisiertes Material, verlorene Maschinenstunden und ein Kunde, der nichts erhält. Das ist dasselbe Muster wie in jedem Fluss, in dem ein schlechter Datensatz später teuer wird.

Related MCP server: fcp-sheets

So funktioniert es

Der Kern ist eine Pipeline aus vier Schritten, die über drei Oberflächen (Terminal, HTTP-API, MCP) verfügbar ist, die dieselbe Funktion aufrufen:

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. Lesen (src/leitor.py) – liest das Excel, typisiert Spalten und prüft das erwartete Schema. Eine fehlende Spalte wird zu einem lesbaren Fehler, nicht zu einem generischen Absturz.

2. Validierung (src/validador.py) – wendet die 9 Regeln auf jeden Datensatz an; trennt gültige von abgelehnten; sammelt alle Gründe pro Datensatz.

3. Priorisierung (src/organizador.py) – berechnet dias_restantes und sortiert die gültigen in eine Dringlichkeitswarteschlange.

4. Bericht (src/relatorio.py) – erzeugt die 3 formatierten Tabellen.

5. KI-Wiederherstellung (src/assistente_ia.py, optional) – versucht, die abgelehnten wiederherzustellen; was die KI korrigiert, geht erneut durch die Validierung, die keine Ausnahmen macht.

So nutzt es der Bediener

1. Öffnet das Formular im Browser.

2. Lädt die .xlsx-Tabelle hoch.

3. Erhält ein .zip mit den drei fertigen Tabellen zurück.

Auf keiner Maschine wird etwas installiert: Die Verarbeitung läuft auf dem Server und das Ergebnis kommt über den Browser zurück. Das Formular wird über den n8n-Flow veröffentlicht, der das Projekt in integracoes/ begleitet und einmalig importiert wird. Wer n8n nicht nutzt, konsumiert die API direkt – der Vertrag steht im selben Leitfaden.

Zum Ausprobieren ohne eigene Daten enthält das Repository exemplo/pedidos_exemplo.xlsx: 50 Datensätze, von denen 10 repräsentative Fehler enthalten.

Erster Lauf des Tages. Der Dienst ist auf einem kostenlosen Plan gehostet und schläft nach einigen Minuten ohne Nutzung ein. Der erste Aufruf dauert etwa 50 Sekunden, um den Server aufzuwecken; die folgenden antworten in weniger als 1 Sekunde. Wenn der Flow beim ersten Versuch ein Timeout meldet, einfach wiederholen.

Validierungsregeln

Jeder Datensatz wird gegen alle Regeln geprüft. Ein Datensatz kann mehrere Gründe ansammeln, die in der Spalte motivo_rejeicao verkettet werden – die vollständige Liste der Probleme auf einmal, nicht ein Fehler pro Neuverarbeitung.

Die Feldnamen oben stammen aus der Ursprungsdomäne (Bestellungen). Das mapa_colunas in config.yaml übersetzt die Kopfzeilen jedes Exports in diese Namen, sodass eine Tabelle aus einem anderen System keinen neuen Code erfordert.

Priorität

Die Genehmigten erhalten dias_restantes und kommen in eine nach Dringlichkeit sortierte Warteschlange – die knappsten zuerst. Die Bereiche (Namen, Intervalle und Farben) leben in config.yaml.

Was geliefert wird

Stack

Python 3.10+.

Gemessenes Ergebnis

Demo-Charge: 50 Datensätze, mit 10 echten Problemen.

Die Zahlen oben stammen aus der Ausführung über exemplo/pedidos_exemplo.xlsx (synthetische Daten), lokal gemessen. Sie sind keine Prognose für das reale Produktionsvolumen.

Was die KI in der realen Ausführung korrigiert hat

Was sie zu Recht nicht gelöst hat

Von den 10 Abgelehnten blieben 5 – und das ist richtig so:

• 2 Duplikate – erfordern eine menschliche Entscheidung, welcher Datensatz gilt.

• 1 abgelaufener Termin – kein Datenfehler, sondern ein operatives Problem.

• 2 inkonsistente Werte – die KI hat die Menge angepasst, aber der valor_total stimmte nicht, also blieb der Datensatz weiterhin abgelehnt. Die Validierung macht für die KI keine Ausnahme.

KI-Ebene – Wiederherstellung abgelehnter Datensätze

Einen Datensatz zu blockieren löst die halbe Aufgabe. Die andere Hälfte ist, ihn wiederherzustellen, wenn der Fehler ein Ausfüllfehler und kein Inhaltsfehler ist. Die Arbeitsteilung ist explizit:

• Mechanischer Fehler (Wert stimmt nicht, überflüssiges Leerzeichen, zu normalisierende E-Mail) → per Regel gelöst, ohne KI.

• Semantischer Fehler (fehlender Name, unvollständige E-Mail) → die KI leitet ihn ab, indem sie die anderen Felder desselben Datensatzes kreuzt.

• Nicht ableitbare Daten → für menschliche Prüfung markiert, niemals erfunden.

Audit-Pfad

Automatische Korrektur ist nur vertrauenswürdig, wenn sie prüfbar ist. Die KI signiert ihre Arbeit innerhalb der gelieferten Tabellen:

• Spalte corrigido_por_ia markiert die wiederhergestellten Datensätze.

• Spalte correcao_ia protokolliert das Vorher → Nachher jedes geänderten Feldes.

• Die Zusammenfassung enthält die Zeile "Von der KI wiederhergestellte Datensätze".

Den Namen aus der E-Mail abzuleiten ist eine plausible Inferenz, keine bestätigte Tatsache. Deshalb gibt es den Pfad: Die KI beschleunigt die Wiederherstellung, und die endgültige Entscheidung bleibt für eine Person überprüfbar.

Architektur

Einzelverantwortung pro Modul – jede Datei macht eine Sache und ist isoliert testbar.

Einzige Quelle der Wahrheit. Der Fluss lebt in executar_pipeline; die Metriken werden einmal erstellt und vom Bericht, vom Log und von der API wiederverwendet. Namen, Reihenfolge und Farben der Prioritätsbereiche existieren nur in config.yaml.

Konsumformen

Eine Validierungslogik, drei Oberflächen – ohne doppelte Regel.

n8n führt die Automatisierung in Stapeln aus; das MCP erlaubt es, sie in natürlicher Sprache zu befragen – „wie viele Datensätze wurden gesperrt und warum?". Um es in einem kompatiblen Client (z. B. Claude Desktop) zu aktivieren, zeigen Sie ihn auf den Server:

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

Verfügbare Tools: validar_pedidos, consultar_resumo, analisar_rejeitados, revalidar_com_correcoes und gerar_dados_exemplo, plus ein Leitfaden-Prompt. Die beiden mittleren bilden den Zyklus der assistierten Korrektur: Das Modell des eigenen Clients schlägt die Korrekturen vor und der Server validiert erneut.

Die Integration bindet das Tool nicht: Da es reines HTTP ist, nutzen Make, Power Automate oder eigener Code dieselbe API. n8n ist der dokumentierte und getestete Weg.

Konfiguration ohne Code

Geschäftsregeln liegen außerhalb des Codes in config.yaml: Wertetoleranz, E-Mail-Muster, Pflichtspalten und die Prioritätsstufen (Namen, Bereiche und Farben). Ein Manager passt Grenzen an, ohne Python zu öffnen.

mapa_colunas übersetzt die Kopfzeilen eines echten Exports in die erwarteten Namen – das ist der Punkt für den Domänenwechsel: andere Tabelle, gleiche Logik.

Fehlende oder ungültige Konfiguration bringt nichts zum Absturz: Das System meldet es und verwendet die eingebauten Standardwerte.

Tests

testar.py führt 13 End-to-End-Prüfungen aus, ohne externes Framework – es ist ein Skript, das den echten Ablauf ausführt und Invarianten prüft:

• Erzeugung der Beispieldatei und Ausführung der Pipeline;

• Vorhandensein und Inhalt der 3 Tabellenblätter und des Logs;

• Konsistenz (genehmigt + abgelehnt = gesamt);

• Vorhandensein eines Grundes in allen abgelehnten Datensätzen;

• die API (Validierung, Download des Pakets, Ablehnung einer Tabelle außerhalb des Formats mit lesbarer Fehlermeldung);

• den MCP-Server, über das echte Protokoll ausgeübt: Handshake, Tool- Katalog und ein End-to-End ausgeführtes Tool.

Weitere eingebaute Sicherheitsvorkehrungen: Ein in Excel geöffneter Bericht wird mit erneuten Versuchen und einer klaren Meldung behandelt; eine fehlerhaft formatierte Korrektur von der KI wird verworfen, ohne den Stapel zu stoppen; temporäre Serverdateien laufen von selbst nach 1 Stunde ab.

python testar.py

So führen Sie es aus

Voraussetzungen: 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

Um die echte Tabelle einzusetzen, speichern Sie sie unter data/pedidos_entrada.xlsx, bevor Sie main.py ausführen.

Umgebungsvariablen (optional)

Alle haben Standardwerte; keine ist für die Validierung erforderlich. Die KI-Korrektur aktiviert sich nur mit vorhandenem Schlüssel.

Der Schlüssel liegt nie im Repository – nur in der Serverumgebung.

Einschränkungen und nächste Schritte

Umfang dieser Lieferung. Die API ist ohne Authentifizierung veröffentlicht, aus einer bewussten Scope-Entscheidung. Die URL sollte nur mit der Demo-Tabelle (synthetische Daten) verwendet werden; echte Datensätze enthalten personenbezogene Daten und erfordern eine Schlüsselauthentifizierung, bevor sie über eine offene URL übertragen werden. Das ist ein bewusster Schritt der Roadmap, kein Versehen.

Was in größerem Maßstab brechen würde. Die Verarbeitung ist synchron und lädt die gesamte Tabelle in den Speicher (pandas) – geeignet für Stapel mit Tausenden von Zeilen, nicht für Millionen. Die Duplikaterkennung prüft nur innerhalb des aktuellen Stapels, nicht zwischen Ausführungen.

Natürliche Weiterentwicklung. Datensätze direkt aus der Quelle lesen (ERP, Datenbank) statt aus einer Tabelle; den Status zurück ins Ursprungssystem schreiben; aktive Benachrichtigung, wenn die Ablehnungsquote steigt; Verlauf zwischen Stapeln, um Duplikate zu erkennen, die Ausführungen übergreifen.

Projektursprung

Dieses Projekt entstand als Business Case für das Auswahlverfahren für ein RPA- Praktikum bei GoCase (GoGroup), Bereich Fabrikbetrieb. Die ursprüngliche Domäne ist die Validierung von Produktionsaufträgen auf Abruf, bei der jeder defekte Datensatz zu verbrauchtem personalisiertem Material und verlorener Maschinenzeit wird.

Die Dokumentation wurde verallgemeinert, weil die Lösung – automatische Prüfung von tabellarischen Datensätzen, die inkonsistent ankommen, mit Wiederherstellung dessen, was ein Ausfüllfehler und kein Inhaltsfehler ist – auf jeden ähnlichen Ablauf anwendbar ist. Das Vokabular der Aufträge bleibt in den Regeln und Beispielen erhalten, weil es der real gemessene Fall ist, nicht weil es der einzig mögliche wäre.