Uma automação pode chegar a um ponto em que não deve avançar sem uma decisão, um dado ou uma verificação. Por exemplo, pode precisar de aprovação antes de confirmar uma operação sensível ou aguardar informações que só uma pessoa pode fornecer. Nesses casos, o sistema deve preservar um estado recuperável e explicar o que está faltando, em vez de simplesmente interromper a execução atual.
Projetar como pausar e retomar uma automação em PHP implica separar o estado do processo da execução do trabalho. A pausa deve ser intencional, persistente e auditável; a retomada deve verificar se o processo continua válido e se os efeitos já aplicados não serão repetidos. Isso é diferente de projetar uma fila de revisão: aqui, o foco está no ciclo de vida do fluxo e em sua continuação segura.
Diferencie pausa, espera e falha
Nem todo processo que não avança está pausado. Uma chamada a uma API que ainda não respondeu é uma espera externa. Um erro de rede pode justificar uma nova tentativa. Uma exceção irrecuperável pode encerrar o processo como falha. Uma pausa deliberada, por outro lado, significa que o fluxo chegou a um limite conhecido e requer uma condição explícita para continuar ou terminar.
Usar um estado distinto para cada situação evita decisões operacionais equivocadas. Tentar novamente uma ação que aguarda aprovação pode repetir uma solicitação desnecessária; tratar uma pausa legítima como falha pode acionar alertas ou políticas de recuperação inadequadas. Defina, no mínimo, estados separados para execução, espera externa, intervenção necessária, concluído, cancelado e com falha. Adicione uma expiração se o negócio exigir que uma pausa deixe de ser válida após determinado prazo.
Antes de incorporar uma pausa, especifique o que a provoca e quem pode resolvê-la. Uma tarefa pendente que é concluída automaticamente quando chega uma resposta nem sempre exige intervenção humana. Já uma decisão com impacto financeiro, jurídico, de acesso ou de segurança pode exigir essa intervenção. Essa distinção determina quem pode agir, quais evidências devem ser armazenadas e o que acontece se ninguém responder.
Persista o estado e o ponto de continuação
O processo deve sobreviver ao fim da requisição PHP, à reinicialização de um worker e a uma nova versão do serviço. Armazene de forma persistente um identificador estável, o estado atual, a etapa alcançada, o motivo da pausa, as referências aos dados necessários e os registros de data e hora relevantes. Quando aplicável, registre também quem pausou ou resolveu o processo e qual decisão foi tomada.
Evite armazenar apenas uma mensagem como “aguardando aprovação”. Ela não identifica qual execução está parada, qual etapa deve continuar nem se os dados foram alterados. Em vez disso, represente a pausa como parte do modelo do processo, com contexto suficiente para validar a retomada. Sempre que possível, mantenha referências a informações sensíveis, em vez de duplicar dados sem necessidade; aplique controles de acesso e retenção adequados à natureza dessas informações.
Defina as transições permitidas e valide-as no servidor. Por exemplo, um processo no estado de intervenção necessária pode passar para execução, cancelado ou expirado; um processo concluído não deve voltar à execução por meio de uma requisição comum. Uma função PHP pode validar a transição, mas a regra também deve estar protegida contra concorrência no banco de dados, e não apenas na interface.
Separe o registro do processo da execução
Registrar que o processo deve continuar e executar suas etapas são operações relacionadas, mas não idênticas. Se o estado for atualizado e o processo terminar antes do início do trabalho, o fluxo pode ficar travado. Se o trabalho começar antes de a transição ser salva, uma repetição pode executar a mesma etapa. Projete a coordenação de modo que o estado persistente permita recuperar o trabalho pendente.
Uma opção comum é salvar a transição e uma instrução de continuação na mesma transação de banco de dados, por exemplo, usando um padrão de saída transacional. Um worker separado lê essa instrução e executa a etapa seguinte. A escolha específica depende da arquitetura; o importante é que o sistema consiga detectar o trabalho ainda não consumido e recuperá-lo, em vez de confiar que uma requisição web permanecerá ativa.
Os efeitos externos exigem atenção adicional. Uma transação local não pode desfazer, por si só, um e-mail enviado, uma cobrança confirmada ou uma chamada já aceita por outro serviço. Projete cada etapa com uma chave de idempotência quando o destino permitir, registre o resultado antes de avançar e considere reconciliação ou compensação quando uma operação não puder ser repetida com segurança. Não marque uma etapa como concluída antes de saber qual foi o resultado.
Controle a retomada, o cancelamento e a expiração
A ação de retomada deve verificar o estado vigente, a identidade e as permissões de quem solicita a operação, além de confirmar que as condições necessárias foram atendidas. Não basta exibir um botão para uma pessoa autorizada: o servidor deve validar tudo novamente ao receber a solicitação. Se a decisão exigir uma justificativa ou um dado adicional, valide e preserve essas informações como parte da resolução.
Trate também o cancelamento e a expiração como transições explícitas, e não como exclusão do registro. O cancelamento deve impedir novas etapas e deixar claro se existem efeitos anteriores que não podem ser revertidos. A expiração deve definir o que acontece em seguida: encerrar o processo, solicitar uma nova intervenção ou encaminhar o caso para outra ação. O comportamento depende da regra de negócio e deve ser visível para a equipe de operações.
Solicitações repetidas e condições de corrida são normais: uma pessoa pode clicar duas vezes, ou dois atores podem agir quase ao mesmo tempo. Use uma atualização condicional, um bloqueio ou um controle de versão para que apenas uma transição válida seja efetivada. Uma segunda solicitação deve receber um resultado coerente com o estado atual, sem executar os efeitos novamente. Armazene um identificador de operação ou uma chave de idempotência para reconhecer repetições.
Faça com que a pausa seja compreensível e verificável
A interface operacional deve explicar por que o processo está parado, qual etapa está pendente, quais informações faltam, quem pode agir e quais são as consequências de cada opção. Evite botões ambíguos ou ações que combinem aprovar, corrigir dados e continuar. Apresente apenas as informações necessárias para a decisão, com acesso limitado de acordo com a função. Um histórico de transições permite diferenciar uma espera legítima de um processo bloqueado ou configurado incorretamente.
Teste o fluxo com interrupções antes e depois de cada efeito externo. Verifique se uma reinicialização não perde a pausa, se uma retomada repetida não duplica ações e se um cancelamento impede as etapas posteriores. Inclua casos de dados alterados durante a pausa, permissões revogadas, expiração, respostas tardias e duas solicitações simultâneas. Verifique também os logs e alertas: eles devem permitir localizar o processo e entender a próxima etapa sem expor segredos.
Lista de verificação para decidir o comportamento
- Aguardar: há uma resposta externa em andamento e o sistema pode continuar automaticamente quando ela chegar, com limites de tempo e recuperação definidos.
- Pausar para intervenção: é necessária uma decisão ou um dado humano explícito antes da execução das etapas seguintes.
- Tentar novamente: ocorreu uma falha transitória e a repetição da etapa é segura ou está protegida por idempotência.
- Encerrar: não há uma continuação válida, ou o processo foi concluído, cancelado, expirou ou falhou definitivamente.
Antes de implantar o fluxo, confirme que cada transição está autorizada, que o estado persiste, que os efeitos anteriores não se repetem e que a equipe sabe como resolver a pausa. Se você não consegue responder o que será retomado, com quais dados e sob quais condições, o processo ainda não tem um ponto de continuação seguro.
