Documentação de manutenção

BarberBot por Pastas

Esta página mostra como o BarberBot está organizado por diretórios. O objetivo é facilitar a leitura do sistema para o próximo desenvolvedor, deixando claro em qual camada cada pasta se encaixa, o que ela costuma concentrar e por onde começar a manutenção.

leitura por diretório camadas práticas foco em manutenção navegação para dev novo

Navegação rápida

Visão geral

O BarberBot é um sistema em PHP puro com MySQL, organizado por módulos e por diretórios funcionais. Em vez de separar totalmente interface, regra e acesso a dados em classes distintas, o projeto distribui essas responsabilidades em pastas operacionais.

Na prática, o próximo desenvolvedor deve ler o sistema assim:

Leitura funcional

  • /sistema concentra autenticação, conexão e áreas internas
  • /sistema/painel concentra o painel administrativo
  • /sistema/painel/paginas concentra os módulos do painel
  • /ajax concentra endpoints soltos chamados por JavaScript
  • /api concentra rotas estruturadas para integração e app

Leitura arquitetural

  • Interface: telas PHP, HTML, modais e scripts
  • Endpoint/Ação: listagem, salvar, editar, excluir, buscar
  • Infraestrutura: conexão, autenticação, config e cron
  • Banco: tabelas MySQL consultadas diretamente pelos módulos
Leitura correta para manutenção: no BarberBot, uma pasta pode pertencer principalmente a uma camada, mas ainda assim misturar responsabilidades. O diretório indica a intenção principal, não uma separação arquitetural rígida.

Mapa rápido das pastas principais

/sistema

Base interna do sistema: conexão, autenticação, painel, cliente e ativos.

Infraestrutura Interface interna
/sistema/painel

Estrutura do painel administrativo: layout, permissões, cron interno, JS, CSS e páginas.

Interface Infraestrutura
/sistema/painel/paginas

Módulos do painel. É onde ficam as telas e as subpastas operacionais do sistema.

Interface Endpoint/Ação
/ajax

Endpoints chamados por JavaScript fora do padrão de módulo do painel.

Endpoint/Ação Integração
/api

Rotas agrupadas por domínio, usadas para app, integração e consumo externo.

Endpoint/Ação Integração
/config e /cron

Configuração global, licenças, chaves e tarefas automatizadas.

Infraestrutura Automação

Como cada pasta se encaixa nas camadas

Pasta Camada principal Função no sistema Observação de manutenção
/sistema Infraestrutura + Interface interna Autenticação, conexão, áreas internas, ativos e base do painel Comece aqui quando o erro envolver login, sessão, conexão ou carregamento geral
/sistema/painel Interface do painel Layout administrativo, permissões, scripts e recursos comuns do painel Use esta pasta quando o problema for estrutural na área administrativa
/sistema/painel/paginas Interface + Endpoint/Ação Módulos administrativos e seus arquivos operacionais É a pasta mais importante para manutenção de regra de negócio do painel
/ajax Endpoint/Ação Requisições rápidas, integrações e callbacks chamados por JS Verifique esta pasta quando a tela chama algo via AJAX fora do módulo
/api Endpoint/Ação Rotas organizadas por domínio funcional Prioridade quando o problema vem do app, integração externa ou consumo por rota
/config Infraestrutura Chaves, licenças, bootstrap e parâmetros globais Verifique com cuidado; qualquer alteração errada afeta vários módulos
/cron Infraestrutura + Automação Rotinas agendadas, alertas e processos automáticos Analise esta pasta quando a falha acontece sem ação direta do usuário
/app Interface + integração Camada ligada à experiência app/PWA e parte do acesso mobile Use quando o comportamento divergir entre painel web e app

Pasta /sistema

A pasta /sistema é a base interna do BarberBot. Ela reúne os arquivos mais estruturais do sistema, como autenticação, conexão com banco, recuperação de senha e os dois grandes ambientes internos: painel e painel_cliente.

Arquivos importantes

  • /sistema/conexao.php → conexão PDO e carregamento global
  • /sistema/autenticar.php → fluxo de autenticação interna
  • /sistema/index.php → ponto de entrada da área interna
  • /sistema/recuperar-senha.php → recuperação de senha

Quando começar por aqui

  • erro de login
  • sessão expirando errado
  • problema global de conexão
  • configuração do painel não carregando
Ponto crítico: vários módulos dependem indiretamente de conexao.php. Se houver falha global de banco, token ou config, o sintoma aparece em várias telas ao mesmo tempo.

Pasta /sistema/painel

Esta pasta representa o núcleo do painel administrativo. Ela concentra recursos compartilhados do backoffice, como verificação de sessão, arquivos estáticos do painel, permissões, imagens, PDFs, relatórios e a pasta paginas.

Função principal

Organizar a área administrativa e seus recursos comuns.

Camada dominante

Interface administrativa com apoio de infraestrutura.

Sinal de manutenção

Problemas de layout, permissão e carregamento geral do painel.

/sistema/painel/
├── index.php
├── verificar.php
├── verificar-permissoes.php
├── js/
├── css/
├── images/
├── rel/
├── cron/
└── paginas/

Pasta /sistema/painel/paginas

Esta é a pasta mais importante para manutenção do BarberBot. Cada módulo do painel costuma ter: 

/sistema/painel/paginas/
├── nome_modulo.php
└── nome_modulo/
    ├── listar.php
    ├── salvar.php
    ├── editar.php ou buscar.php
    └── excluir.php

O arquivo nome_modulo.php monta a tela. A subpasta operacional executa as ações do módulo. No BarberBot, essa pasta mistura principalmente interface e endpoint/ação.

Exemplos reais

  • /sistema/painel/paginas/clientes.php
  • /sistema/painel/paginas/cobrancas_pagas.php
  • /sistema/painel/paginas/agendamentos.php
  • /sistema/painel/paginas/analises.php

Exemplos de subpastas

  • /sistema/painel/paginas/cobrancas_pagas/listar.php
  • /sistema/painel/paginas/clientes/salvar.php
  • /sistema/painel/paginas/agendamentos/excluir.php
  • /sistema/painel/paginas/simulador/gerar_ia.php
Leitura correta: sempre abra primeiro o arquivo principal do módulo, depois a subpasta interna. É assim que o fluxo real do painel fica claro.

Pasta /ajax

A pasta /ajax concentra endpoints acionados por JavaScript em fluxos rápidos do sistema. Nem sempre esses arquivos seguem o padrão de um módulo do painel. Por isso, ela funciona como uma camada de ação mais solta.

Arquivos encontrados

  • /ajax/agendar.php
  • /ajax/api-listar.php
  • /ajax/api-texto.php
  • /ajax/gerar_ia_cliente.php

Quando investigar

  • requisição AJAX falhando sem abrir módulo do painel
  • problema em callback assíncrono
  • função de front chamando arquivo fora de /paginas
  • erro em automação de mensagem

Pasta /api

A pasta /api organiza rotas por domínio funcional. Ela é mais estruturada que a pasta /ajax, porque separa grupos como clientes, servicos, usuarios, receber e outros. 

/api/
├── clientes/
├── home/
├── login/
├── receber/
├── servicos/
├── usuarios/
└── vendas/

Para manutenção, pense assim:

  • se a origem do erro for integração, app ou rota consumida externamente, comece em /api
  • se o erro vier do painel web com listagem e modal, normalmente comece em /sistema/painel/paginas

Pastas /config e /cron

Essas pastas pertencem principalmente à camada de infraestrutura. Elas não representam um módulo visual, mas afetam o comportamento geral do sistema.

/config

  • config_openai.php
  • licenca_boot.php
  • licenca_cron.php
  • recaptcha.php

Use com cautela, pois alterações aqui podem impactar vários módulos ao mesmo tempo.

/cron

  • tarefas automáticas
  • alertas
  • envios programados
  • processos sem clique do usuário

Quando a falha acontece “sozinha”, sem ação de tela, é forte sinal de rotina em cron.

Pasta /app

A pasta /app representa a camada ligada ao consumo por app/PWA e experiência mobile. Ela não substitui o painel web, mas compõe outra entrada do sistema.

Regra prática: se um recurso funciona no painel web mas falha no app, compare a implementação em /app com a implementação equivalente em /sistema ou /api.

Exemplo real: módulo cobrancas_pagas

/sistema/painel/paginas/cobrancas_pagas.php
/sistema/painel/paginas/cobrancas_pagas/listar.php
/sistema/painel/paginas/cobrancas_pagas/salvar.php
/sistema/painel/paginas/cobrancas_pagas/excluir.php

Leitura por camada

  • cobrancas_pagas.php → interface do módulo
  • listar.php → endpoint de listagem
  • salvar.php → persistência
  • excluir.php → remoção

Leitura real do BarberBot

  • listar.php também monta HTML
  • listar.php também aplica regra de negócio
  • listar.php também executa SQL
  • ou seja: a pasta ajuda a entender, mas o arquivo mistura funções
Mensagem para o próximo dev: use a pasta para se localizar, mas sempre leia o arquivo inteiro. No BarberBot, o nome do arquivo indica a função principal, porém não limita tudo o que ele faz.

Resumo final

O que o diretório mostra

A intenção principal do arquivo ou módulo dentro da arquitetura.

O que o diretório não garante

Separação rígida de responsabilidade. Isso o dev precisa confirmar lendo o código.

Pasta mais importante

/sistema/painel/paginas, porque é onde vive a maior parte da regra operacional do painel.

Regra prática para manutenção

Sempre descubra primeiro de qual diretório veio a ação. Depois leia o fluxo nessa ordem: tela, arquivo operacional, query SQL e retorno. Esse é o caminho mais rápido para entender o BarberBot sem se perder.