Módulo: Agendamentos (Painel) – BarberBot

CRUD de agendamentos • disponibilidade de horários • serviços por profissional • conclusão de atendimento (financeiro) • atualizado em 15/01/2026

pasta: sistema/painel/paginas/agendamentos padrão: AJAX → HTML/texto WhatsApp: lembretes/confirmar/cancelar

Este documento foi montado a partir do código real do módulo agendamentos. A ideia é o próximo dev bater o olho e entender: onde mexer, quais arquivos são chamados, quais tabelas do banco são afetadas e quais strings/contratos o front espera.

Escopo do módulo

Criar agendamento

Seleciona profissional, data, horário, cliente e serviço.
Valida disponibilidade e bloqueios.
Grava em agendamentos e “trava” horários em horarios_agd.

Listar e operar

Lista agendamentos do dia e exibe ações (excluir/cancelar, concluir atendimento).
Mostra status/valores e integra com DataTables (no HTML gerado).

Disponibilidade de horários

Gera horários com base no intervalo do profissional e na escala do dia (dias).
Remove horários já ocupados (horarios_agd), horários do passado (se data = hoje) e datas bloqueadas.

Concluir atendimento (financeiro)

Ao “fechar serviço”, cria/atualiza receber, movimenta caixas (se pago) e lança comissão em pagar.
Atualiza fidelidade/cartões e agenda retorno (rotinas em agendamentos_temp / API).

Estrutura de arquivos (no painel)

sistema/painel/paginas/
  ├─ agendamentos.php
  └─ agendamentos/
     ├─ listar.php
     ├─ inserir.php
     ├─ excluir.php
     ├─ listar-horarios.php
     ├─ listar-servicos.php
     └─ inserir-servico.php

agendamentos.php: página “container” (HTML do módulo) + JS (jQuery) chamando os endpoints via AJAX.
agendamentos/listar.php: retorna HTML da listagem (tabela) de agendamentos para o profissional selecionado.
agendamentos/listar-horarios.php: retorna HTML de horários disponíveis para uma data e um profissional.
agendamentos/listar-servicos.php: retorna as <option> dos serviços do profissional (servicos_func).
agendamentos/inserir.php: cria o agendamento e registra os “slots” ocupados em horarios_agd.
agendamentos/inserir-servico.php: fechamento do atendimento (gera financeiro + comissão + fidelidade + retorno).
agendamentos/excluir.php: exclui agendamento e libera horários ocupados.

Atenção (pasta/paths): os arquivos usam require_once("../../../conexao.php") e includes externos como ../../../../ajax/api-texto.php. Se você mover o módulo de lugar, ajuste os caminhos relativos.

Fluxo principal (tela → AJAX → banco)

1) Seleção do profissional

Sem profissional, listar.php responde com: Selecione um Funcionário! e encerra.
Ao selecionar, o front carrega:
- Serviços do profissional via listar-servicos.php
- Horários disponíveis via listar-horarios.php (após escolher data)
- Lista de agendamentos via listar.php

2) Criar agendamento

O form envia para agendamentos/inserir.php via POST.
O endpoint valida regras de agenda e disponibilidade (bloqueios, escala, slots já ocupados).
Cria registro em agendamentos e cria N registros em horarios_agd (um por intervalo ocupado).
Resposta de sucesso exata: Salvo com Sucesso.

3) Concluir atendimento

O módulo abre um modal (na listagem) e envia para agendamentos/inserir-servico.php.
Esse endpoint é o “ponto quente”: movimenta receber/caixas/pagar, além de atualizar fidelidade e retorno.
Resposta de sucesso exata: Salvo com Sucesso.

4) Excluir / cancelar agendamento

O front chama agendamentos/excluir.php passando id.
Esse endpoint remove em agendamentos e limpa os slots em horarios_agd.
Se existir integração de lembrete, também chama ../../../../ajax/agendar-delete.php usando o valor salvo em agendamentos.hash.
Resposta de sucesso exata: Excluído com Sucesso.

Endpoints AJAX e contratos

Endpoint	Método	Entradas (POST)	Saída
`agendamentos/listar.php`	POST	`funcionario`, `data`	HTML (tabela/listagem) • erros em texto (`Selecione um Funcionário!`)
`agendamentos/listar-horarios.php`	POST	`funcionario`, `data`	HTML (rádios/labels) • mensagens como `Não temos mais horários disponíveis...`
`agendamentos/listar-servicos.php`	POST	`funcionario`	HTML (`<option>`)
`agendamentos/inserir.php`	POST	`id`, `data`, `horario`, `cliente`, `funcionario`, `servico`, `obs`	Texto puro: `Salvo com Sucesso` ou mensagem de validação
`agendamentos/inserir-servico.php`	POST	`id_agd`, `id_servico`, `cliente_agd`, `funcionario_agd`, `subtotal`, `valor`, `comissao`, `descricao`, `obs`, `forma_pgto`, `data_retorno`, `cliente`, `funcionario`, `id`	Texto puro: `Salvo com Sucesso`
`agendamentos/excluir.php`	POST	`id`	Texto puro: `Excluído com Sucesso`

Contratos de string importam: o front do BarberBot compara mensagens de retorno. Se você trocar o texto, pode “quebrar” sucesso/erro (ex.: exclusão e salvamento).

Tabelas do banco tocadas

agendamentos: registro principal (cliente, funcionário, data/hora, serviço, status, hash, observação).
horarios_agd: “slots” ocupados (usado para bloquear horários no listar-horarios.php).
clientes: dados do cliente + fidelidade/cartões + data de retorno.
usuarios: dados do profissional (inclui intervalo e parâmetros usados para agenda).
dias: escala do profissional por dia da semana (abre/fecha/intervalo).
dias_bloqueio e dias_bloqueio_func: bloqueios globais e por profissional.
servicos e servicos_func: catálogo de serviços e vínculo serviço ↔ profissional.
formas_pgto: formas de pagamento (usadas no fechamento do atendimento).
receber: contas a receber geradas ao concluir serviço.
pagar: comissões/contas a pagar (com base no serviço e % definida).
caixas: movimentação de caixa (se o atendimento for baixado como pago).
agendamentos_temp: suporte a retorno/lembretes (usado no fechamento para próxima visita).

Dica de debug: quando “falta horário” no calendário, quase sempre o culpado é horarios_agd (slots presos), ou bloqueios em dias_bloqueio*. Comece por aí.

Regras de agenda (validações implementadas)

Bloqueios de data

Se a data estiver em dias_bloqueio: retorna Não estaremos funcionando nesta Data!
Se a data estiver em dias_bloqueio_func (para o profissional): retorna mensagem de indisponibilidade.

Escala do profissional

O módulo valida se o profissional trabalha no dia (tabela dias).
Se não trabalha: Este Funcionário não trabalha neste Dia!

Construção dos horários

Os horários são gerados usando o intervalo do profissional (usuarios.intervalo).
Horários já ocupados são lidos de horarios_agd.
Se a data for hoje, remove horários passados (comparação com horário atual).

Validação de conflito e duração do serviço

Ao salvar, inserir.php valida se o horário está disponível.
Também valida se o serviço “cabe” na agenda considerando o intervalo.

Melhor prática: para consistência, o bloqueio de agenda deve sempre ser centralizado em horarios_agd. Qualquer ação de criar/excluir agendamento deve inserir/remover os slots correspondentes.

Integrações (WhatsApp / notificações / lembretes)

WhatsApp – envio de mensagem de agendamento

inserir.php pode disparar mensagem via ../../../../ajax/api-texto.php.
O envio é controlado por configuração como $msg_agendamento.

Lembrete / agendamento automático (hash)

Quando $minutos_aviso > 0, inclui ../../../../ajax/confirmacao.php para agendar lembrete.
O valor é salvo em agendamentos.hash e usado em excluir.php para remover o lembrete com agendar-delete.php.

Notificações internas

Ao salvar, pode incluir ../../../../api/notid.php para notificar dentro do sistema.

Importante: se algum include não existir no servidor, o módulo pode gerar erro PHP/notice. Em produção, garanta paths corretos ou use file_exists().

Pontos críticos e melhorias recomendadas

1) SQL Injection (alto risco): há consultas montadas com variáveis direto na string SQL. Recomendação: padronizar em PDO::prepare() + bindValue().

2) Concorrência / “duplo clique”: duas requisições simultâneas podem criar agendamentos no mesmo slot. Recomendação: transação + índice único em horarios_agd(data, funcionario, horario).

3) Consistência financeira: inserir-servico.php mexe em receber, pagar e caixas. Recomendação: transação e logs (quem baixou, quando, IP).

4) Padronizar status: defina constantes/enum (Agendado, Confirmado, Concluído, Cancelado) e evite texto solto.

Checklist de manutenção

Não aparece horário: verifique dias, usuarios.intervalo, bloqueios (dias_bloqueio*) e slots em horarios_agd.
Não lista serviço: verifique vínculo em servicos_func e se o serviço está ativo em servicos.
WhatsApp não envia: valide config e paths no api-texto.php.
Financeiro inconsistente: audite receber, pagar e caixas no fechamento.

↑ voltar ao topo