Documentação de manutenção

Camadas do Sistema BarberBot

Esta página explica, de forma objetiva, como o BarberBot está organizado hoje. O foco é ajudar o próximo desenvolvedor a entender rapidamente onde fica a interface, onde estão os endpoints, como o banco é acessado e por que vários arquivos misturam responsabilidades.

4 camadas práticas monólito em PHP puro módulos por pasta foco em manutenção

Navegação rápida

Visão geral

O BarberBot é um sistema em PHP puro com MySQL, organizado por módulos dentro do painel. Ele não segue uma arquitetura em camadas rígida como MVC puro ou Clean Architecture. Na prática, ele funciona como um monólito modular, onde cada módulo costuma ter:

Estrutura mais comum

  • uma tela principal
  • uma pasta com arquivos operacionais
  • acesso direto ao banco por PDO
  • retorno em HTML, texto ou JSON para AJAX

Leitura correta

O sistema tem camadas técnicas, mas elas não ficam completamente isoladas. Em vários pontos, o mesmo arquivo consulta o banco, aplica regra de negócio, monta a saída e devolve a resposta para a tela.

As 4 camadas práticas do BarberBot

1

Camada de Interface

É a parte que o usuário vê no navegador.

  • monta HTML
  • exibe tabelas, filtros e modais
  • carrega JavaScript
  • dispara requisições AJAX
/public_html/sistema/painel/paginas/cobrancas_pagas.php
2

Camada de Endpoint / Ação

São os arquivos internos do módulo que processam as ações da tela.

  • recebem POST ou GET
  • leem sessão
  • buscam dados no banco
  • salvam, editam, listam ou excluem
  • devolvem HTML, texto ou JSON
/public_html/sistema/painel/paginas/cobrancas_pagas/listar.php
/public_html/sistema/painel/paginas/cobrancas_pagas/salvar.php
/public_html/sistema/painel/paginas/cobrancas_pagas/excluir.php
3

Camada de Infraestrutura / Conexão

É a parte que conecta o sistema ao banco e carrega configurações globais.

  • abre a conexão PDO
  • disponibiliza $pdo
  • carrega configurações globais
  • serve de base para os demais arquivos
/public_html/sistema/conexao.php
4

Camada de Banco de Dados

É a camada de persistência do sistema, onde ficam as tabelas e relacionamentos.

  • clientes
  • usuários
  • cobranças
  • agendamentos
  • configurações
clientes usuarios receber agendamentos config formas_pgto

Onde as camadas se misturam

O ponto mais importante para o próximo dev é este: as camadas existem, mas estão misturadas.

Em muitos módulos, principalmente nos arquivos abaixo, o mesmo arquivo faz tudo junto:

listar.php salvar.php editar.php excluir.php
Leitura correta: em vários pontos do BarberBot, o mesmo arquivo lê parâmetro, aplica regra, consulta banco, monta HTML e devolve a resposta do AJAX.
Interface Regra SQL Resposta AJAX

Como ler um módulo do BarberBot

Normalmente cada módulo tem esta estrutura:

/paginas/nome_modulo.php
/paginas/nome_modulo/listar.php
/paginas/nome_modulo/salvar.php
/paginas/nome_modulo/editar.php
/paginas/nome_modulo/excluir.php

nome_modulo.php

É a tela principal do módulo.

  • monta a interface
  • renderiza filtro
  • carrega modais
  • chama os arquivos internos por AJAX

listar.php

Lista os dados do módulo.

  • consulta banco
  • aplica filtros
  • monta tabela HTML
  • devolve a listagem para a tela

salvar.php

Grava ou atualiza dados.

  • recebe dados do formulário
  • valida campos
  • executa INSERT ou UPDATE
  • devolve mensagem de sucesso ou erro

editar.php / buscar.php

Busca um registro específico para preencher formulário ou modal.

Exemplo real: cobrancas_pagas/listar.php

Arquivo principal

/public_html/sistema/painel/paginas/cobrancas_pagas.php

Esse arquivo pertence principalmente à camada de interface. Ele monta a tela, cria os filtros, chama a listagem e organiza os modais.

Arquivo interno

/public_html/sistema/painel/paginas/cobrancas_pagas/listar.php

Esse arquivo pertence principalmente à camada de endpoint/ação, mas na prática ele também mistura outras responsabilidades.

O que esse arquivo normalmente faz

  • lê os filtros recebidos
  • valida a sessão
  • executa consulta SQL
  • aplica regra de visualização
  • monta a tabela HTML
  • retorna a resposta para AJAX
Conclusão sobre esse arquivo: o listar.php não é apenas uma consulta. Ele funciona como um arquivo híbrido, misturando endpoint, regra de negócio, SQL e renderização de HTML.

Como o fluxo do módulo funciona

Fluxo de listagem

Usuário abre cobrancas_pagas.php
    ↓
A tela carrega estrutura HTML e filtros
    ↓
JavaScript chama cobrancas_pagas/listar.php
    ↓
listar.php consulta o banco
    ↓
listar.php monta a tabela HTML
    ↓
o HTML volta via AJAX
    ↓
a tela exibe a listagem

Fluxo de salvamento

Usuário preenche formulário
    ↓
JavaScript envia os dados para salvar.php
    ↓
salvar.php valida e grava no banco
    ↓
retorna sucesso ou erro
    ↓
a tela atualiza a listagem

Regra prática para manutenção

Quando o próximo dev for mexer em qualquer módulo do BarberBot, deve sempre analisar estes quatro pontos:

1. Entrada

  • $_POST
  • $_GET
  • $_SESSION
  • filtros
  • IDs recebidos

2. Regra

  • condição de negócio
  • tipo de usuário
  • permissões
  • filtros aplicados

3. SQL

  • query executada
  • joins
  • WHERE
  • ordenação
  • paginação

4. Saída

  • HTML retornado
  • JSON retornado
  • texto de sucesso/erro
  • comportamento esperado pelo AJAX

Resumo final para o próximo dev

Quantas camadas o BarberBot tem?
O BarberBot trabalha com 4 camadas práticas: interface, endpoint/ação, infraestrutura/conexão e banco de dados.

Essas camadas são separadas?
Não totalmente. Em vários módulos, principalmente em arquivos como listar.php, salvar.php e excluir.php, o sistema mistura regra de negócio, SQL, resposta AJAX e renderização HTML.

Como entender um módulo rápido?
Primeiro abrir o arquivo principal do módulo, depois analisar a pasta interna e seguir esta ordem: tela principal, listar, salvar, editar/buscar, excluir e tabelas do banco usadas pelo módulo.

Texto curto para reutilizar em outras docs

O BarberBot é um sistema monolítico em PHP puro, organizado por módulos. Cada módulo possui uma tela principal e uma pasta com arquivos operacionais como listar.php, salvar.php, editar.php e excluir.php. Na prática, o sistema possui quatro camadas: interface, endpoints internos, infraestrutura de conexão e banco de dados. Entretanto, essas camadas não são rigidamente separadas. Em vários arquivos, principalmente os de listagem e persistência, a lógica de negócio, o acesso ao banco e a renderização de HTML estão concentrados no mesmo ponto. Por isso, a manutenção deve sempre considerar entrada, regra, SQL e saída como partes do mesmo fluxo.