Documentação de manutenção

Fluxo entre Pastas do BarberBot

Esta página mostra o caminho completo de execução do BarberBot. A ideia é ajudar o próximo desenvolvedor a enxergar rapidamente de onde a requisição sai, por quais arquivos ela passa e em qual tabela ela termina.

Tela Pastas Banco Execução
Visão geral Padrões principais Fluxo painel Fluxo salvar Fluxo cron Fluxo API Checklist
Leitura rápida

Como ler o caminho de execução

No BarberBot, a maioria dos fluxos começa em uma tela do painel ou em um endpoint de integração. Depois disso, a execução costuma passar por um arquivo operacional do módulo, carregar a conexão global e acessar uma ou mais tabelas do MySQL.

Origem

Tela, cron, API, webhook ou ação AJAX.

Processamento

Arquivo como listar.php, salvar.php, buscar.php ou excluir.php.

Infraestrutura

Normalmente o fluxo passa por /sistema/conexao.php.

Persistência

Consulta ou gravação em tabelas como clientes, receber, agendamentos e outras.

Regra prática: para entender qualquer funcionalidade do BarberBot, siga esta ordem: tela de entrada → arquivo operacional → conexao.php → tabela → retorno para a interface.
Mapa mental

Padrões de fluxo mais comuns

1. Tela do painel → listagem

Usado quando a página principal monta a estrutura e o conteúdo da tabela vem por AJAX.

/sistema/painel/paginas/modulo.php /sistema/painel/paginas/modulo/listar.php /sistema/conexao.php tabela MySQL

2. Tela do painel → salvar

Usado quando o formulário do modal envia dados para gravação ou atualização.

/sistema/painel/paginas/modulo.php /sistema/painel/paginas/modulo/salvar.php /sistema/conexao.php INSERT / UPDATE

3. Cron → banco → serviço externo

Usado para rotinas automáticas, alertas e disparos programados.

/cron/arquivo.php /sistema/conexao.php tabela MySQL /ajax/api-texto.php

4. Aplicativo / integração → API interna

Usado por rotas em /api, normalmente consumidas por app ou integração externa.

/api/modulo/arquivo.php /sistema/conexao.php tabela MySQL retorno da API
Exemplo real

Fluxo 1 — Painel → páginas → listar.php → conexão → tabela

Este é o fluxo clássico de listagem usado em módulos do painel. Um exemplo real é o módulo cobranças pagas.

/sistema/painel/paginas/cobrancas_pagas.php → /sistema/painel/paginas/cobrancas_pagas/listar.php → /sistema/conexao.php → receber
1

Tela principal

cobrancas_pagas.php monta a interface, exibe filtros por data e prepara a div onde a listagem será renderizada.

2

Chamada da listagem

O JavaScript da tela envia os filtros para cobrancas_pagas/listar.php, normalmente via AJAX.

3

Processamento

listar.php lê $_POST, verifica sessão e decide se o usuário é administrador ou comum para montar a consulta correta.

4

Banco

O arquivo carrega /sistema/conexao.php, usa $pdo e consulta principalmente a tabela receber.

5

Retorno

O próprio listar.php monta o HTML da tabela e devolve esse conteúdo para a tela principal.

Ponto importante: esse tipo de arquivo costuma misturar consulta SQL, regra de negócio e renderização de HTML. Por isso, ao corrigir um problema nele, o dev deve inspecionar entrada, regra, SQL e saída no mesmo lugar.
Exemplo de persistência

Fluxo 2 — Painel → salvar.php → conexão → tabela → retorno AJAX

/sistema/painel/paginas/modulo.php → /sistema/painel/paginas/modulo/salvar.php → /sistema/conexao.php → INSERT / UPDATE em tabela

Como funciona

  • A tela principal abre um modal ou formulário.
  • O JavaScript envia os dados para salvar.php.
  • O arquivo lê $_POST, valida campos e executa INSERT ou UPDATE.
  • No final, devolve uma mensagem curta para o AJAX tratar.

O que o dev deve testar

  • campos obrigatórios
  • registro duplicado
  • edição versus cadastro novo
  • mensagem de erro retornada
  • recarga da listagem após salvar
Leitura recomendada: sempre abra primeiro a tela principal do módulo para descobrir quem envia o formulário e qual arquivo recebe a submissão.
Rotina automática

Fluxo 3 — Cron → conexão → banco → AJAX interno → serviço externo

Esse padrão aparece quando o sistema executa ações automáticas sem passar por uma tela do painel. Um exemplo real é o alerta de manutenção de prótese capilar.

/cron/alerta_manutencao.php → /sistema/conexao.php → manutencoes_protese + clientes + proteses → /ajax/api-texto.php → provedor WhatsApp
1

Entrada do cron

alerta_manutencao.php roda de forma agendada no servidor.

2

Busca pendências

O cron consulta manutenções vencidas e cruza dados com clientes e próteses.

3

Prepara mensagem

O script monta o texto a ser enviado e valida telefone e data da manutenção.

4

Disparo

O envio é delegado ao arquivo /ajax/api-texto.php, que conversa com o provedor externo.

5

Atualiza status

Depois do envio, o banco pode ser atualizado para evitar reenvio duplicado.

Leitura correta desse fluxo: mesmo usando a pasta /ajax, esse caso não é uma chamada do navegador. Aqui /ajax/api-texto.php funciona como um utilitário interno de integração.
Integração

Fluxo 4 — API interna → conexão → tabela → resposta

As rotas em /api são usadas por aplicativo, integração ou consumo externo. Um exemplo simples é a listagem de clientes.

/api/clientes/listar.php → /sistema/conexao.php → clientes → resposta para app / integração

O que esse padrão mostra

  • a pasta /api expõe pontos de entrada fora do painel
  • o banco continua sendo acessado via /sistema/conexao.php
  • a resposta pode ser HTML, texto simples ou JSON, dependendo da implementação

Cuidados comuns

  • validar autenticação da rota
  • padronizar retorno
  • não confiar em $_POST sem validação
  • evitar SQL direto com concatenação
Checklist operacional

Como seguir um fluxo quando surgir bug

1. Descobrir a origem

Veja se a execução começa no painel, em API, cron, webhook ou chamada AJAX.

2. Localizar o arquivo operacional

Identifique qual listar.php, salvar.php, buscar.php ou endpoint recebeu a ação.

3. Confirmar a conexão

Verifique se o fluxo passa por /sistema/conexao.php e se o $pdo está disponível.

4. Mapear a tabela

Descubra quais tabelas são lidas ou gravadas e valide os campos envolvidos.

5. Validar o retorno

Entenda se o arquivo devolve HTML, JSON, texto simples ou apenas executa um efeito colateral.

6. Testar o caminho completo

Não teste só a query. Teste a tela, o endpoint, o banco e o retorno final para a interface.

Resumo

O que o próximo dev deve guardar

O BarberBot é mais fácil de manter quando o desenvolvedor pensa em caminho de execução, e não apenas em arquivo isolado. Em quase todos os módulos, o entendimento correto vem de seguir esta lógica:

origem arquivo operacional conexão tabela / integração retorno

Sempre que surgir um bug, refaça mentalmente esse percurso. Isso reduz muito o tempo de diagnóstico porque o BarberBot costuma misturar regra, SQL e saída no mesmo ponto.