Diagnóstico

Comece pelo sintoma, faça verificações somente de leitura e registre evidências. Não altere dados diretamente no banco e não reinicie todos os serviços sem identificar qual processo falhou.

Evidências mínimas para escalar

Anote ambiente, empresa, usuário/perfil, tela ou rota, horário com fuso, ID do registro/execução/job, resultado esperado, resultado observado e passos para reproduzir. Inclua status HTTP e código técnico quando houver. Oculte senhas, tokens, cookies, documentos pessoais e payloads sensíveis.

Usuário não consegue acessar uma área

1. Confirme que o usuário pertence à empresa correta e está ativo.
2. Consulte Usuários e permissões e compare o perfil com a área.
3. Teste novamente após sair e entrar; uma sessão antiga pode preservar estado anterior.
4. No navegador, registre rota e status: 401 indica sessão, 403 indica permissão e 404 também pode representar isolamento entre empresas.

Evidência esperada: outro usuário com o mesmo perfil apresenta o mesmo limite; um perfil autorizado abre a área.

Escalone quando: matriz e cadastro permitem acesso, mas o backend retorna 403/404; envie rota, usuário, empresa e horário.

Colaborador não vê projeto no modo de campo

1. Confirme que o login está ligado a um colaborador ativo.
2. Confirme que o colaborador pertence a uma equipe.
3. Confirme que essa equipe está atribuída ao projeto.
4. Confirme que o usuário saiu e entrou novamente após mudanças de vínculo.

Evidência esperada: o projeto aparece em Campo para um usuário autenticado ligado a colaborador ativo cuja equipe está atribuída. Perfil operator e equipe do tipo campo controlam o redirecionamento automático.

Escalone quando: vínculos estão ativos e corretos, mas a lista continua vazia; informe IDs do usuário, colaborador, equipe e projeto.

Cliente ou atualização não aparece no portal

1. Abra o link copiado da tela do próprio projeto; não reutilize token de outro projeto.
2. Confirme que projeto, cliente e atualização pertencem à mesma empresa.
3. Verifique se a atualização foi publicada e se fotos terminaram o upload.
4. Teste em janela anônima e registre o status HTTP.

Evidência esperada: o token abre um único projeto e mostra as atualizações publicadas daquele histórico.

Escalone quando: a tela interna mostra o conteúdo no projeto correto, mas o mesmo token não o apresenta; envie projeto, atualização, horário e status, nunca o link público completo em canal aberto.

E-mail não chega

1. Confirme endereço do usuário e MAIL_MAILER do ambiente.
2. Em local, abra Mailpit. Em homologação/produção, confira log do provedor.
3. Valide remetente, host, porta, TLS e autenticação.
4. Consulte spam, bloqueio, bounce e políticas SPF/DKIM/DMARC.

Evidência esperada: a aplicação entrega ao SMTP e o provedor atribui um ID à mensagem.

Escalone quando: o provedor aceitou e não entregou, ou Laravel registrou exceção; envie horário, destinatário mascarado e ID do provedor.

Imagem ou arquivo não carrega

1. Registre a URL e o status HTTP sem compartilhar token de portal.
2. Confirme a existência do arquivo no disco public e a permissão de leitura.
3. Confira storage/app/public, o link criado por php artisan storage:link e a persistência do volume.
4. Em mais de uma instância, confirme que storage/app/public é compartilhado.

Evidência esperada: o arquivo existe no disco public e a URL gerada responde 200 com o tipo correto.

Escalone quando: o banco referencia um caminho inexistente ou a URL é gerada incorretamente; envie ID do anexo, disco, caminho e status.

WhatsApp não envia ou não recebe

1. Em Config. WhatsApp, confirme conta ativa e use Verificar conexão.
2. Para recebimento, confira retorno do webhook, assinatura e Phone number ID.
3. Para envio, confira status e erro da mensagem, worker da fila whatsapp e validade do token.
4. Confirme número normalizado, regras da Meta e bloqueio/atribuição da conversa.

Evidência esperada: entrada cria uma mensagem única; saída passa de queued para enviada ou registra erro do provedor.

Escalone quando: Meta aceitou a entrega e nada foi criado, ou a mensagem falha sem detalhe; envie ID da conta/mensagem, horário, direção e status, sem token.

Webhook não é validado

1. Identifique se é webhook Meta ou trigger de flow.
2. Meta: confira URL HTTPS, modo subscribe, challenge e verify token do mesmo ambiente.
3. Flow: confira URL publicada, Idempotency-Key e, se usada, assinatura HMAC/timestamp.
4. Registre status: 403 aponta validação/assinatura; 404, chave ou trigger inativo; 422, cabeçalho obrigatório/payload.

Evidência esperada: verificação Meta devolve o challenge; trigger retorna 202 com executionId.

Escalone quando: bytes assinados, horário e configuração estão corretos e ainda há 403; envie cabeçalhos não secretos, hash do corpo, status e horário.

Flow não inicia, não publica, fica aguardando ou falha

1. Não publica: valide o draft e abra cada erro/aviso de node, conexão e credencial.
2. Não inicia: confirme versão publicada, flow ativo e trigger publicado.
3. Aguardando: abra a espera e confirme scheduler, callback, evento/correlação ou resposta esperada.
4. Falha: abra node, código, entrada permitida, política de erro e serviço externo.
5. Confirme worker workflows e workflows:tick no scheduler.

Evidência esperada: histórico mostra trigger, versão, sequência de nodes e transição de queued para estado final ou espera conhecida.

Escalone quando: a execução permanece sem node ativo ou a espera elegível não retoma; envie flow, versão, execução, node/wait e horários.

Evento interno não dispara automação

1. Confirme que a ação realmente emite o evento listado em Automações e flows.
2. Confira a fila events e o listener StoreInternalEvent.
3. Localize o evento interno e seu processed_at.
4. Confirme assinatura do trigger, empresa, versão publicada e flow ativo.
5. Para WhatsApp, confirme conversa sem atendente e sem bloqueio de automação.

Evidência esperada: evento é persistido, processado e cria uma execução idempotente por assinatura.

Escalone quando: evento processado e assinatura ativa não geram execução; envie IDs do evento, assinatura, flow e empresa.

Job permanece pendente

1. Descubra a fila: events, whatsapp, workflows ou default.
2. Verifique se o worker está vivo e consumindo explicitamente essa fila.
3. Confira conexão Redis e jobs falhos.
4. Compare retry_after com timeout do worker e duração real.
5. Após deploy, confirme que workers foram reiniciados.

Evidência esperada: a profundidade da fila cai e o job muda de estado ou aparece como falho com exceção.

Escalone quando: worker saudável reserva o job repetidamente ou processo morre; envie fila, classe, ID, tentativas e exceção sanitizada.

Atualização em tempo real não aparece

1. Atualize a página. Se o dado aparece, persistência está correta e o problema é realtime.
2. Confira BROADCAST_CONNECTION, processo Reverb e variáveis VITE_REVERB_* usadas no build.
3. No navegador, verifique conexão ws/wss, host, porta, TLS e erro no console.
4. Confirme que proxy aceita upgrade de websocket e que o usuário está autenticado no canal.

Evidência esperada: websocket conecta e eventos de conversa/execução atualizam a tela sem reload.

Escalone quando: evento é publicado mas não chega ao canal; envie nome do evento, canal, horário e erro websocket, sem chaves.

Financeiro ou folha mostra valor inesperado

1. Confira empresa e período/filtros.
2. Financeiro: valide tipo, competência/vencimento, valor, pagamentos parciais, status e lançamento de caixa.
3. Folha: valide colaborador ativo, compensação vigente, referência, salário, adicionais, descontos e adiantamentos.
4. Recalcule o preview e compare a fórmula descrita em RH e folha.
5. Confirme se a folha está em rascunho, fechada ou reaberta.

Evidência esperada: soma dos componentes e pagamentos reproduz o total e o saldo exibidos.

Escalone quando: os registros persistidos não reproduzem o cálculo; envie IDs, período e valores, removendo dados pessoais desnecessários.

Comandos seguros de apoio

Execute no ambiente correto e preserve a saída necessária:

php artisan about
php artisan schedule:list
php artisan queue:failed
php artisan migrate:status

Use logs do serviço web, worker, scheduler e Reverb filtrados pelo horário. Não rode migrate:fresh, limpeza global de filas, exclusão em massa ou comandos de banco destrutivos como diagnóstico comum.