Pular para o conteúdo principal

Feature - Consulta de Slots Disponiveis

Introducao ao documento​

Documenta a consulta de disponibilidade de horarios para colaborador em um dia especifico.

Versionamento​

  • Versao do documento: 1.0.0
  • Ultima atualizacao: 2026-03-17
  • Responsavel: GitHub Copilot

Referencial teorico​

  • Time-slot scheduling
  • Caching de leitura

Visao geral​

A feature retorna slots disponiveis em duas modalidades: geral e mentoria em grupo.

Atores​

  • Sistema consumidor da API com API key.
  • Evidencia: routes/api.php:30
  • Evidencia: routes/api.php:31

Pre-condicoes​

  • employee_cpf valido para um colaborador existente.
  • date em formato valido para parse no model.
  • Evidencia: app/Http/Controllers/AppointmentController.php:538
  • Evidencia: app/Models/Appointment.php:91

Fluxo principal​

  1. GET /api/appointments/slots/{date}/employee/{employee_cpf}/client/{client}.
  2. Busca em cache pela chave composta.
  3. Se miss, calcula slots e armazena por 600 segundos.
  4. Retorna lista de objetos id/date/time.
  • Evidencia: app/Http/Controllers/AppointmentController.php:581
  • Evidencia: app/Http/Controllers/AppointmentController.php:583
  • Evidencia: app/Http/Controllers/AppointmentController.php:601
  • Evidencia: app/Models/Appointment.php:117

Fluxo alternativo (grupo)​

  • GET /api/appointments/slots/group/{date}/employee/{employee_cpf}/client/{client}.
  • Permite concorrencia quando o tipo existente for group e retorna appointment_count.
  • Evidencia: routes/api.php:31
  • Evidencia: app/Models/Appointment.php:171
  • Evidencia: app/Models/Appointment.php:191

Regras de negocio​

  • Grade e incrementada em passos de 60 minutos.
  • Horarios ocupados por tipos nao-group bloqueiam slot.
  • Evidencia: app/Models/Appointment.php:100
  • Evidencia: app/Models/Appointment.php:150
  • Evidencia: app/Models/Appointment.php:172

Estados possiveis​

  • Retorno de cache ou banco com status 200
  • employee nao encontrado (404)
  • erro interno (500)
  • Evidencia: app/Http/Controllers/AppointmentController.php:585
  • Evidencia: app/Http/Controllers/AppointmentController.php:595
  • Evidencia: app/Http/Controllers/AppointmentController.php:624

Endpoints envolvidos​

  • GET /api/appointments/slots/{date}/employee/{employee_cpf}/client/{client}
  • GET /api/appointments/slots/group/{date}/employee/{employee_cpf}/client/{client}

Dados impactados​

  • appointments (consulta)
  • cache (read/write)
  • Referencia: ../data/model.md

Pendencias​

  • O parametro client existe na rota, mas nao participa da assinatura dos metodos.
  • Evidencia: routes/api.php:30
  • Evidencia: app/Http/Controllers/AppointmentController.php:577