Documentação de manutenção

Como depurar um módulo do BarberBot

Esta página foi feita para o próximo desenvolvedor encontrar bugs com rapidez. O foco não é teoria. O foco é mostrar onde olhar primeiro, como seguir o fluxo e quais arquivos normalmente quebram.

Debug prático listar / salvar / buscar / excluir sessão / SQL / AJAX manutenção diária
Visão geral Ordem correta Depurar listar.php Depurar salvar.php Depurar buscar.php Depurar excluir.php Sessão SQL AJAX Checklist final
Leitura rápida

Como pensar quando um módulo quebra

No BarberBot, um bug quase nunca está em um lugar só. Em muitos módulos, a tela, o endpoint, a query SQL e a resposta AJAX estão espalhados em arquivos diferentes. Em outros casos, tudo isso está misturado no mesmo arquivo.

1. Tela

Veja o arquivo principal do módulo, normalmente nome_modulo.php.

2. Endpoint

Depois siga para listar.php, salvar.php, buscar.php ou excluir.php.

3. SQL

Confirme a tabela, os filtros, os joins, os binds e a lógica de consulta.

4. Resposta

Verifique se o retorno esperado é HTML, texto simples ou JSON.

Regra prática: quando um módulo falhar, siga sempre esta ordem: entrada → sessão → regra → SQL → saída → AJAX.
Método recomendado

Ordem correta para depurar

  1. Abra a tela principal do módulo

    Exemplo: /sistema/painel/paginas/cobrancas_pagas.php.

    Confirme quais botões, filtros, formulários e chamadas JavaScript partem dali.

  2. Identifique o arquivo operacional chamado

    Normalmente a tela chama um destes arquivos:

    listar.php
salvar.php
buscar.php
editar.php
excluir.php

  3. Confira os dados de entrada

    Valide $_POST, $_GET, $_SESSION e qualquer campo oculto do formulário.

  4. Leia a regra antes de mexer na query

    Muitos bugs são de permissão, filtro ou tipo de usuário, e não do banco em si.

  5. Só depois revise o SQL

    Confirme tabela, campos, joins, filtros, datas e paginação.

  6. Por fim, verifique a resposta esperada

    Se o frontend espera HTML e o backend devolve texto ou JSON, a tela quebra mesmo que a query esteja certa.

Arquivo mais frequente

Como depurar listar.php

O listar.php costuma ser o arquivo que mais mistura responsabilidades no BarberBot. Ele normalmente recebe filtros, consulta o banco e devolve a tabela HTML pronta.

Sequência típica

tela do módulo → AJAX → listar.php → conexao.php → tabela MySQL → HTML de resposta

O que verificar

  • Se os filtros chegaram corretamente por POST ou GET
  • Se a sessão do usuário foi iniciada
  • Se o arquivo carregou ../../../conexao.php corretamente
  • Se a query SQL usa a tabela certa
  • Se o retorno final é HTML válido
  • Se a tabela esperada na tela recebe esse HTML sem erro de seletor

Sintomas comuns

  • Tela vazia mesmo com dados no banco
  • Filtro de data sem efeito
  • Lista aparecendo só para administrador
  • Erro de DataTable ou tabela quebrada
  • HTML vindo truncado por echo mal fechado

Exemplo real do BarberBot

No módulo cobrancas_pagas, o fluxo costuma ser: 

/sistema/painel/paginas/cobrancas_pagas.php
    → chama via JavaScript
/sistema/painel/paginas/cobrancas_pagas/listar.php
    → carrega conexao.php
    → consulta tabela receber
    → devolve a tabela HTML

Se esse fluxo falhar, o primeiro passo é confirmar as datas enviadas em p1 e p2, o nível do usuário em $_SESSION['nivel'] e a query sobre a tabela receber.

Persistência

Como depurar salvar.php

O salvar.php normalmente recebe os campos do formulário, valida regras básicas e executa um INSERT ou UPDATE.

Verificações principais

  • Campos obrigatórios chegaram no $_POST
  • O ID está vazio quando é cadastro e preenchido quando é edição
  • Os nomes dos campos do formulário batem com os nomes lidos no PHP
  • Os bindValue foram feitos para todos os placeholders
  • A query não está falhando por coluna obrigatória ausente

Sintomas comuns

  • Botão salvar não faz nada
  • Cadastro sempre volta com “erro” sem detalhes
  • Edita como se fosse novo registro
  • Atualiza parcialmente e deixa coluna vazia
  • Validação de duplicidade bloqueia edição correta
Ponto crítico: em módulos do BarberBot, é comum o bug estar no nome do campo do formulário e não na query. Exemplo: o input name="cliente" não bater com o campo lido em $_POST['cliente'].
Busca de registro

Como depurar buscar.php ou editar.php

Esses arquivos costumam ser chamados quando o usuário abre um modal de edição ou precisa carregar um registro específico.

O que verificar

  • Se o ID foi enviado corretamente
  • Se o registro realmente existe no banco
  • Se o retorno esperado é JSON, texto delimitado ou HTML parcial
  • Se há campos que precisam ser convertidos antes de voltar para a tela
  • Se caracteres especiais estão quebrando o retorno

Sintomas comuns

  • Modal abre vazio
  • Campos vêm trocados
  • ID certo, mas registro não aparece
  • Erro de JavaScript ao tentar processar retorno
  • JSON inválido por echo extra ou aviso PHP
Remoção

Como depurar excluir.php

O excluir.php parece simples, mas costuma falhar por relacionamento, arquivo físico associado, permissão ou ID incorreto.

O que verificar

  • Se o ID foi enviado corretamente
  • Se o registro existe antes do delete
  • Se existem dependências em outras tabelas
  • Se o módulo também remove arquivos do disco
  • Se a resposta de sucesso realmente volta para a tela

Sintomas comuns

  • Exclusão aparentemente executa, mas item continua na tela
  • Item some da lista, mas continua no banco
  • Registro é removido, porém arquivo físico permanece
  • Erro por chave estrangeira ou dependência lógica
Autorização

Como depurar sessão e permissão

Muitos módulos do BarberBot mudam o comportamento com base em $_SESSION['id'], $_SESSION['nivel'] e outras variáveis globais. Quando o resultado muda entre administrador e usuário comum, quase sempre o problema está aqui.

Sintoma clássico: funciona para administrador, mas falha para usuário comum.
  • Confirme se session_start() foi chamado
  • Veja se o arquivo depende de $_SESSION['id'] ou $_SESSION['nivel']
  • Teste com perfis diferentes
  • Verifique redirecionamentos silenciosos para index.php
  • Confirme se permissões do painel estão bloqueando a tela antes do endpoint ser chamado
Banco de dados

Como depurar SQL do módulo

O que revisar

  • Tabela correta
  • Campo correto
  • Filtro de data
  • Join correto
  • Ordenação
  • Paginação
  • Parâmetros bindados corretamente

Alertas

  • Não assumir que o problema é SQL antes de conferir entrada e sessão
  • Cuidado com query montada por concatenação
  • Evite mexer em LIMIT e filtros sem revisar paginação
  • Se o retorno for vazio, valide a query direto no banco com os mesmos filtros
Fluxo recomendado:
1. descobrir qual tabela o módulo usa
2. copiar a query montada
3. testar com os mesmos parâmetros
4. comparar o resultado esperado com o resultado real
5. só depois corrigir o PHP
Frontend e resposta

Como depurar AJAX e retorno

Mesmo quando o backend está certo, a tela pode continuar quebrada se o JavaScript esperar um formato de resposta diferente.

O que verificar no AJAX

  • URL chamada está correta
  • Método POST ou GET está correto
  • Dados enviados possuem o nome certo
  • O callback de sucesso trata HTML, JSON ou texto do jeito esperado
  • Existe callback de erro ou log no console

Sintomas comuns

  • Nada atualiza na tela
  • Resposta vem, mas não renderiza
  • Modal fecha sem salvar
  • Console mostra erro de parse
  • Endpoint responde HTML, mas o JS tenta ler JSON

Teste rápido de manutenção

Quando o módulo usa AJAX, o ideal é comparar: 

1. o que a tela envia
2. o que o endpoint recebe
3. o que o endpoint devolve
4. o que o JavaScript espera receber
Encerramento

Checklist final de depuração

Antes de corrigir

  • Descobrir qual arquivo inicia o fluxo
  • Descobrir qual endpoint é chamado
  • Confirmar sessão e permissão
  • Confirmar dados de entrada

Durante a análise

  • Revisar query e tabela
  • Conferir placeholders e binds
  • Testar retorno esperado
  • Comparar com a resposta AJAX

Depois da correção

  • Testar cadastro
  • Testar edição
  • Testar exclusão
  • Testar com administrador e usuário comum
  • Testar lista vazia e lista com dados
Resumo final: para achar bug no BarberBot, não basta abrir só o arquivo com erro aparente. O método mais seguro é seguir o fluxo inteiro: tela → endpoint → sessão → regra → SQL → resposta → AJAX.