Extração assistida em PHP: aceitar, revisar ou colocar em quarentena

A extração assistida de dados em PHP converte documentos, formulários, e-mails ou registros recebidos em campos estruturados. No entanto, detectar um nome, um valor ou uma data não implica que esse valor possa acionar um pagamento, criar um pedido ou modificar um processo sem intervenção. O resultado da extração é uma proposta: deve ser confrontado com regras de negócio, evidências disponíveis e o impacto de um erro.

Um projeto útil não busca automatizar 100% dos casos desde o primeiro dia. Ele define quais dados podem ser aceitos com segurança, quais exigem uma decisão humana e quais devem ser interrompidos até que haja informações adicionais. Essa separação protege a operação e permite aprimorar o sistema com correções reais, e não com suposições sobre uma pontuação de confiança.

Definir o dado, sua origem e o custo do erro

Antes de escolher um fornecedor, uma biblioteca ou um modelo de IA, descreva cada campo como um objeto de negócio. Não basta indicar que uma data será extraída; é necessário determinar se ela é a data de emissão, vencimento, prestação ou entrega. A ambiguidade semântica é um risco diferente de uma falha de leitura.

• Finalidade: qual processo consumirá o campo e se ele pode iniciar uma ação irreversível.
• Origem: documento original, página, seção, rótulo, coordenadas ou trecho que sustenta o valor.
• Restrições: tipo, formato, obrigatoriedade, intervalo, moeda, catálogo permitido e relações com outros campos.
• Impacto: consequência de aceitar um valor incorreto, ausente ou atribuído ao documento errado.
• Fonte de verificação: sistema mestre, regra contratual, base de fornecedores ou revisão humana que pode confirmar o dado.

Um identificador fiscal pode ter uma expressão formal correta e, ainda assim, pertencer a uma entidade não autorizada. Um total pode ser numérico e positivo, mas não corresponder à soma das linhas, impostos e descontos. Por isso, a validação deve incluir tanto a forma do campo quanto seu significado operacional.

Classifique também a sensibilidade dos dados. Documentos com informações pessoais, financeiras ou contratuais exigem definir quem pode ver o original, por quanto tempo ele é mantido e quais informações são enviadas a serviços externos. A utilidade da automação não elimina as obrigações de minimização e controle de acesso.

Projetar uma saída estruturada e verificável

A extração deve produzir uma estrutura estável, e não texto livre que outro componente precise reinterpretar. O contrato pode incluir o valor normalizado, o valor literal, o estado de presença, a evidência e os avisos detectados. Manter ambos os valores evita ocultar uma transformação relevante: por exemplo, converter 1.250,00 em um decimal depende da convenção identificada.

{
  "invoice_number": {
    "raw": "F-01842",
    "normalized": "F-01842",
    "evidence": {"page": 1, "label": "Fatura"},
    "warnings": []
  },
  "total": {
    "raw": "1.250,00 EUR",
    "normalized": 1250.00,
    "currency": "EUR",
    "evidence": {"page": 1, "label": "Total"},
    "warnings": ["sum_not_verified"]
  }
}

O esquema deve rejeitar campos inesperados, tipos incompatíveis e ausência de campos obrigatórios. Em PHP, uma camada específica pode validar o resultado antes que ele alcance o domínio da aplicação. As regras técnicas incluem formatos, comprimentos e conversões; as regras de negócio incluem duplicidades, períodos permitidos, limites de aprovação e correspondência com registros existentes.

Não trate o percentual de confiança como uma decisão. Sua calibração muda conforme o tipo de documento, a qualidade da imagem, o idioma e o campo. Ele pode ser usado como um sinal adicional, mas não substitui uma verificação como a existência do fornecedor, a plausibilidade da data ou a conferência do total.

Separar aceitação, revisão e quarentena

Os três destinos devem ser estados explícitos do fluxo, com permissões, responsáveis e transições controladas. Não são rótulos visuais sobre uma mesma fila.

• Aceitação automática: é usada quando o esquema é válido, as regras de negócio são atendidas, há evidência suficiente e o risco residual está dentro do limite definido. Deve-se persistir quais regras foram atendidas.
• Revisão humana: é aplicada se o caso é compreensível, mas exige confirmação, como uma discrepância menor, uma baixa confiança localizada ou uma correspondência inconclusiva com um sistema mestre.
• Quarentena: interrompe casos incompletos, potencialmente fraudulentos, duplicados, ilegíveis, incompatíveis com o esquema ou afetados por uma regra crítica. Ela não deve permitir que uma nova tentativa automática transforme um bloqueio deliberado em aceitação.

Uma matriz de decisão prática combina criticidade e verificabilidade. Um campo de baixo impacto pode ser aceito se cumprir o formato e o catálogo. Um dado que determina um pagamento exige também conciliação com o pedido, fornecedor autorizado e cálculo coerente. Se o original estiver ausente, a evidência for contraditória ou for detectada uma possível manipulação, a saída razoável é a quarentena, mesmo que outros campos pareçam corretos.

Fluxo de referência em PHP e persistência segura

Um fluxo robusto separa responsabilidades para que a extração não fique misturada à decisão de negócio. A recepção atribui um identificador imutável, verifica o tipo e o tamanho do arquivo e armazena o original em um local com acesso restrito. Depois, um processo assíncrono prepara o documento, invoca o extrator e valida a resposta em relação ao esquema.

A decisão é tomada com base em dados normalizados e regras determinísticas. O serviço pode retornar um objeto de decisão com o estado, os motivos, os campos afetados e a versão das regras. Somente após essa decisão o registro de negócio é persistido ou uma tarefa de revisão é criada. A idempotência é essencial: um mesmo arquivo ou evento repetido não deve gerar registros ou ações duplicados.

$result = $extractor->extract($document);
$validated = $schemaValidator->validate($result);
$decision = $decisionEngine->decide($validated, $businessContext);
$repository->saveDecision($documentId, $decision);

Ao usar IA, defina o caso de uso de forma delimitada: classificação documental, localização de campos ou interpretação de texto difícil, por exemplo. Avalie a qualidade em um conjunto representativo antes de ativar qualquer automação, mantenha a revisão humana para as hipóteses definidas e limite os dados enviados. Calcule também o custo por documento, a latência tolerável e o comportamento diante de respostas parciais. Uma demonstração convincente não prova que o fluxo seja operável em escala.

Tornar eficazes a revisão humana e a quarentena

A pessoa revisora não deve reconstruir o documento do zero. A interface deve mostrar o valor proposto junto à sua evidência, o original ou um recorte autorizado, as regras não atendidas e as alternativas disponíveis. Deve permitir corrigir, confirmar, rejeitar ou solicitar informações, deixando um motivo estruturado.

Registre a correção como um evento diferente do resultado inicial. Isso permite saber se falhou a leitura, a normalização, uma regra ou o documento de origem. Não use automaticamente toda correção como dado de treinamento: primeiro, revise a qualidade, as permissões, a representatividade e a possível incorporação de dados sensíveis.

A quarentena precisa de um responsável, uma prioridade e um prazo de resolução. As novas tentativas devem ter causa concreta, limite e registro: tentar novamente após uma falha transitória não é o mesmo que reprocessar um arquivo ilegível. Os casos sem resolução devem ser escalados ou encerrados com um motivo explícito, nunca desaparecer da fila.

Rastreabilidade, testes e degradação controlada

Para explicar uma decisão, mantenha o identificador do documento, a impressão digital ou referência do original, a versão do esquema e das regras, o resultado das validações, a evidência mínima por campo, o estado, o ator que revisou e os registros de data e hora. Evite duplicar o documento completo em cada log ou armazenar texto sensível quando um identificador e uma referência segura forem suficientes.

Teste com documentos representativos e casos extremos: páginas giradas, imagens borradas, campos ausentes, múltiplas moedas, rótulos ambíguos, duplicados, formatos regionais e documentos com estrutura inesperada. Meça taxas separadas de extração, validação, aceitação automática, revisão, quarentena, correção humana e tempo de resolução. Uma alta taxa de aceitação não é um sinal positivo se, depois, aumentarem as retificações ou ocorrências.

Defina a degradação antes do deploy. Se o extrator não responder, exceder a latência ou retornar uma estrutura inválida, o documento deve ser mantido e direcionado para uma fila manual ou para um mecanismo alternativo autorizado. Não preencha valores críticos com estimativas silenciosas. Ative alterações de regras ou do extrator gradualmente, compare os resultados e mantenha um caminho de reversão.

Lista de verificação antes de automatizar um campo

• O campo tem uma definição de negócio inequívoca e um consumidor identificado?
• Existem regras de formato, intervalo, catálogo e coerência com outros dados?
• É possível mostrar evidência suficiente para confirmar o valor?
• O impacto de um falso positivo é conhecido e foi definido um limite de risco?
• Há um caminho de revisão, quarentena, novas tentativas limitadas e alternativa manual?
• A rastreabilidade permite explicar a decisão sem reter dados desnecessários?
• Os testes incluem os erros previsíveis e a ativação gradual tem reversão?

Um campo passa de assistência para automação quando demonstra consistência sob essas condições, e não apenas porque um extrator costuma acertar. Assim, o PHP coordena um processo verificável em que a velocidade de processamento não substitui a responsabilidade sobre o dado.