Módulo: Agenda e Agendamentos – Painel Admin

Documentação técnica do módulo Agenda (sistema/painel/paginas/agenda.php + sistema/painel/paginas/agenda/). Inclui listagem, inserção, exclusão, horários disponíveis e vincular serviço/pagamento.
Atualizado em 14/01/2026

Este documento é baseado no código-fonte do módulo de agenda do BarberBot. A ideia é deixar claro o que cada arquivo faz, quais tabelas ele toca, quais retornos o front espera e quais pontos merecem atenção em manutenção/segurança.

Estrutura de pastas e arquivos

sistema/painel/paginas/
  ├─ agenda.php
  └─ agenda/
      ├─ listar.php
      ├─ inserir.php
      ├─ excluir.php
      ├─ inserir-servico.php
      └─ listar-horarios.php
  • agenda.php – tela do módulo (UI + modais + scripts de interação).
  • agenda/listar.php – monta a listagem do dia/período (HTML injetado via AJAX).
  • agenda/inserir.php – cria agendamento e registra horários associados.
  • agenda/excluir.php – exclui agendamento e limpa referências (ex.: horarios_agd).
  • agenda/inserir-servico.php – vincula serviço ao agendamento e processa rotinas financeiras (receber/caixa/comissão).
  • agenda/listar-horarios.php – calcula horários disponíveis conforme dia, funcionário e regras de bloqueio.
Observação: o padrão do projeto é separar a tela “wrapper” (arquivo na raiz, ex.: agenda.php) dos endpoints (subpasta com listar.php, inserir.php, etc.). Isso facilita manter o JavaScript da tela simples (apenas chamando os endpoints).

Telas, modais e componentes

1) Tela principal (agenda.php)

  • Mostra o painel da agenda e carrega a listagem via listar() (AJAX).
  • Carrega dados de usuarios (funcionários) e servicos_func (serviços por funcionário) para os selects.

2) Modal “Novo Agendamento”

  • Campos típicos: cliente, funcionario, servico, data, hora, obs e recorrência (quando habilitada).
  • No submit, chama agenda/inserir.php e depois recarrega a listagem.

3) Modal “Vincular Serviço / Pagamento”

  • Usado para finalizar o atendimento e gerar registros financeiros (ex.: receber, comissões, movimento de caixa).
  • Campos do fluxo: id_agendamento, servico, funcionario, pgto, data_pgto, descontos/observações.
  • No submit, chama agenda/inserir-servico.php.
Dica de manutenção: se algum campo “some” na UI, confirme se ele está sendo alimentado no PHP (agenda.php) e se o name/id do input bate com o que os endpoints esperam.

Endpoints do módulo (AJAX)

agenda/listar.php

  • Função: renderiza a lista de agendamentos (normalmente no dia selecionado).
  • Saída: HTML pronto para ser injetado no container da página (não é JSON).

agenda/inserir.php

  • Função: cria agendamento e vincula horários.
  • Saída: string de sucesso/erro (o front usa isso para alertas).

agenda/excluir.php

  • Função: remove o agendamento e apaga registros dependentes (horarios_agd).
  • Extra: se existir “hash de integração”, chama rotina externa para cancelar.

agenda/inserir-servico.php

  • Função: finaliza o agendamento com serviço executado e registra financeiro.
  • Rotinas: valida receber, busca serviço/profissional, valida caixa aberto, registra receber e (quando aplicável) pagar, atualiza status.

agenda/listar-horarios.php

  • Função: calcula e retorna horários disponíveis.
  • Regras: usa dias, bloqueios e ocupação (horarios_agd).

Regras de negócio e validações

  • Conflito de horário: não permite criar agendamento em horário já reservado.
  • Disponibilidade por dia: valida se o dia está habilitado em dias para o funcionário.
  • Bloqueios: respeita bloqueio global e por funcionário.
  • Serviço por profissional: lista serviços a partir de servicos_func.
  • Fechamento financeiro: ao vincular serviço, cria receber e registra comissão (pagar) quando aplicável.
Regra prática: inserir-servico.php existe para concluir atendimento sem abrir outra tela (atalho operacional).

Tabelas/tópicos de banco envolvidos

  • agendamentos, horarios_agd, dias, dias_bloqueio, dias_bloqueio_func
  • usuarios, clientes, servicos, servicos_func
  • formas_pgto, receber, caixas, pagar

Contratos de retorno (strings)

Os endpoints retornam strings que o JavaScript usa para decidir se mostra “sucesso” ou “erro”. Manter esses textos é importante para não quebrar a UI.

  • agenda/inserir.php: Salvo com Sucesso, Esse horário já está reservado!, O Funcionário não trabalha nesse dia!, Erro ao Salvar.
  • agenda/inserir-servico.php: sucesso observado Salvo com Sucesso.
  • agenda/excluir.php: geralmente Excluído com Sucesso (e possíveis retornos de integração).
Boa prática: se evoluir para JSON, crie endpoint novo e migre o front aos poucos.

Pontos críticos e melhorias recomendadas

  • SQL Injection: migrar endpoints de escrita para prepare().
  • Permissões: checar sessão/perfil antes de inserir/excluir/finalizar.
  • Concorrência: validar conflito no banco (transação/lock) em alto volume.
  • Logs: registrar exclusões/finalizações (auditoria).
Recomendação rápida: comece pelos endpoints de escrita (inserir.php, inserir-servico.php, excluir.php).

Checklist de testes

  1. Criar agendamento em horário livre (retorno: Salvo com Sucesso).
  2. Tentar criar no mesmo horário (retorno: Esse horário já está reservado!).
  3. Testar funcionário em dia não trabalhado (retorno: O Funcionário não trabalha nesse dia!).
  4. Validar bloqueio global e por funcionário (horário some do listar-horarios.php).
  5. Finalizar serviço e confirmar receber e comissão em pagar.
  6. Excluir agendamento e confirmar remoção em agendamentos e horarios_agd.