Uma alteração não está pronta porque funciona numa demonstração, porque um teste manual produziu o resultado esperado ou porque o código chegou ao ramo principal. Esses sinais podem confirmar uma parte da implementação, mas não provam que a alteração é segura, compreensível e operável em produção.
A definição de pronto em projetos PHP deve estabelecer que evidências tornam aceitável uma alteração concreta. Deve abranger o comportamento de negócio, mas também os dados existentes, as tarefas assíncronas, as integrações, as permissões, a observabilidade e a reversão. Assim, evita-se que o produto aceite algo que as operações não conseguem sustentar ou que a tecnologia implemente uma modificação cujos efeitos são difíceis de reparar.
Não confundir aceitação, implementação e operação
Convém separar três estados que frequentemente são condensados num único «feito»:
- Âmbito aceite: verificou-se que a regra de negócio acordada se comporta como esperado nos cenários relevantes.
- Implementação concluída: o código, os testes, a configuração e as alterações de esquema necessárias estão preparados e revistos.
- Alteração operável: pode ser implementada, monitorizada, suportada e, se necessário, limitada ou revertida sem deixar o sistema num estado desconhecido.
Numa aplicação PHP existente, a distância entre estes estados pode ser considerável. Uma nova validação num controlador pode passar numa demonstração, mas bloquear uma automatização que utiliza a mesma API. Uma migração pode ser executada sem erros e, ainda assim, transformar valores que um processo de importação ainda interpreta com a semântica anterior. Uma permissão adicionada na interface pode não ser aplicada a uma rota interna ou a um comando de consola.
A definição não deve transformar-se num ritual uniforme. Deve ser proporcional ao risco: um ajuste visual isolado requer menos evidências do que uma alteração na faturação, nas permissões, nos dados pessoais ou em fluxos com efeitos externos.
Construir uma matriz de critérios consoante o impacto
Antes de desenvolver, classifique a alteração pelas suas superfícies de impacto. Não é necessário atribuir uma pontuação complexa: basta identificar que dimensões mudam e que falha seria inaceitável. Cada dimensão ativa critérios e evidências adicionais.
Negócio e comportamento
Defina regras, exceções e estados limite com exemplos verificáveis. Inclua o que deve ocorrer perante dados incompletos, pedidos repetidos, concorrência e erros previsíveis. Se uma regra substituir outra, especifique a partir de quando se aplica e o que acontece aos registos criados sob a regra anterior.
Dados e esquema
Se existirem migrações, novos campos, recálculo de informação ou importações, determine o volume afetado, a compatibilidade temporal entre versões da aplicação e do esquema e a validação posterior. Uma migração concluída não equivale a dados corretos: é necessário verificar contagens, valores inválidos, duplicados, nulos inesperados e a preservação de relações relevantes.
Integrações e processos assíncronos
Queues, cron, webhooks, emails, armazenamento de ficheiros e APIs externas requerem critérios próprios. Documente contratos de entrada e saída, tentativas, idempotência, tempos de espera, tratamento de respostas parciais e destino dos erros. Em PHP, um comando de consola ou um worker pode utilizar serviços e credenciais diferentes dos de um pedido web; o teste deve abranger essa execução realista.
Permissões, segurança e privacidade
Indique quem pode ver, criar, aprovar, modificar ou exportar cada recurso. A autorização deve ser verificada no servidor, não apenas através da visibilidade de um botão. Se estiverem envolvidos dados pessoais ou segredos operacionais, inclua minimização de registos, restrições de acesso e revisão de que informação aparece em erros, traces e notificações.
Operação e implementação
Determine como será detetada uma falha após a implementação: registos com contexto, métricas existentes, alertas aplicáveis ou verificações manuais concretas. Distinga implementação de release: a primeira instala artefactos e configuração; o segundo expõe o comportamento a utilizadores ou processos. Quando possível, uma configuração, uma ativação gradual ou uma condição de negócio pode permitir limitar a exposição sem a confundir com uma reversão completa.
Que evidências devem acompanhar a alteração
Uma lista de pronto é útil se solicitar provas observáveis, e não fórmulas vagas como «validado» ou «documentado». A evidência deve poder ser revista por quem aceita a alteração e ser útil durante um incidente.
- Testes automatizados: casos unitários para regras isoladas, testes de integração para persistência, autorizações e serviços, e testes end-to-end apenas onde forneçam cobertura real do fluxo.
- Verificação de aceitação: cenários de negócio executados com entradas, resultados e funções identificadas, incluindo os casos de rejeição.
- Resultado da migração: plano de execução, validações anteriores e posteriores, contagens esperadas e tratamento explícito de anomalias.
- Contrato de integração: alterações em campos, códigos de erro, autenticação, limites, tentativas e compatibilidade com consumidores existentes.
- Verificação operacional: que registo, métrica ou consulta permite confirmar que o fluxo funciona após a implementação e quem deve revê-lo.
- Guia de suporte: sintomas conhecidos, identificadores a procurar, ações seguras e escalonamento. Deve ser breve e acessível, e não documentação genérica que não ajuda sob pressão.
Nem toda a evidência tem de ser um documento independente. Um conjunto de testes, uma nota de implementação e uma consulta de validação podem ser suficientes se forem precisos, localizáveis e mantidos junto da alteração.
Critérios mínimos e critérios reforçados
Para uma alteração de baixo risco, sem modificação de dados, interfaces externas ou permissões, o mínimo inclui geralmente âmbito aceite, revisão do código, testes relevantes, configuração identificada e uma verificação posterior à implementação. Mesmo aqui, deve ficar claro o que é considerado comportamento correto.
Adicione controlos reforçados quando existir qualquer uma destas condições:
- São criados, transformados ou eliminados dados persistentes.
- É modificada uma regra com impacto económico, contratual ou de conformidade.
- São alteradas funções, permissões, autenticação ou exposição de informação.
- São enviados efeitos para sistemas externos, como cobranças, emails ou webhooks.
- A alteração afeta workers, queues, tarefas agendadas ou processos que se podem repetir.
- A implementação exige coordenação entre aplicação, base de dados, infraestrutura ou fornecedores.
Nestes casos, inclua compatibilidade entre versões, plano de implementação ordenado, validações de dados, teste de falhas previsíveis, observabilidade, responsáveis pela decisão e plano de contenção. A pergunta útil não é «existem testes?», mas sim «que evidência reduziria o risco específico desta alteração?».
Reversão: recuperar o controlo, não fingir que nada aconteceu
Uma reversão realista depende dos efeitos produzidos. Reverter código pode ser simples; reverter uma migração destrutiva, um email enviado ou uma atualização aceite por uma API externa não o é. Por isso, o critério deve distinguir entre reverter a execução futura, compensar efeitos já emitidos e corrigir dados.
Antes do release, defina o limiar que obrigaria a agir, quem pode tomar a decisão e que ações são seguras. Uma flag de configuração pode interromper novas execuções. Uma queue pode ser pausada para evitar mais efeitos. Uma correção compensatória pode exigir revisão humana antes de modificar registos já processados. Se não existir uma reversão automática segura, declare-o e prepare um procedimento de recuperação com limites claros.
Um plano de reversão válido identifica os efeitos irreversíveis, a forma de os conter e a evidência necessária para saber que a contenção funcionou.
Exemplo: uma nova aprovação num backoffice PHP
Suponha que um backoffice incorpora uma regra: determinados pedidos devem ser aprovados por uma função específica antes de passarem à execução. A demonstração pode mostrar que surge um botão e que o estado muda para «aprovado». Isso não basta.
A definição de pronto deve esclarecer o modelo de estados: que pedidos requerem aprovação, o que acontece aos já existentes, se uma aprovação pode ser revogada e se duas pessoas podem agir ao mesmo tempo. Deve verificar-se que o serviço de domínio, os controladores, as rotas de API e os comandos de consola aplicam a mesma autorização. Também deve verificar-se que um worker não executa pedidos pendentes sem aprovação por utilizar uma consulta antiga.
Se for adicionado um campo de estado, a migração necessita de uma regra para classificar os registos históricos e de uma verificação posterior das contagens. Os registos de auditoria devem preservar ator, momento, transição e motivo quando aplicável, evitando incluir informação sensível desnecessária. As operações precisam de saber como detetar pedidos bloqueados à espera de aprovação e como interromper o processamento se surgir uma transição incoerente. A reversão poderia desativar a exigência para novos pedidos, mas não deveria eliminar aprovações já registadas sem uma decisão explícita.
Integrar os critérios no ciclo de entrega
A definição de pronto não deve ser redigida no fim como uma lista para encerrar uma tarefa. Durante o refinamento, produto e tecnologia identificam regras, dependências, dados afetados e consequências operacionais. Antes de desenvolver, acordam os cenários de aceitação e as evidências exigidas. Durante a implementação, essas evidências orientam testes, migrações, instrumentação e documentação mínima. Antes da implementação, confirma-se que a ordem de execução, os responsáveis e a contenção continuam válidos.
Evite três antipadrões: listas genéricas que ignoram o risco; critérios descobertos quando a alteração já está pronta para implementar; e documentação extensa sem sinais acionáveis para suporte. Uma boa definição de pronto em projetos PHP não acrescenta burocracia por defeito. Torna explícito o que deve ser verdade para que uma alteração possa operar em segurança depois de a demonstração ter terminado.
