표 형식 레코드 검증기

레코드 수집과 이를 소비할 시스템 사이의 품질 필터 역할을 하는 자동화 도구입니다. 스프레드시트를 읽고, 불일치 항목을 각각의 거부 사유와 함께 차단하며, 긴급도 기준으로 유효한 레코드의 우선순위를 정하고, 차단된 레코드를 AI로 자동 복구까지 시도합니다.

원래 사례는 공장 주문(주문 생산)이지만, 이 로직은 불일치 상태로 도착하여 진행 전에 검수가 필요한 모든 표 형식 레코드 집합(수입, 등록, 시스템 간 통합)에 적용됩니다. 비즈니스 규칙은 config.yaml에 있으며, 도메인을 바꾸는 것은 코드가 아닌 YAML 편집입니다.

서비스 URL: https://validador-pedidos-gocase.onrender.com

문제

여러 출처에서 레코드가 시스템으로 유입될 때마다 각 출처는 서로 다른 방식으로 입력을 검증하거나, 아예 검증하지 않습니다. 그 결과 완벽한 레코드와 필수 필드가 비어 있거나, 이메일이 깨져 있거나, 숫자가 0이거나, 합계가 맞지 않거나, 날짜가 과거이거나, 중복된 레코드가 공존하는 배치가 만들어집니다.

이를 수동으로 확인하는 것은 느리고 지루하며 미묘한 오류(몇 센트 차이, 수십 줄 떨어진 중복)를 놓치기 쉽습니다. 더 나쁜 것은 유효한 레코드가 내용 오류가 아닌 입력 오류(누락된 이름, 이메일에서 사라진 @)로 거부될 수 있다는 점입니다. 올바른 데이터는 존재하지만 형식이 맞지 않게 도착한 것입니다.

원래 사례에서 각 레코드는 물리적 생산 지시가 되는 주문입니다. 데이터가 깨진 주문은 단순히 잘못된 레코드가 아니라, 낭비된 맞춤 자재, 손실된 기계 시간, 제품을 받지 못한 고객을 의미합니다. 잘못된 레코드가 나중에 큰 비용을 초래하는 모든 흐름에서 동일한 패턴입니다.

Related MCP server: fcp-sheets

작동 방식

핵심은 동일한 함수를 호출하는 세 가지 인터페이스(터미널, HTTP API, MCP)로 노출되는 4단계 파이프라인입니다:

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. 준비된 세 개의 스프레드시트가 담긴 .zip 파일을 돌려받습니다.

아무것도 사용자 머신에 설치되지 않습니다. 처리는 서버에서 실행되고 결과는 브라우저로 반환됩니다. 양식은 프로젝트에 포함된 n8n 흐름(integracoes/)으로 게시되며, 한 번만 가져오면 됩니다. n8n을 사용하지 않는 경우 API를 직접 사용합니다. 계약은 동일한 가이드에 있습니다.

데이터를 준비하지 않고 실험하려면 저장소에 exemplo/pedidos_exemplo.xlsx가 포함되어 있습니다. 50개 레코드 중 10개에 대표적인 결함이 있습니다.

하루의 첫 실행. 서비스는 무료 요금제로 호스팅되며 몇 분간 사용이 없으면 절전 모드로 전환됩니다. 첫 번째 호출은 서버를 깨우는 데 약 50초가 걸리고, 이후 호출은 1초 미만으로 응답합니다. 첫 시도에서 흐름이 시간 초과되면 다시 실행하면 됩니다.

검증 규칙

각 레코드는 모든 규칙에 대해 평가됩니다. 레코드는 여러 사유를 누적할 수 있으며, motivo_rejeicao 열에 연결됩니다. 재처리당 오류 하나가 아니라 전체 문제 목록이 한 번에 표시됩니다.

위 필드 이름은 원래 도메인(주문)의 이름입니다. config.yaml의 mapa_colunas는 모든 내보내기의 헤더를 이러한 이름으로 변환하므로 다른 시스템의 스프레드시트에도 새 코드가 필요하지 않습니다.

우선순위

승인된 레코드는 dias_restantes를 받고 긴급도별로 정렬된 큐에 들어갑니다. 가장 촉박한 것이 먼저입니다. 범위(이름, 간격, 색상)는 config.yaml에 있습니다.

제공 결과물

기술 스택

Python 3.10+.

측정된 결과

데모 배치: 50개 레코드, 실제 문제 10개.

위 수치는 exemplo/pedidos_exemplo.xlsx(합성 데이터)에 대한 실행 결과로, 로컬에서 측정되었습니다. 실제 운영 볼륨의 예측이 아닙니다.

실제 실행에서 AI가 수정한 내용

AI가 올바르게 해결하지 않은 것

거부된 10개 중 5개는 그대로 남았으며, 이것이 올바른 방식입니다:

• 중복 2건 — 어떤 레코드가 유효한지 사람의 결정이 필요합니다.

• 기한 초과 1건 — 데이터 오류가 아니라 운영 문제입니다.

• 값 불일치 2건 — AI가 수량을 조정했지만 valor_total이 맞지 않아 레코드는 계속 거부되었습니다. 검증은 AI에 예외를 허용하지 않습니다.

AI 계층 — 거부된 레코드 복구

레코드를 차단하는 것은 문제의 절반을 해결합니다. 나머지 절반은 오류가 내용이 아닌 입력에 있을 때 복구하는 것입니다. 작업 분담은 명시적입니다:

• 기계적 오류(합계 불일치, 여분의 공백, 정규화할 이메일) → AI 없이 규칙으로 해결.

• 의미적 오류(누락된 이름, 불완전한 이메일) → AI가 레코드 자체의 다른 필드를 교차 참조하여 추론.

• 추론할 수 없는 데이터 → 절대 만들어내지 않고 인간 검토용으로 표시.

감사 추적

자동 수정은 감사 가능할 때만 신뢰할 수 있습니다. AI는 제공된 스프레드시트 내에서 수행한 작업에 서명합니다:

• corrigido_por_ia 열은 복구된 레코드를 표시합니다.

• correcao_ia 열은 각 변경 필드의 이전 → 이후를 기록합니다.

• 요약에는 "AI로 복구된 레코드" 행이 있습니다.

이메일에서 이름을 추론하는 것은 확인된 데이터가 아닌 그럴듯한 추론입니다. 그래서 추적이 존재합니다. AI는 복구를 가속화하고 최종 결정은 계속 사람이 확인할 수 있습니다.

아키텍처

모듈별 단일 책임 — 각 파일은 한 가지 작업을 수행하며 독립적으로 테스트 가능합니다.

단일 진실 소스. 흐름은 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에서 열린 보고서는 재시도와 명확한 메시지로 처리됩니다; 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 인턴십 선발 과정을 위한 비즈니스 케이스로 시작되었으며, 공장 운영 영역입니다. 원래 도메인은 주문형 생산 주문 검증으로, 깨진 레코드 하나가 낭비되는 맞춤 자재와 잃어버린 기계 시간이 됩니다.

문서는 일반화되었습니다. 이 솔루션 — 불일치하게 도착하는 표 형식 레코드의 자동 검증과, 내용 오류가 아닌 입력 오류의 복구 — 은 같은 유형의 모든 흐름에 적용되기 때문입니다. 주문 어휘는 측정된 실제 사례이기 때문에 규칙과 예시에 남아 있으며, 유일하게 적용 가능한 경우이기 때문이 아닙니다.