Pular para o conteúdo principal

Feature - Criacao de Agendamento

Introducao ao documento​

Describe o fluxo de criacao de agendamento via API publica.

Versionamento​

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

Referencial teorico​

  • HTTP POST
  • Validacao de entrada
  • Regras de conflito temporal

Visao geral​

A feature cria agendamentos vinculando colaborador (employee), cliente (quando aplicavel) e tipo de atendimento.

Atores​

  • Sistema consumidor da API com API key valida.
  • Colaborador (employee) e cliente (client) referenciados por CPF.
  • Evidencia: routes/api.php:26
  • Evidencia: app/Http/Controllers/AppointmentController.php:133
  • Evidencia: app/Http/Controllers/AppointmentController.php:149

Pre-condicoes​

  • Header Authorization presente e valido.
  • employee_id (cpf) deve existir.
  • Para tipos individual/group/collective, client_id (cpf) deve existir.
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:22
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:39
  • Evidencia: app/Http/Controllers/AppointmentController.php:147

Fluxo principal​

  1. Recebe POST /api/appointments.
  2. Valida payload.
  3. Verifica conflito de horario.
  4. Persiste appointment.
  5. Dispara e-mail (exceto tipo block).
  6. Invalida cache de slots.
  • Evidencia: routes/api.php:28
  • Evidencia: app/Http/Controllers/AppointmentController.php:161
  • Evidencia: app/Http/Controllers/AppointmentController.php:172
  • Evidencia: app/Http/Controllers/AppointmentController.php:196
  • Evidencia: app/Http/Controllers/AppointmentController.php:198
  • Evidencia: app/Http/Controllers/AppointmentController.php:210

Fluxos alternativos​

  • 404 quando colaborador nao existe.
  • 404 quando cliente nao existe (tipos que exigem cliente).
  • 409 quando ha sobreposicao de horario.
  • 400 para validacao invalida.
  • Evidencia: app/Http/Controllers/AppointmentController.php:137
  • Evidencia: app/Http/Controllers/AppointmentController.php:153
  • Evidencia: app/Http/Controllers/AppointmentController.php:176
  • Evidencia: app/Http/Controllers/AppointmentController.php:223

Regras de negocio​

  • class_id e obrigatorio e aceita numero ou texto alfabetico.
  • employee_id entra por CPF e e convertido para id interno.
  • Tipos group nao bloqueiam por conflito no checkForConflicts.
  • Evidencia: app/Http/Controllers/AppointmentController.php:166
  • Evidencia: app/Http/Controllers/AppointmentController.php:133
  • Evidencia: app/Http/Controllers/AppointmentController.php:447

Estados possiveis​

  • Criado (201)
  • Rejeitado por validacao (400)
  • Nao encontrado (404)
  • Conflito (409)

Endpoints envolvidos​

  • POST /api/appointments (ver ../api/openapi.yaml)

Dados impactados​

  • appointments
  • clients (lookup)
  • employees (lookup)
  • types (lookup)
  • cache (chave de slots)
  • Referencia: ../data/model.md

Pendencias​

  • Comentario de codigo indica pendencia de reativacao de cache no index de appointments.
  • Evidencia: app/Http/Controllers/AppointmentController.php:31