Валидатор табличных записей

Автоматизация, которая действует как фильтр качества между сбором записей и системой, которая будет их потреблять: читает таблицу, отклоняет несоответствующие записи с объяснением причины каждого отклонения, приоритизирует валидные по критерию срочности и дополнительно пытается автоматически восстановить с помощью ИИ отклонённые записи.

Исходный случай — заказы на фабрике (производство под заказ), но логика применима к любому набору табличных записей, которые поступают с ошибками и требуют проверки перед дальнейшей обработкой — импорты, регистрации, интеграция между системами. Бизнес-правила находятся в config.yaml; смена домена — это редактирование YAML, а не кода.

Сервис в сети: https://validador-pedidos-gocase.onrender.com

Проблема

Когда записи попадают в систему из разных источников, каждый источник валидирует на входе по-своему — или не валидирует вовсе. В результате получается пакет, где соседствуют идеальные записи и записи с пустым обязательным полем, битым email, нулевым числом, не сходящимся значением, датой в прошлом или дубликатом.

Проверять это вручную — медленно, утомительно и позволяет пропустить тонкую ошибку — разницу в копейках, дубликат, разделённый десятками строк. Хуже того: валидная запись может быть отклонена из-за ошибки заполнения, а не содержания — пропущенного имени, пропавшего @ в email. Правильные данные существуют; просто не пришли в нужном формате.

В исходном случае каждая запись — это заказ, который превращается в физический производственный заказ. Заказ с битыми данными — это не просто ошибочная запись: это потраченный персонализированный материал, потерянное машинное время и клиент, который ничего не получил. Это та же закономерность, что и в любом процессе, где плохая запись дорого обходится в дальнейшем.

Related MCP server: fcp-sheets

Как это работает

Ядро — конвейер из четырёх этапов, доступный через три интерфейса (терминал, 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. Восстановление с помощью ИИ (src/assistente_ia.py, опционально) — пытается восстановить отклонённые; то, что исправляет ИИ, снова проходит валидацию, которая не делает исключений.

Как работает оператор

1. Открывает форму в браузере.

2. Загружает файл .xlsx.

3. Получает обратно .zip с тремя готовыми таблицами.

Ничего не устанавливается на чьей-либо машине: обработка выполняется на сервере, а результат возвращается через браузер. Форма публикуется через поток n8n, который сопровождает проект в integracoes/, импортируется один раз. Кто не использует n8n, потребляет API напрямую — контракт описан в том же руководстве.

Чтобы попробовать без подготовки данных, в репозитории есть exemplo/pedidos_exemplo.xlsx: 50 записей, из которых 10 содержат характерные дефекты.

Первый запуск дня. Сервис размещён на бесплатном тарифе и засыпает после нескольких минут без использования. Первый вызов занимает около 50 секунд, чтобы разбудить сервер; последующие отвечают менее чем за 1 секунду. Если поток сообщает о тайм-ауте при первой попытке, просто повторите.

Правила валидации

Каждая запись проверяется по всем правилам. Запись может накапливать несколько причин, объединённых в столбце motivo_rejeicao — полный список проблем сразу, а не одна ошибка за повторную обработку.

Имена полей выше относятся к исходному домену (заказы). mapa_colunas из config.yaml переводит заголовки любого экспорта в эти имена, поэтому таблица из другой системы не требует нового кода.

Приоритет

Одобренные получают dias_restantes и попадают в очередь, отсортированную по срочности — сначала самые срочные. Диапазоны (названия, интервалы и цвета) находятся в config.yaml.

Что выдаётся

Стек

Python 3.10+.

Измеренный результат

Демонстрационный пакет: 50 записей, с 10 реальными проблемами.

Числа выше получены при выполнении над exemplo/pedidos_exemplo.xlsx (синтетические данные), измерены локально. Это не прогноз реального производственного объёма.

Что ИИ исправил в реальном выполнении

Что она правильно не решила

Из 10 отклонённых 5 остались — и так и должно быть:

• 2 дубликата — требуют человеческого решения о том, какая запись действительна.

• 1 просроченный срок — это не ошибка данных, а операционная проблема.

• 2 несогласованных значения — ИИ скорректировал количество, но valor_total не сошёлся, поэтому запись осталась отклонённой. Валидация не делает исключений для ИИ.

Слой ИИ — восстановление отклонённых записей

Отклонить запись — это решить половину проблемы. Вторая половина — восстановить её, когда ошибка в заполнении, а не в содержании. Разделение труда явное:

• Механическая ошибка (не сходящееся значение, лишний пробел, email, требующий нормализации) → решается правилом, без ИИ.

• Семантическая ошибка (отсутствующее имя, неполный email) → ИИ выводит, сопоставляя другие поля самой записи.

• Невозможные для вывода данные → помечаются для ручной проверки, никогда не выдумываются.

Траектория аудита

Автоматическое исправление надёжно только тогда, когда его можно проверить. ИИ подписывает то, что сделал, внутри выдаваемых таблиц:

• Столбец corrigido_por_ia отмечает восстановленные записи.

• Столбец correcao_ia фиксирует «до → после» для каждого изменённого поля.

• В сводке есть строка «Записи, восстановленные ИИ».

Вывести имя из email — это правдоподобное предположение, а не подтверждённый факт. Поэтому траектория существует: ИИ ускоряет восстановление, а окончательное решение остаётся проверяемым человеком.

Архитектура

Одна ответственность на модуль — каждый файл делает одно дело и тестируется изолированно.

Единый источник истины. Поток живёт в executar_pipeline; метрики собираются один раз и переиспользуются отчётом, логом и API. Названия, порядок и цвета диапазонов приоритета существуют только в config.yaml.

Способы потребления

Одна логика валидации, три интерфейса — без дублирования правил.

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, плюс подсказка-промпт. Два средних образуют цикл ассистируемой коррекции: модель самого клиента предлагает исправления, а сервер повторно проверяет.

Интеграция не привязывает к инструменту: будучи чистым HTTP, Make, Power Automate или собственный код используют тот же API. n8n — это документированный и протестированный путь.

Настройка без кода

Бизнес-правила находятся вне кода, в config.yaml: допустимое отклонение значения, шаблон электронной почты, обязательные столбцы и диапазоны приоритетов (названия, интервалы и цвета). Менеджер корректирует лимиты, не открывая Python.

mapa_colunas переводит заголовки реального экспорта в ожидаемые имена — это точка смены домена: другая таблица, та же логика.

Отсутствующая или недействительная конфигурация ничего не ломает: система предупреждает и использует встроенные значения по умолчанию.

Тесты

testar.py выполняет 13 проверок сквозного тестирования, без внешнего фреймворка — это скрипт, который запускает реальный поток и проверяет инварианты:

• генерация примерной таблицы и выполнение конвейера;

• наличие и содержимое 3 таблиц и журнала;

• согласованность (одобренные + отклонённые = всего);

• наличие причины у всех отклонённых;

• API (валидация, загрузка пакета, отказ от таблицы не в том формате с понятной ошибкой);

• MCP-сервер, проверяемый через реальный протокол: рукопожатие, каталог инструментов и один инструмент, выполненный от начала до конца.

Другие встроенные меры защиты: открытый в Excel отчёт обрабатывается с повторными попытками и понятным сообщением; некорректное исправление от ИИ отбрасывается без сбоя пакета; временные файлы сервера автоматически истекают через 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

Чтобы поместить реальную таблицу, сохраните её в data/pedidos_entrada.xlsx перед запуском main.py.

Переменные окружения (необязательные)

У всех есть значения по умолчанию; ни одна не обязательна для валидации. ИИ-коррекция включается только при наличии ключа.

Ключ никогда не хранится в репозитории — только в окружении сервера.

Ограничения и следующие шаги

Объём этой поставки. API опубликован без аутентификации, по решению об объёме. URL следует использовать только с демонстрационной таблицей (синтетические данные); реальные записи содержат персональные данные и требуют аутентификации по ключу перед передачей через открытый URL. Это осознанный шаг в дорожной карте, а не упущение.

Что сломается при большем масштабе. Обработка синхронная и загружает всю таблицу в память (pandas) — подходит для пакетов в тысячи строк, а не в миллионы. Обнаружение дубликатов смотрит только внутри текущего пакета, а не между выполнениями.

Естественная эволюция. Читать записи напрямую из источника (ERP, база данных) вместо таблицы; записывать статус обратно в исходную систему; активное уведомление при росте доли отклонений; история между пакетами для обнаружения дубликатов, пересекающих выполнения.

Происхождение проекта

Этот проект родился как бизнес-кейс для отбора на стажировку по RPA в GoCase (GoGroup), отдел операций фабрики. Исходная область — валидация заказов на производство по требованию, где каждая повреждённая запись превращается в потраченный персонализированный материал и потерянное машинное время.

Документация была обобщена, потому что решение — автоматическая проверка табличных записей, поступающих с ошибками, с восстановлением того, что является ошибкой заполнения, а не содержания — применимо к любому потоку такого типа. Словарь заказов остаётся в правилах и примерах, потому что это реальный измеренный случай, а не потому что он единственно возможный.