Módulo: Clientes, Usuários e Funcionários – BarberBot

🧭 Atalhos (para o dev se achar rápido)

📁 Estrutura (pasta do painel)

Caminho padrão no BarberBot: sistema/painel/paginas/. Os módulos abaixo costumam existir como subpastas.

sistema/painel/paginas/
  ├─ clientes/
  │   ├─ listar.php
  │   ├─ salvar.php
  │   ├─ excluir.php
  │   ├─ ... (extras: cobrar/recorrência/contrato/anexos)
  │
  ├─ usuarios/
  │   ├─ listar.php
  │   ├─ salvar.php
  │   ├─ excluir.php
  │   ├─ mudar-status.php
  │   ├─ listar-permissoes.php
  │   ├─ add-permissao.php | add-permissoes.php
  │   └─ limpar-permissoes.php
  │
  ├─ funcionarios/
  │   ├─ listar.php
  │   ├─ salvar.php
  │   ├─ excluir.php
  │   ├─ mudar-status.php
  │   ├─ inserir-horario.php | listar-horarios.php | excluir-horarios.php
  │   ├─ inserir-dias.php    | listar-dias.php     | excluir-dias.php
  │   └─ inserir-servico.php | listar-servicos.php  | excluir-servico.php
  │
  └─ grupos/ e acessos/ (quando usado)
      ├─ listar.php
      ├─ salvar.php
      └─ excluir.php

• Padrão listar.php retorna HTML/linhas para tabela/lista.
• Padrão salvar.php faz INSERT/UPDATE (PDO) e retorna string de sucesso/erro.
• Padrão excluir.php remove (ou inativa) e retorna string de sucesso/erro.
• Atenção Alguns módulos retornam mensagens “exatas” para o JS (ex.: Excluído com Sucesso).

👤 Clientes (cadastro + relacionamento + cobrança)

O cliente é a entidade central do atendimento. Além do cadastro básico, o módulo costuma integrar: histórico de visitas/agendamentos, cobranças/recorrência, anexos, contratos e relacionamento (marketing/retorno).

Arquivos típicos

• listar.php – Lista clientes com filtros (nome, telefone, status, data).
• salvar.php – Cria/edita cliente (dados pessoais e preferências).
• excluir.php – Exclui (ou inativa) um cliente.
• listar_cobrancas.php / listar_debitos.php – Visões financeiras do cliente.
• gerar_cobranca.php – Gera cobrança vinculada ao financeiro.
• recorrencia.php – Rotinas de cobrança recorrente/assinatura.
• salvar-contrato.php / texto-contrato.php – Contratos (quando habilitado).

Pontos críticos (clientes)

• LGPD minimização de dados: guarde só o necessário e controle acesso por perfil.
• Validação normalize telefone/CPF e valide duplicidade por documento/telefone.
• Integridade antes de excluir: checar dependências (agendamentos, vendas, cobranças).
• Auditoria registrar: quem alterou, quando, e o que mudou (ideal: logs).

🧑‍💻 Usuários (contas de acesso ao painel)

Usuários são contas do painel (admin, gerente, atendente etc). O controle de acesso geralmente é feito por grupos/perfis + permissões por módulo.

Arquivos típicos

• listar.php – Lista usuários do painel.
• salvar.php – Cria/edita usuário (nome, login, senha, grupo, status).
• mudar-status.php – Ativa/inativa (ou bloqueia) sem excluir o registro.
• excluir.php – Remove usuário (recomendado: preferir inativar).
• listar-permissoes.php – Exibe permissões atuais.
• add-permissao.php / add-permissoes.php – Concede permissão(ões).
• limpar-permissoes.php – Remove permissões do usuário.

Pontos críticos (usuários)

• Privilégio impedir escalonamento: usuário não pode dar permissão acima do próprio perfil.
• Senha nunca gravar senha em texto puro; sempre hash (ex.: password_hash).
• Sessão bloquear usuários inativos no login e invalidar sessão em mudança de status.
• Rastreio logar alterações de permissão (quem concedeu/removeu).

💈 Funcionários (profissionais + agenda + serviços)

Funcionários são os profissionais que atendem. O módulo geralmente controla: cadastro, status, dias/horários disponíveis e quais serviços cada profissional executa.

Arquivos típicos

• listar.php – Lista profissionais.
• salvar.php – Cria/edita profissional.
• mudar-status.php – Ativa/inativa.
• inserir-dias.php / listar-dias.php / excluir-dias.php – Dias disponíveis.
• inserir-horario.php / listar-horarios.php / excluir-horarios.php – Horários.
• inserir-servico.php / listar-servicos.php / excluir-servico.php – Serviços vinculados.
• excluir.php – Exclui (preferível: inativar se houver histórico).

Pontos críticos (funcionários)

• Agenda ao inativar, decidir: cancela futuros agendamentos ou mantém e remaneja?
• Conflitos validar overlap de horário (não permitir intervalos que se cruzam).
• Serviços ao remover serviço do profissional, checar agendamentos futuros daquele serviço.
• Performance listagens grandes: indexar por funcionario, data, status.

🔑 Permissões & Grupos (visão prática)

O BarberBot costuma separar perfil/grupo (papel) de permissões por módulo (o que pode abrir/executar). O padrão é: telas do painel verificam permissões; endpoints também devem validar.

• grupos/ – define perfis (Admin, Gerente, Atendente...).
• acessos/ – mapeia quais páginas/módulos um perfil ou usuário pode acessar.
• Obrigatório validar permissão no backend (não confiar em menu/JS).

🔄 Fluxos críticos (resumo)

1) Onboarding de um novo negócio / usuário admin

1. Cria usuário (admin) → define grupo/perfil.
2. Vincula permissões (por grupo ou por usuário).
3. Cria funcionários (profissionais) e define agenda e serviços.
4. Cadastra clientes e inicia atendimentos/agendamentos.

2) Cadastro de funcionário com agenda

1. funcionarios/salvar.php cria o profissional.
2. funcionarios/inserir-dias.php define dias disponíveis.
3. funcionarios/inserir-horario.php define horários por dia.
4. funcionarios/inserir-servico.php vincula serviços.

3) Gestão de permissões

1. Admin abre usuarios/listar-permissoes.php.
2. Concede via add-permissao(s).php ou limpa via limpar-permissoes.php.
3. Endpoints sensíveis devem registrar log do evento.

🛡️ Segurança (sem frescura)

• PDO sempre usar prepare() + bind (evitar SQL Injection).
• ID validar IDs recebidos ((int)) e checar existência.
• Permissão checar sessão + permissão no endpoint, não só na tela.
• Uploads validar MIME/extensão e bloquear execução nas pastas de upload.
• Logs registrar ações críticas: excluir, mudar-status, permissão, baixa financeira.

✅ Checklist rápido (para o próximo dev)

• Confirmar quais arquivos extras existem em clientes/ (cobrança/contrato/recorrência).
• Em usuarios/, garantir que mudar-status.php invalida sessões ativas (se aplicável).
• Em funcionarios/, validar conflito de horários e efeito em agendamentos futuros.
• Revisar mensagens retornadas pelos endpoints (JS pode depender de texto exato).
• Garantir índices no banco para listagens grandes (clientes, agendamentos, receber/pagar).
• Garantir que permissões são verificadas também em endpoints (não só em menu/tela).