Documentação Técnica - Convenções do BarberBot

Base do padrão

Como o próximo dev deve ler esta página

Objetivo

Padronizar a criação e a manutenção de módulos para que qualquer dev encontre a mesma lógica de navegação, nomes parecidos, respostas previsíveis e SQL seguro em todo o sistema.

Mesmo nome do módulo na tela e na pasta interna.
Mesma ordem mental: tela, listar, salvar, buscar, excluir.
Mesmo padrão de retorno para AJAX.
Mesmo padrão de modal e de IDs de formulário.

Regra prática

Sempre que criar ou ajustar um módulo, o dev deve manter o mesmo desenho do restante do BarberBot. Isso evita arquivos improvisados, nomes fora do padrão e bugs causados por respostas diferentes em cada página.

Evitar nomes em inglês quando o restante do módulo está em português.
Evitar criar endpoints fora da pasta do módulo sem necessidade.
Evitar mudar o formato de resposta sem atualizar o AJAX da tela.

Padrão de nomes

Nomes de arquivos e organização de pastas

Arquivo principal da tela

O arquivo principal fica direto em /sistema/painel/paginas e deve ter o mesmo nome da pasta operacional. Exemplo: clientes.php trabalha com a pasta clientes/.

Pasta operacional do módulo

Dentro da pasta do módulo devem ficar os arquivos internos responsáveis por listar, salvar, buscar e excluir. O ideal é não espalhar esses arquivos em diretórios aleatórios.

Estrutura recomendada

/public_html/sistema/painel/paginas/clientes.php
/public_html/sistema/painel/paginas/clientes/listar.php
/public_html/sistema/painel/paginas/clientes/salvar.php
/public_html/sistema/painel/paginas/clientes/buscar.php
/public_html/sistema/painel/paginas/clientes/excluir.php

`nome_modulo.php`

Responsável pela interface, filtros, modais e chamadas AJAX.

`listar.php`

Retorna a listagem do módulo, normalmente em HTML.

`salvar.php`

Recebe formulário, valida campos e grava ou atualiza o banco.

`buscar.php`

Busca um item específico para preencher modal ou formulário de edição.

`excluir.php`

Remove o registro e devolve status simples para a tela.

Arquivos extras

Somente quando o módulo exigir fluxo específico, como processar.php ou gerar_ia.php.

Padrão de escrita

Convenções de variáveis

Variáveis PHP

Usar snake_case para seguir o padrão atual do projeto: $id_usuario, $data_inicial.
Quando o projeto já usa nomes curtos consolidados, manter consistência: $pag, $pdo, $tabela.
Variáveis vindas de formulário devem refletir o nome do campo: $nome, $telefone, $valor.
IDs devem ser explícitos: $id para o principal, $id_cliente para relacionamentos.

Variáveis JavaScript

Seguir o mesmo nome da interface: id, busca, pagina, dataInicial se já estiver em camelCase na tela.
O nome da variável usada no AJAX deve bater com o nome que o PHP espera.
IDs e seletores devem ser previsíveis: #listar, #form, #mensagem, #tituloModal.

Regra importante

Não misturar nomes diferentes para a mesma coisa. Se o campo no form chama telefone, não use $fone no PHP, phone no JS e contato no banco. Essa variação aumenta erro de manutenção.

Comunicação interna

Padrão de rotas AJAX

Em módulos do painel, o padrão do BarberBot é a tela principal disparar AJAX para a subpasta do próprio módulo. O dev deve preservar esse desenho sempre que possível.

Listagem

function listar(){
  var busca = $('#busca').val();

  $.ajax({
    url: 'paginas/' + pag + '/listar.php',
    method: 'POST',
    data: { busca: busca },
    dataType: 'html',
    success: function(resposta){
      $('#listar').html(resposta);
    }
  });
}

Salvamento

$('#form').on('submit', function(e){
  e.preventDefault();

  $.ajax({
    url: 'paginas/' + pag + '/salvar.php',
    method: 'POST',
    data: new FormData(this),
    processData: false,
    contentType: false,
    success: function(resposta){
      if(resposta.trim() === 'Salvo com Sucesso'){
        $('#modalForm').modal('hide');
        listar();
      }else{
        $('#mensagem').text(resposta);
      }
    }
  });
});

Convenções recomendadas

A tela principal deve usar a variável pag para montar a URL.
listar.php normalmente responde HTML.
buscar.php normalmente responde JSON quando preenche modal.
salvar.php e excluir.php normalmente respondem texto simples.

Erros comuns

Trocar o nome da pasta e esquecer de atualizar a variável pag.
Mudar o tipo de retorno e não ajustar o AJAX.
Criar endpoint fora da pasta do módulo sem documentar a chamada.

Retorno previsível

Padrão de mensagens de sucesso e erro

Sucesso de gravação

Usar resposta curta e objetiva, por exemplo: Salvo com Sucesso.

Sucesso de exclusão

Usar resposta curta e objetiva, por exemplo: Excluído com Sucesso.

Erro de validação

Informar o problema real, por exemplo: Preencha o nome ou Selecione um cliente.

Regra de consistência

A tela geralmente compara a resposta com uma string exata. Por isso, o texto de retorno do PHP não deve mudar sem que o JavaScript da tela seja atualizado. Alterar Salvo com Sucesso para outro texto sem revisar o AJAX costuma quebrar o fechamento do modal e a atualização da listagem.

Interface repetível

Organização de modais

Estrutura base de modal

<div class="modal fade" id="modalForm" tabindex="-1" aria-hidden="true">
  <div class="modal-dialog modal-lg">
    <div class="modal-content">
      <form id="form">
        <div class="modal-header">
          <h5 class="modal-title" id="tituloModal">Cadastrar registro</h5>
          <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
        </div>

        <div class="modal-body">
          <input type="hidden" name="id" id="id">
          <div class="row">
            <div class="col-md-12">
              <label>Nome</label>
              <input type="text" class="form-control" name="nome" id="nome" required>
            </div>
          </div>
          <small id="mensagem" class="text-danger"></small>
        </div>

        <div class="modal-footer">
          <button type="submit" class="btn btn-primary">Salvar</button>
        </div>
      </form>
    </div>
  </div>
</div>

IDs recomendados

#modalForm para o modal principal do cadastro.
#form para o formulário principal.
#tituloModal para alternar entre cadastrar e editar.
#mensagem para mostrar retorno do backend.
#id como campo oculto do registro.

Boas práticas

Limpar o formulário antes de abrir modal de novo cadastro.
Ao editar, preencher os campos com buscar.php antes de exibir o modal.
Não reutilizar o mesmo ID em modais diferentes.
Manter os botões e a ordem visual parecidos entre módulos.

Persistência

Uso de PDO e padrão mínimo de SQL

Exemplo de buscar.php

<?php
require_once("../../../conexao.php");
@session_start();

$id = (int)($_POST['id'] ?? 0);

$query = $pdo->prepare("SELECT * FROM clientes WHERE id = :id LIMIT 1");
$query->bindValue(':id', $id, PDO::PARAM_INT);
$query->execute();

$res = $query->fetch(PDO::FETCH_ASSOC);

if(!$res){
  echo 'Registro não encontrado';
  exit();
}

echo json_encode([
  'id'   => $res['id'],
  'nome' => $res['nome']
], JSON_UNESCAPED_UNICODE);

Exemplo de salvar.php

<?php
require_once("../../../conexao.php");
@session_start();

$id   = (int)($_POST['id'] ?? 0);
$nome = trim($_POST['nome'] ?? '');

if($nome === ''){
  echo 'Preencha o nome';
  exit();
}

if($id > 0){
  $query = $pdo->prepare("UPDATE clientes SET nome = :nome WHERE id = :id");
  $query->bindValue(':nome', $nome);
  $query->bindValue(':id', $id, PDO::PARAM_INT);
  $query->execute();
}else{
  $query = $pdo->prepare("INSERT INTO clientes SET nome = :nome, data_cad = curDate()");
  $query->bindValue(':nome', $nome);
  $query->execute();
}

echo 'Salvo com Sucesso';

O que seguir sempre

Usar $pdo->prepare().
Usar bindValue() para dados vindos de formulário ou URL.
Converter IDs para inteiro antes de usar.
Validar campos obrigatórios antes de executar SQL.

O que evitar

Interpolar $_POST e $_GET direto na query.
Executar SQL diferente em cada módulo para o mesmo comportamento sem necessidade.
Retornar mensagens genéricas demais quando o erro é validável.
Esquecer LIMIT 1 quando a busca é por ID único.

Checklist

Checklist final antes de subir um módulo

Arquivos e nomes

A tela principal tem o mesmo nome da pasta do módulo.
Os arquivos internos seguem o padrão listar, salvar, buscar, excluir.
Não existem endpoints duplicados para a mesma função.

AJAX e retorno

A tela chama a pasta correta do módulo.
O tipo de retorno do PHP bate com o esperado no JavaScript.
As mensagens de sucesso e erro estão padronizadas.

Modal e interface

Os IDs do modal seguem o padrão do sistema.
O formulário limpa corretamente ao abrir novo cadastro.
A edição preenche os dados corretos antes de abrir o modal.

SQL e segurança

Todo dado externo passa por prepare e bindValue.
IDs foram convertidos para inteiro.
Campos obrigatórios foram validados.
O módulo passou em teste de listagem, cadastro, edição e exclusão.