Uma operação que modifica centenas de registros pode estar correta segundo suas regras e, ainda assim, afetar mais dados do que o esperado. Uma confirmação genérica — «Tem certeza?» — não permite avaliar o alcance nem detectar condições inesperadas. Uma prévia de alterações em PHP deve mostrar quais registros seriam afetados, quais valores mudariam e em que condições a operação poderia ser executada.
A prévia reduz surpresas, mas não garante que a execução posterior produzirá exatamente o mesmo resultado. Entre as duas fases, os dados, as permissões ou o alcance da operação podem mudar. O design deve tornar essa incerteza visível e validar novamente o que for necessário antes de gravar.
Quando uma prévia agrega valor
Vale considerar uma prévia para operações em massa, sensíveis ou difíceis de reverter: atualizar preços, alterar estados, reatribuir contas, eliminar informações ou recalcular dados derivados. Ela também é útil quando a pessoa que inicia a tarefa precisa analisar seu impacto ou obter aprovação antes de executá-la.
Nem todas as ações precisam de uma interface de prévia. Se uma operação for pequena, reversível e tiver um resultado inequívoco, uma confirmação contextual pode ser suficiente. Por outro lado, se o usuário não consegue saber o que significa confirmar, o problema exige a exibição de dados concretos, não a adição de outra caixa de diálogo.
A prévia também não substitui um backup, um mecanismo de reversão nem uma política de aprovação. Se um erro puder ter consequências graves, é preciso avaliar controles adicionais, como a aprovação por outra pessoa, uma execução gradual ou um processo de recuperação testado.
Separar o cálculo da aplicação
A regra de negócio deve ser capaz de calcular uma proposta sem modificar o banco de dados. Uma estratégia prática é compartilhar a seleção e o cálculo entre dois modos: um que descreve a alteração e outro que a aplica. Evitar duas implementações independentes reduz o risco de a prévia e a execução interpretarem regras diferentes.
A proposta pode incluir, para cada item afetado:
- Um identificador que permita reconhecer o registro.
- Os valores atuais relevantes e os valores esperados.
- O motivo pelo qual o item foi incluído ou excluído.
- As validações realizadas e os conflitos detectados.
- O escopo da operação, como filtros, conta ou intervalo de tempo.
Por exemplo, uma operação para alterar o estado de pedidos pode mostrar o estado atual, o estado proposto e o motivo da elegibilidade. Se houver itens demais para exibir todos na tela, é possível apresentar totais e uma amostra, sempre esclarecendo o que está sendo mostrado e permitindo inspecionar ou exportar os detalhes quando necessário.
Em PHP, é recomendável encapsular a seleção e o cálculo em componentes com responsabilidades claras. Um serviço de domínio pode produzir as alterações propostas; outro componente pode apresentá-las; e uma rota de aplicação pode se encarregar de validá-las e persistir os dados. A prévia não deve executar indiretamente uma gravação por efeitos colaterais da leitura.
Validar dados, permissões e escopo
Uma proposta útil explica não apenas o que mudaria, mas também por que a alteração pode ser feita. Valide as condições de negócio com base nos dados atuais e verifique se o usuário tem permissão para visualizar e executar a operação. Ter permissão para consultar registros não implica necessariamente ter permissão para modificá-los.
O escopo deve ficar explícito. Se a ação depender de filtros, de uma seleção ou do carregamento de um arquivo, registre esses parâmetros de forma compreensível e comunique limites, exclusões e erros. Evite que uma busca ampla ou um filtro omitido transforme acidentalmente uma ação limitada em uma modificação global.
Também é preciso indicar o que não pode ser previsto com certeza. A prévia não antecipa automaticamente alterações feitas por outros processos, regras executadas em sistemas externos nem efeitos colaterais que dependam do estado futuro. Se houver integrações, filas ou cálculos posteriores, descreva esses efeitos separadamente e não os apresente como parte confirmada do resultado.
Evitar aplicar uma proposta obsoleta
Uma prévia representa os dados em um momento específico. Se eles mudarem antes da execução, um pedido pode deixar de atender às condições, um usuário pode perder permissões ou um registro pode ser atualizado por outro processo. Por isso, o resultado exibido não deve ser tratado como uma autorização permanente para gravar.
Ao executar, verifique novamente as condições que determinam a elegibilidade e as permissões. Conforme o caso, você pode comparar uma versão do registro, uma marca temporal ou os valores relevantes com os observados durante o cálculo da proposta. Se houver divergências, não aplique silenciosamente uma decisão diferente: informe o conflito e solicite a geração de uma nova prévia ou a resolução explícita do problema.
Em processos que exigem correspondência estrita, mantenha uma referência à proposta e valide se a aplicação continua usando o escopo e as regras dela. Uma transação pode proteger um conjunto de gravações contra falhas intermediárias, mas não elimina, por si só, o tempo decorrido entre a prévia e a execução. A estratégia de concorrência deve corresponder ao risco e ao volume da operação.
Executar em lotes e registrar resultados
Para grandes volumes, aplicar tudo em uma única operação pode aumentar o tempo de bloqueio e dificultar a recuperação. Defina limites de lote adequados ao banco de dados e ao comportamento da aplicação. Se houver falhas parciais, o usuário deve conseguir distinguir os registros aplicados, os ignorados e os que precisam de revisão.
Registre informações suficientes para investigar o resultado: quem iniciou e aprovou a operação, quando ela foi preparada e executada, qual escopo foi solicitado, quantos itens foram processados e quais erros ocorreram. Evite armazenar dados pessoais ou valores sensíveis sem necessidade; os registros de auditoria também devem respeitar os controles de acesso e retenção aplicáveis.
Se a operação for repetida, considere a idempotência: repetir uma solicitação não deve duplicar efeitos inesperados. Um identificador de operação e estados de execução podem ajudar a reconhecer solicitações repetidas e separar preparação, aprovação, execução e conclusão. Não apresente a implantação do código como equivalente a liberar ou habilitar a operação: são decisões distintas e devem ter controles próprios.
Testar se a prévia não modifica os dados
Os testes devem verificar tanto o cálculo quanto a ausência de gravações no modo de prévia. Use dados representativos para verificar inclusões, exclusões, valores atuais e propostos, permissões insuficientes e validações com falha.
Verifique também se a execução aplica a proposta esperada e se as alterações concorrentes produzem o comportamento definido. Teste falhas dentro de um lote, novas tentativas e erros de integração, quando aplicável. Os testes de integração com o banco de dados são importantes: um teste unitário do cálculo não demonstra que uma rota de prévia não tem efeitos colaterais.
Os casos-limite devem incluir filtros vazios, grandes volumes, registros apagados ou modificados entre as fases e usuários com diferentes escopos de acesso. Também convém verificar se a interface não afirma «exatamente estes itens serão atualizados» quando a aplicação voltar a calcular o conjunto.
Lista de verificação para decidir o controle necessário
- A operação afeta muitos registros, tem efeitos difíceis de reverter ou exige aprovação?
- O escopo, os itens afetados e os valores atuais e esperados são exibidos?
- A prévia está separada das gravações e de seus efeitos colaterais?
- As permissões, as regras de negócio e os dados são validados tanto na preparação quanto na execução?
- As alterações relevantes ocorridas entre as duas fases são detectadas?
- Há limites de lote, tratamento definido para falhas parciais e registros de auditoria adequados?
- Os testes confirmam que a prévia não modifica os dados e que a execução respeita o resultado validado?
Uma prévia é adequada quando ajuda a tomar uma decisão informada e seus limites estão claros. Se não for possível oferecer uma estimativa confiável do impacto, é preferível reduzir o escopo, executar primeiro em um ambiente controlado ou exigir uma revisão adicional, em vez de transformar um número ou uma lista parcial em uma promessa de resultado.
