Guia operacional do projeto

Boas práticas e manutenção do BarberBot

Página de referência para manter o sistema estável, seguro e consistente. O objetivo aqui não é só listar regras, mas dar ao próximo desenvolvedor uma visão clara do que fazer, do que evitar e do que revisar antes de publicar.

Foco principal Segurança, legibilidade e manutenção
Stack base PHP puro, JS puro e MySQL
Uso recomendado Consulta rápida antes de alterar módulos
Como usar esta página

Leia como um checklist de manutenção, não como texto institucional

Sempre que um módulo for alterado, o ideal é revisar esta página junto com as páginas de convenções, depuração e fluxo entre pastas. Assim o dev não corrige um ponto quebrando outro.

Base do projeto

Princípios que guiam o BarberBot

Estas regras ajudam a manter o sistema previsível, fácil de evoluir e menos propenso a bugs escondidos.

Clareza antes de complexidade

Prefira soluções fáceis de entender por outro dev. Em PHP puro, legibilidade vale mais do que “engenhosidade”.

Consistência entre módulos

Se um módulo usa listar.php, salvar.php, buscar.php e excluir.php, os próximos devem seguir o mesmo padrão.

Banco e tela precisam conversar bem

Os nomes dos campos, regras de validação e mensagens devem refletir o comportamento real do banco de dados.

Corrigir sem espalhar lógica

Evite duplicar regra de negócio em várias páginas. Ao corrigir, procure o ponto mais central da lógica.

Estrutura

Organização do código

O que seguir

  • Separar a tela principal do módulo dos endpoints internos.
  • Usar includes reutilizáveis para cabeçalho, rodapé e trechos comuns.
  • Centralizar a conexão e configurações globais em arquivos previsíveis.
  • Manter o módulo com responsabilidades reconhecíveis: tela, listagem, gravação, busca e exclusão.

O que evitar

  • HTML demais dentro de arquivos que já concentram muita regra.
  • Copiar e colar queries sem revisar filtros e parâmetros.
  • Endpoint fora da pasta do módulo, dificultando rastreio.
  • Variáveis genéricas demais, como $dado, $valor ou $res.
paginas/nome_modulo.php
paginas/nome_modulo/listar.php
paginas/nome_modulo/salvar.php
paginas/nome_modulo/buscar.php
paginas/nome_modulo/excluir.php

Essa estrutura ajuda qualquer dev a saber onde procurar quando precisar listar, salvar, buscar ou excluir.

Obrigatório

Segurança

PDO sempre com parâmetros

Use prepare() e bindValue() em toda entrada dinâmica. SQL interpolado é um dos riscos mais comuns em manutenção.

Validação de entrada

Todo dado vindo de $_POST, $_GET, upload ou sessão deve ser validado e convertido antes de entrar em regra ou query.

Saída segura

Ao imprimir valores vindos do banco ou do usuário, trate a saída para reduzir risco de XSS e quebra de layout.

Sessão e permissão

Antes de executar ação sensível, confirme se a sessão está ativa e se o usuário pode realmente executar aquela operação.

Atenção: em um sistema que mistura interface, regra e SQL no mesmo módulo, uma falha pequena em listar.php ou salvar.php pode virar ao mesmo tempo bug funcional, falha de permissão e risco de segurança.
Eficiência

Performance

Consultas

Usar LIMIT, filtros coerentes e índices nas colunas de busca e relacionamento.

Loop e banco

Evitar consultas dentro de laços quando um JOIN ou uma busca mais bem montada resolve de forma mais barata.

Front-end

Não carregar script ou estilo desnecessário em páginas simples. Menos peso melhora manutenção e resposta visual.

Rotinas automáticas

Em cron e integrações, registrar o mínimo necessário para diagnóstico sem deixar o processo pesado demais.

Rotina do time

Manutenção preventiva

Antes de alterar

  • Entender qual arquivo é tela e qual arquivo é endpoint.
  • Mapear as tabelas envolvidas.
  • Verificar se existe AJAX, modal e retorno de mensagem dependente daquela ação.

Durante a alteração

  • Preservar nomes e contratos que a interface já espera.
  • Evitar mudar saída HTML/JSON sem revisar o JavaScript que consome.
  • Adicionar validação no backend mesmo que a tela já valide.

Depois de alterar

  • Testar listagem, cadastro, edição, exclusão e retorno visual.
  • Conferir se a sessão continua válida no fluxo completo.
  • Rodar testes manuais com cenário feliz e cenário de erro.
Checklist final

Antes de publicar em produção

Leitura complementar

Páginas que combinam com este guia

Convenções do BarberBot Padroniza nomes de arquivos, variáveis, AJAX e uso de PDO. Como depurar um módulo Passo a passo para achar bug em listagem, gravação, sessão, SQL e AJAX. Fluxo entre pastas Ajuda a seguir o caminho tela → endpoint → conexão → banco. Banco de dados Consulta rápida das tabelas e dos relacionamentos mais usados pelo sistema.