Uma importação empresarial não deveria obrigar a escolher entre cancelar um lote inteiro por causa de uma linha defeituosa ou incorporar dados duvidosos. A quarentena de dados em importações PHP oferece uma terceira opção: aceitar os registros válidos, isolar os que exigem atenção e conservar contexto suficiente para resolvê-los com segurança.
A quarentena não é simplesmente uma pasta de erros nem uma tabela para guardar linhas com falha. É um fluxo operacional com regras de classificação, estados explícitos, correção controlada e novas tentativas que não repetem efeitos. Para projetá-la, convém primeiro definir o que significa «válido» para o negócio e quais ações cada função pode executar.
Classifique os erros antes de decidir o que fazer com cada linha
Uma importação costuma combinar verificações distintas. Separá-las permite explicar o resultado e decidir se o registro pode prosseguir, deve ser rejeitado ou precisa de revisão humana.
- Validação estrutural: verifica o formato e o conteúdo básico: colunas presentes, tipos de dados, datas interpretáveis, campos obrigatórios e limites razoáveis. Um arquivo ilegível pode impedir o processamento do lote; uma data inválida em uma única linha normalmente não deveria fazê-lo.
- Regras de negócio: verificam condições do domínio, como um preço não negativo, um cliente ativo ou uma categoria permitida. Algumas violações podem ser rejeitadas; outras podem depender de uma decisão operacional.
- Conflitos com dados existentes: detectam, por exemplo, um identificador externo já associado a outro registro ou uma atualização baseada em uma versão obsoleta. Nem sempre são resolvidos com a correção do arquivo: podem exigir conciliação ou revisão.
Defina uma política para cada tipo de erro. A ausência de um campo opcional pode permitir um valor padrão; uma identidade ambígua não deveria ser resolvida escolhendo arbitrariamente um registro. Evite tanto regras permissivas demais quanto classificar todo defeito como erro fatal. A decisão deve refletir o impacto de aceitar o dado e o custo de interromper o lote.
Modele estados e transições explícitos
Use estados com significado operacional, em vez de inferir a situação a partir de campos vazios ou mensagens de texto. Um modelo inicial pode incluir pending, accepted, rejected e needs_review. Adicione estados como processing ou resolved somente se corresponderem a transições reais do seu fluxo.
Documente o que cada transição permite. Por exemplo, uma linha pendente é validada; se passar pelas regras, é aceita; se apresentar um conflito que pode ser analisado, fica pendente de revisão. Uma linha corrigida pode ser validada novamente, mas uma linha aceita não deveria ser processada outra vez como se fosse nova. Registre o estado do lote separadamente: um lote pode terminar com linhas aceitas e outras em quarentena, portanto «concluído parcialmente» descreve melhor o resultado do que um único indicador de sucesso ou fracasso.
Os estados devem corresponder a decisões verificáveis. «Rejeitada» deveria significar que a alteração de negócio não foi aplicada; «requer revisão» indica que uma pessoa precisa tomar uma decisão. Se for permitido substituir dados existentes, especifique quem pode fazê-lo e sob quais condições.
Conserve o original e explique cada decisão
Guarde a entrada original da linha e, separadamente, seus valores normalizados e o resultado da validação. Essa separação permite investigar discrepâncias — por exemplo, diferenças entre uma data recebida e sua interpretação — sem transformar a versão convertida na única evidência disponível.
Uma estrutura de persistência pode incluir um identificador do lote, número da linha, origem, referência do arquivo, conteúdo original, estado, erros detectados, datas de criação e resolução e responsável pela ação. Registre os motivos como códigos estáveis e mensagens legíveis: um código como customer_id_ambiguous ajuda a filtrar e medir casos; a mensagem deve explicar qual dado precisa ser verificado. Evite depender de texto livre como única lógica de classificação.
Conserve também o contexto necessário para reproduzir a análise: versão ou identificador das regras utilizadas, identificador externo e dados relevantes para o conflito. Não armazene segredos nem dados pessoais desnecessários em registros técnicos. Defina controles de acesso e um período de retenção compatível com a sensibilidade e as obrigações aplicáveis. Se o arquivo completo puder conter informações desnecessárias para resolver uma linha, limite sua exposição.
Corrija e tente processar novamente sem duplicar efeitos
Uma nova tentativa segura começa por distinguir a linha da tentativa de processá-la. Atribua uma identidade estável a cada linha dentro do seu escopo, por exemplo, uma combinação de lote e índice da linha ou uma chave externa validada. Em importações repetíveis, defina também uma chave de idempotência que permita reconhecer a mesma operação. A escolha depende de o mesmo arquivo, quando carregado novamente, dever atualizar os dados, ser ignorado ou criar uma nova versão.
Ao processar uma linha, aplique a gravação de negócio e a alteração de estado de forma atômica, quando possível: ambas as operações são confirmadas juntas ou nenhuma delas é. Em PHP, uma transação de banco de dados pode proteger alterações que usam a mesma conexão; por si só, ela não torna atômica uma chamada a uma API externa. Para efeitos externos, use uma estratégia compatível com o sistema receptor, como chaves de idempotência, uma tabela de saída transacional ou uma compensação projetada para o caso.
Após uma correção, execute novamente as validações pertinentes e conserve o histórico anterior. Não apague o erro original: adicione uma nova tentativa com seu resultado. Se as regras ou os dados de referência mudarem, indique qual versão foi aplicada e evite que uma repetição altere silenciosamente uma decisão já aceita. A nova tentativa deve afetar somente os registros selecionados e não executar novamente o lote inteiro de forma indiscriminada.
Projete uma revisão operacional e auditável
A interface de revisão deve ajudar a tomar decisões, não se limitar a exibir uma exceção técnica. Inclua o valor recebido, o motivo, o campo afetado, o contexto relevante e, quando for seguro, uma sugestão de correção. Permita filtrar por estado, lote, tipo de erro e antiguidade; deixe claro quais linhas já produziram efeitos e quais não.
Registre quem analisou o caso, quando, qual valor foi alterado, a decisão tomada e o motivo. Diferencie a correção feita por um operador de uma transformação automática. Aplique permissões de acordo com as responsabilidades: quem pode importar um arquivo não necessariamente deve poder aprovar conflitos ou alterar registros aceitos. Para alterações de alto impacto, considere uma aprovação adicional.
Evite que a ferramenta facilite a substituição de informações sem aviso. Antes de aceitar uma correção, verifique novamente a unicidade, as permissões e o estado atual do registro. Se outra pessoa tiver alterado o dado desde a detecção do conflito, apresente essa condição para que seja resolvida, em vez de aplicar uma atualização obsoleta.
Teste falhas parciais e recuperação
Os testes devem abranger tanto as regras quanto o comportamento do fluxo. Inclua arquivos com linhas válidas e inválidas misturadas, formatos inesperados, conflitos, erros temporários de banco de dados e novas tentativas repetidas. Verifique se uma linha rejeitada não impede a aceitação das demais, caso essa seja a política acordada, e se uma falha dentro de uma transação não deixa efeitos parciais.
- Processar novamente uma linha com a mesma chave de idempotência não duplica registros nem ações externas.
- Corrigir um campo permite uma nova validação sem apagar o original nem o histórico.
- Uma linha já aceita não é aplicada novamente quando outra linha passa por uma nova tentativa.
- Os conflitos detectados entre a revisão e a resolução não são sobrescritos silenciosamente.
- As mensagens de erro permitem agir sem expor dados sensíveis desnecessários.
Em produção, monitore o volume e a antiguidade dos registros em quarentena, os motivos mais frequentes, a taxa de resolução e as falhas nas novas tentativas. Um aumento sustentado pode indicar uma mudança no sistema de origem, uma regra desatualizada ou instruções de carregamento pouco claras. A quarentena funciona quando torna essas causas visíveis e permite resolvê-las com controle, não quando se transforma em um depósito indefinido de exceções.
