Onboarding técnico seguro em PHP legado

O onboarding técnico em aplicações PHP legadas não se resolve com a entrega de uma conta de repositório e credenciais de desenvolvimento. Uma pessoa recém-integrada pode escrever código correto num módulo isolado e, ainda assim, causar uma incidência se desconhecer que processo de negócio protege, que dados são irreversíveis ou como uma alteração se propaga através de filas, tarefas agendadas e integrações.

O objetivo antes da primeira alteração não é documentar toda a aplicação. É reduzir a incerteza até ser possível formular, rever, fazer deploy e reverter uma modificação pequena sem colocar a operação em risco. Isto exige contexto verificável, privilégios proporcionais e um caminho claro para pedir ajuda.

Porque os acessos não bastam para começar

Numa aplicação legada, a lógica relevante raramente reside apenas em controladores, serviços ou templates PHP. Pode estar distribuída entre configurações de ambiente, procedimentos de base de dados, um cron, uma fila, uma regra num fornecedor externo ou uma convenção não escrita da equipa. Também é habitual que uma mesma alteração afete utilizadores com permissões diferentes, processos noturnos, faturação, stock ou comunicações transacionais.

O risco aumenta quando a pessoa externa recebe um pedido aparentemente menor, como adicionar um campo, ajustar uma validação ou modificar um estado. Antes de editar, deve saber se esse dado é replicado, se ativa automatizações, se faz parte de uma exportação ou se tem implicações de privacidade e retenção.

Por isso, o responsável técnico deve converter o conhecimento disperso em decisões operacionais: o que se sabe, como foi verificado, o que continua incerto e quem pode resolver cada dúvida. A incerteza não é um defeito se estiver explícita; o perigoso é tratar uma suposição como um facto.

As 10 perguntas antes da primeira alteração

1. Que propósito de negócio cumpre a área afetada? Identifique a decisão, transação ou serviço que suporta, não apenas o nome do módulo.
2. Quem são os seus utilizadores e que permissões têm? Distinga utilizadores finais, operadores, administradores e processos de sistema.
3. Qual é o fluxo crítico? Descreva o percurso principal e os casos que não podem falhar, como confirmar um pagamento ou registar uma encomenda.
4. Onde estão os limites do domínio? Esclareça que entidade é a fonte de verdade, que estados admite e que invariantes não devem ser quebrados.
5. Que integrações intervêm? Liste APIs, webhooks, e-mail, armazenamento, fornecedores de identidade, gateways de pagamento e exportações.
6. Que dados são lidos, escritos ou derivados? Indique dados pessoais, financeiros, operacionais e campos cuja modificação seja irreversível.
7. Como chega o código a produção? Diferencie o deploy técnico do release: publicar artefactos não implica necessariamente ativar uma funcionalidade para todos os utilizadores.
8. Que observabilidade existe? Especifique logs, métricas, traces, alertas e consultas permitidas para verificar o comportamento.
9. Como são geridas as incidências? Determine o canal de escalamento, a severidade, os tempos de resposta esperados e o procedimento de reversão.
10. Quem decide e quem valida? Atribua responsáveis por produto, domínio, revisão técnica, deploy e operação.

As respostas devem ter uma fonte: código, configuração, teste executado, painel operacional ou confirmação de um responsável. Se não existir evidência, convém marcar a resposta como pendente e limitar o âmbito da alteração.

Criar um inventário técnico mínimo e verificável

Não é necessário produzir um mapa exaustivo antes de avançar, mas sim um inventário que permita reproduzir o ambiente e localizar dependências. Deve distinguir o que está confirmado do que é assumido e evitar incluir segredos em documentos, incidências ou capturas de ecrã.

• Repositório ou repositórios, branch de integração, estratégia de revisão e mecanismo de gestão de dependências PHP.
• Ambientes disponíveis, propósito de cada um, diferenças relevantes de configuração e dados permitidos em cada um deles.
• Versão de PHP, extensões necessárias, servidor web, processos de queue worker e comandos de execução local.
• Base de dados, migrações, tarefas de manutenção, cópias de segurança e restrições a consultas ou modificações.
• Segredos e configuração: localização gerida, processo de pedido, rotação e responsáveis, nunca valores reais.
• Filas, tarefas agendadas, importadores, exportadores, notificações e serviços externos com os seus pontos de falha.
• Canais de logs, alertas e painéis existentes, incluindo limites de acesso a informação sensível.

Um inventário útil permite responder a uma pergunta concreta: “se esta modificação for executada, que processos adicionais poderão ser ativados?”. Se não for possível responder, o primeiro trabalho deverá ser de descoberta ou instrumentação, não de alteração funcional.

Aplicar acessos progressivos e separação de funções

O princípio do menor privilégio reduz tanto o impacto de um erro como a dificuldade de investigar o que aconteceu. Os acessos devem ser concedidos por fases, de acordo com a tarefa e a evidência necessária.

Fases práticas de acesso

• Investigação: leitura de código, documentação, tickets fechados, logs depurados e dados anonimizados quando possível.
• Desenvolvimento: execução local, criação de branches, testes e acesso a ambientes não produtivos com credenciais limitadas.
• Deploy: capacidade de preparar ou iniciar um deploy apenas se existir uma revisão aprovada e um mecanismo auditado.
• Operação: acesso temporário e limitado à produção para diagnóstico, com registo de atividade e uma necessidade definida.

Evite partilhar contas, copiar ficheiros de configuração de produção ou conceder acesso administrativo “para o caso de ser preciso”. A rapidez inicial que essas decisões aparentam costuma transformar-se numa investigação lenta quando surge uma incidência. Quando a equipa utiliza ativação gradual, também deve separar o ato de fazer deploy do código da exposição do comportamento: uma feature flag, se existir e for bem gerida, pode limitar a exposição inicial.

Reconstruir um fluxo crítico de ponta a ponta

Selecione um fluxo representativo e percorra-o da perspetiva do utilizador. Por exemplo: um utilizador envia um formulário, a aplicação autentica e autoriza a ação, valida dados, persiste uma entidade, emite um evento, processa um trabalho assíncrono e chama uma API externa. O percurso deve mostrar onde pode falhar, o que é tentado novamente e o que acontece se um passo for concluído duas vezes.

Durante a reconstrução, identifique:

• Entrada, validações e mensagens de erro visíveis.
• Controladores, serviços, eventos, listeners e código legado que intervém de forma indireta.
• Leituras e escritas na base de dados, transações, bloqueios e identificadores de correlação.
• Mensagens na fila, tarefas agendadas, tentativas, idempotência e filas de erros.
• Contratos de API, timeouts, respostas esperadas e comportamento perante indisponibilidade.
• Logs ou métricas que permitam confirmar o resultado sem expor dados sensíveis.

Não basta desenhar o caminho feliz. Deve verificar-se o que acontece perante dados inválidos, duplicados, uma API lenta ou uma execução repetida de um worker. Essa verificação transforma um diagrama em conhecimento operacional.

Escolher uma primeira alteração que valide o conhecimento

A primeira alteração deve ser pequena, reversível e observável. O seu valor não se mede apenas pela funcionalidade entregue, mas também pela capacidade de validar que o novo integrante compreende o ciclo completo de trabalho: requisito, código, testes, revisão, deploy e verificação posterior.

São candidatos razoáveis uma correção de validação com testes, uma melhoria de mensagem de erro, cobertura para um caso limite conhecido ou uma correção delimitada num processo não sensível. Evite começar por migrações destrutivas, alterações massivas de permissões, regras de cálculo, sincronizações de dados ou modificações de infraestrutura sem uma linha de base verificável.

O pedido deve ser formulado com critérios de aceitação e limites claros. Em vez de “corrigir o registo”, especifique o caso de entrada, o resultado esperado, os perfis afetados, o comportamento que não deve mudar e o sinal que confirmará o sucesso.

Exigir evidências antes, durante e depois do deploy

Uma revisão de código é necessária, mas não substitui a evidência operacional. Cada primeira alteração deve incluir um conjunto proporcional de testes e um plano explícito.

• Testes automatizados modificados ou adicionados e resultado da suite relevante.
• Teste manual documentado para o fluxo afetado e as suas permissões relevantes.
• Revisão por alguém que conheça o domínio ou a área sensível do sistema.
• Plano de deploy com pré-requisitos, ordem dos passos e responsável pela sua execução.
• Verificações posteriores: logs, métrica, consulta segura ou ação controlada que confirme o resultado.
• Plano de reversão: o que é revertido, quando, que consequências tem e se os dados requerem uma correção adicional.

A reversão merece especial atenção em PHP legado: restaurar código não desfaz, por si só, um dado já enviado a um terceiro, um e-mail enviado ou um trabalho assíncrono processado. O plano deve distinguir entre reverter o binário e compensar efeitos de negócio.

Converter o trabalho realizado em documentação viva

O conhecimento obtido não deve ficar apenas em conversas ou comentários de um pedido de alteração. Mantenha um mapa vivo, breve e próximo do trabalho: fluxo percorrido, componentes envolvidos, responsáveis, dependências, comandos seguros, riscos, decisões e perguntas em aberto.

Também convém registar os pontos frágeis: processos sem testes, tabelas com semântica duvidosa, integrações sem ambiente de teste, alertas que não cobrem falhas relevantes ou tarefas que dependem de uma pessoa concreta. Documentá-los não obriga a resolvê-los de imediato, mas permite priorizá-los e evitar que se transformem em surpresas repetidas.

Sinais para interromper alterações de maior risco

Interrompa e reoriente o onboarding quando não for possível reproduzir o fluxo num ambiente seguro, não existir uma pessoa capaz de validar o resultado de negócio, se desconhecer como reverter ou os acessos obrigarem a partilhar credenciais. Outros sinais são erros sem rastreabilidade, dados de produção usados sem controlos, dependências externas sem contrato conhecido e deploys manuais que ninguém consegue explicar.

Nestas condições, avançar depressa não reduz o prazo: transfere o custo para uma incidência mais difícil de diagnosticar. O passo seguinte adequado pode ser melhorar a observabilidade, recuperar um ambiente de testes, documentar uma integração ou delimitar uma tarefa ainda menor. Um onboarding técnico seguro cria capacidade de mudança sustentável antes de ampliar o âmbito.