表形式レコード検証器

レコードの収集とそれを消費するシステムの間の品質フィルターとして機能する自動化です。スプレッドシートを読み取り、不整合なものを拒否して各拒否理由を説明し、緊急度の基準で有効なものを優先し、さらにAIで拒否されたレコードの自動回復を試みます。

元のケースは工場注文（受注生産）ですが、このロジックは、不整合な状態で届き、先に進む前に確認が必要なあらゆる表形式レコードの集合に当てはまります。インポート、登録、システム間の統合などです。ビジネスルールはconfig.yamlにあり、ドメインを変更するにはYAMLを編集するだけで、コードは不要です。

稼働中のサービス: https://validador-pedidos-gocase.onrender.com

問題

複数の送信元からレコードがシステムに入るたびに、各送信元は入力時に異なる方法で検証するか、まったく検証しません。その結果、完全なレコードと、必須フィールドが空、壊れたメール、ゼロの数値、一致しない値、過去の日付、重複などの問題を抱えたレコードが混在するバッチが生まれます。

これを手作業で確認するのは遅く、疲れ、微妙なエラー（数セントの差、数十行離れた重複）を見逃します。さらに悪いことに、有効なレコードが内容ではなく記入ミス（名前の欠落、メールから消えた@）で拒否されることがあります。正しいデータは存在するのに、フォーマットされずに届いただけです。

元のケースでは、各レコードは物理的な生産指示に変わる注文です。壊れたデータの注文は単なる誤ったレコードではなく、無駄になったカスタム材料、失われた機械時間、顧客への未納品です。これは、不良レコードが後で高くつくあらゆるフローと同じパターンです。

Related MCP server: fcp-sheets

仕組み

中核は4段階のパイプラインで、同じ関数を呼び出す3つのインターフェース（ターミナル、HTTP API、MCP）で公開されています。

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. 読み取り (src/leitor.py) — Excelを読み取り、列を型付けし、期待されるスキーマを確認します。列が欠けていると、一般的な失敗ではなく、読みやすいエラーになります。

2. 検証 (src/validador.py) — 各レコードに9つのルールを適用し、有効なものと拒否されたものを分け、レコードごとにすべての理由を蓄積します。

3. 優先順位付け (src/organizador.py) — dias_restantesを計算し、有効なものを緊急度のキューに並べます。

4. レポート (src/relatorio.py) — フォーマットされた3つのスプレッドシートを生成します。

5. AIによる回復 (src/assistente_ia.py、オプション) — 拒否されたものを回復しようとします。AIが修正したものは検証に戻りますが、検証は例外を認めません。

オペレーターの使い方

1. ブラウザでフォームを開きます。

2. .xlsxスプレッドシートをアップロードします。

3. 準備完了の3つのスプレッドシートを含む.zipを受け取ります。

誰のマシンにも何もインストールされません。処理はサーバーで実行され、結果はブラウザで返されます。フォームは、プロジェクトに付属するn8nフロー（integracoes/）によって公開され、一度だけインポートされます。n8nを使用しない場合は、APIを直接利用します。契約は同じガイドにあります。

データを準備せずに試すには、リポジトリにexemplo/pedidos_exemplo.xlsxが含まれています。50レコードのうち、10件に代表的な欠陥があります。

1日の最初の実行。 このサービスは無料プランでホストされており、数分間使用されないと休止します。最初の呼び出しはサーバーを起動するのに約50秒かかります。以降の呼び出しは1秒未満で応答します。最初の試行でタイムアウトになった場合は、もう一度実行するだけです。

検証ルール

各レコードはすべてのルールに対して評価されます。レコードには複数の理由が蓄積され、motivo_rejeicao列に連結されます。再処理ごとに1つのエラーではなく、問題の完全なリストが一度に表示されます。

上記のフィールド名は元のドメイン（注文）のものです。config.yamlのmapa_colunasは、任意のエクスポートのヘッダーをこれらの名前に変換するため、別のシステムのスプレッドシートでも新しいコードは必要ありません。

優先度

承認されたものにはdias_restantesが割り当てられ、緊急度で並べられたキューに入ります。最も差し迫ったものが最初です。範囲（名前、間隔、色）はconfig.yamlにあります。

提供されるもの

スタック

Python 3.10以上。

測定された結果

デモバッチ：50レコード、10件の実際の問題。

上記の数値は、exemplo/pedidos_exemplo.xlsx（合成データ）での実行から得られたもので、ローカルで測定されました。実際の本番ボリュームの予測ではありません。

実際の実行でAIが修正したもの

正しく解決しなかったもの

拒否された10件のうち、5件は残りました。そして、それは正しい姿です：

• 2件の重複 — どのレコードが有効かの人間の判断が必要です。

• 1件の期限切れ — データエラーではなく、運用上の問題です。

• 2件の不整合な値 — AIは数量を調整しましたが、valor_totalが一致しなかったため、レコードは拒否されたままです。検証はAIに対して例外を認めません。

AIレイヤー — 拒否されたレコードの回復

レコードを拒否することは問題の半分を解決します。残りの半分は、エラーが内容ではなく記入ミスである場合に回復することです。作業の分担は明確です：

• 機械的エラー（値が一致しない、余分なスペース、正規化が必要なメール）→ AIなしでルールで解決。

• 意味的エラー（名前の欠落、不完全なメール）→ AIがレコード自体の他のフィールドを照合して推測。

• 推測できないデータ → 人間のレビュー用にフラグが立てられ、決して発明されません。

監査証跡

自動修正は、監査可能な場合にのみ信頼できます。AIは、提供されたスプレッドシート内で自分の行ったことを署名します：

• corrigido_por_ia列は、回復されたレコードをマークします。

• correcao_ia列は、変更された各フィールドの前→後を記録します。

• サマリーには「AIで回復されたレコード」という行があります。

メールから名前を推測することは、確認されたデータではなく、もっともらしい推測です。そのため、証跡が存在します。AIは回復を加速し、最終決定は引き続き人間が確認できます。

アーキテクチャ

モジュールごとに単一責任 — 各ファイルは1つのことを行い、単独でテスト可能です。

唯一の真実のソース。 フローはexecutar_pipelineにあり、メトリクスは一度構築され、レポート、ログ、APIで再利用されます。優先度範囲の名前、順序、色はconfig.yamlにのみ存在します。

消費方法

1つの検証ロジック、3つのインターフェース — 重複するルールはありません。

n8nはバッチ処理の自動化を実行し、MCPはそれを自然言語で問い合わせることを可能にします — 「何件のレコードが拒否され、その理由は？」。対応クライアント（例：Claude Desktop）で有効にするには、サーバーを指定します：

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

公開されるツール：validar_pedidos、consultar_resumo、 analisar_rejeitados、revalidar_com_correcoes、gerar_dados_exemplo、さらに ガイド用プロンプト。中央の2つが支援修正サイクルを構成します：クライアント側の モデル自体が修正を提案し、サーバーが再検証します。

この統合はツールに縛られません。純粋なHTTPのため、Make、Power Automate、または 独自コードでも同じAPIを利用できます。n8nは文書化されテスト済みの経路です。

コード不要の設定

ビジネスルールはコードの外、config.yaml に置きます：値の許容範囲、 メールパターン、必須列、優先度の範囲（名前、間隔、色）。管理者はPythonを開かずに 制限値を調整できます。

mapa_colunas は実際のエクスポートのヘッダーを期待される名前に変換します — これはドメインの交換ポイントです：別のスプレッドシートでも、同じロジック。

設定が欠落または無効でも何も停止しません：システムは警告を出し、組み込みの デフォルト値を使用します。

テスト

testar.py は外部フレームワークなしで13の検証をエンドツーエンドで実行します — 実際のフローを実行して不変条件を確認するスクリプトです：

• サンプルスプレッドシートの生成とパイプラインの実行；

• 3つのスプレッドシートとログの存在と内容；

• 整合性（承認 + 却下 = 合計）；

• すべての却下レコードに理由が存在すること；

• API（検証、パッケージのダウンロード、形式外のスプレッドシートを 読みやすいエラーで拒否）；

• MCPサーバー。実際のプロトコルで動作確認：ハンドシェイク、ツール カタログ、1つのツールをエンドツーエンドで実行。

その他の組み込みの保護策：Excelで開かれたレポートは再試行と明確なメッセージで 処理；AIからの不正な修正はバッチを停止させずに破棄；サーバーの一時ファイルは 1時間で自動的に期限切れ。

python testar.py

実行方法

前提条件： 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

実際のスプレッドシートを使用するには、main.py を実行する前に data/pedidos_entrada.xlsx に保存します。

環境変数（オプション）

すべてにデフォルト値があり、検証には必須のものはありません。AIによる修正は キーが存在する場合のみ有効になります。

キーはリポジトリには決して置かれません — サーバーの環境のみに存在します。

制限事項と次のステップ

今回の納品範囲。 APIは認証なしで公開されています。これは範囲の決定によるものです。 URLはデモ用スプレッドシート（合成データ）でのみ使用する必要があります。実際のレコードには 個人データが含まれており、公開URLを経由する前にキーによる認証が必要です。これはロードマップの 意識的なステップであり、見落としではありません。

大規模化した場合の課題。 処理は同期式で、スプレッドシート全体をメモリに読み込みます （pandas）— 数千行のバッチには適していますが、数百万行には不適切です。重複検出は 現在のバッチ内のみを対象とし、実行間では行われません。

自然な進化。 スプレッドシートではなくソース（ERP、データベース）から直接レコードを読み取る； ステータスを元のシステムに書き戻す；却下率が上昇したときのアクティブ通知；実行をまたぐ 重複を検出するためのバッチ間履歴。

プロジェクトの起源

このプロジェクトは、GoCase（GoGroup）のRPAインターン選考プロセス用のビジネスケースとして 生まれました。対象領域はオンデマンド生産の注文検証で、壊れたレコードはそれぞれ カスタム材料の浪費と機械時間の損失になります。

ドキュメントは一般化されています。なぜなら、このソリューション — 不整合な状態で届く 表形式レコードの自動チェックと、内容ではなく記入ミスであるエラーの回復 — は 同じタイプのあらゆるフローに適用できるからです。注文の語彙がルールと例に残っているのは、 それが唯一の適用可能なケースだからではなく、実際に測定されたケースだからです。