表格记录验证器

一个自动化工具，充当记录采集与消费系统之间的质量过滤器：读取电子表格，拦截不一致的数据并说明每条拒绝的原因，按紧急程度标准对有效数据进行优先级排序，并尝试使用AI 自动恢复被拦截的记录。

原始场景是工厂订单（按需生产），但该逻辑适用于任何以不一致状态到达并需要在继续流转前进行核对的表格记录集——导入、注册、系统间集成。业务规则存放在 config.yaml 中；更换领域只需编辑 YAML，无需修改代码。

在线服务： https://validador-pedidos-gocase.onrender.com

问题

每当记录从多个来源进入系统时，每个来源在入口处的验证方式都不同——或者根本不验证。结果是同一批次中既有完美的记录，也有必填字段为空、邮箱格式错误、数字归零、金额对不上、日期在过去或存在重复的记录。

人工核对既慢又累，还会漏掉细微错误——几分钱的差异、相隔几十行的重复项。更糟的是：一条有效记录可能因为填写错误而非内容错误而被拒绝——漏填的名字、邮箱中消失的 @。正确的数据是存在的，只是没有以正确的格式到达。

在原始场景中，每条记录都是一个会变成实体生产工单的订单。数据损坏的订单不仅仅是错误记录——它是浪费的定制材料、损失机时和未收到货的客户。任何错误记录会在后续流程中付出高昂代价的流水线，都存在同样的模式。

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，为列设置类型并检查预期的 schema。缺失列会变成可读的错误，而不是通用故障。

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 在真实执行中修正的内容

它正确地未解决的内容

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 实习选拔流程的 business case，属于工厂运营领域。原始领域是按需生产订单的验证，其中每条损坏的记录都会变成浪费的定制材料和损失的机器工时。

文档已泛化，因为该解决方案——对到达时不一致的表格记录进行自动核对，并恢复属于填写错误而非内容错误的记录——适用于任何同类流程。订单词汇保留在规则和示例中，因为它是实际测量的案例，而非唯一适用的案例。