Pular para o conteúdo principal

Feature - Cancelamento de Agendamento

Introducao ao documento​

Detalha o cancelamento de agendamento com validacao por CPF do colaborador e notificacoes.

Versionamento​

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

Referencial teorico​

  • HTTP DELETE
  • Integridade de ownership de recurso

Visao geral​

A feature remove (soft delete) um appointment quando o colaborador do request corresponde ao colaborador do agendamento.

Atores​

  • Sistema consumidor da API.
  • Colaborador dono do agendamento.
  • Evidencia: routes/api.php:29
  • Evidencia: app/Http/Controllers/AppointmentController.php:383
  • Evidencia: app/Http/Controllers/AppointmentController.php:396

Pre-condicoes​

  • API key valida.
  • Agendamento e colaborador devem existir.
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:39
  • Evidencia: app/Http/Controllers/AppointmentController.php:384

Fluxo principal​

  1. Recebe DELETE /api/appointments/{id}/cpf/{cpf}.
  2. Resolve employee por cpf e appointment por id.
  3. Valida ownership (appointment.employee_id == employee.id).
  4. Remove appointment e invalida cache de slots.
  5. Dispara e-mail de cancelamento para tipos > 1.
  • Evidencia: routes/api.php:29
  • Evidencia: app/Http/Controllers/AppointmentController.php:396
  • Evidencia: app/Http/Controllers/AppointmentController.php:397
  • Evidencia: app/Http/Controllers/AppointmentController.php:401
  • Evidencia: app/Http/Controllers/AppointmentController.php:403

Fluxos alternativos​

  • 500 quando ownership falha (tentativa de excluir agenda de outro colaborador).
  • 404 para id/cpf nao encontrados.
  • Evidencia: app/Http/Controllers/AppointmentController.php:416
  • Evidencia: app/Http/Controllers/AppointmentController.php:427

Regras de negocio​

  • Tipo 1 nao envia e-mail de cancelamento.
  • Mensagem de cancelamento difere para tipo individual e coletivo.
  • Evidencia: app/Http/Controllers/MailController.php:130
  • Evidencia: app/Http/Controllers/MailController.php:140
  • Evidencia: app/Http/Controllers/MailController.php:158

Estados possiveis​

  • Cancelado com sucesso (200)
  • Nao encontrado (404)
  • Erro de regra/execucao (500)

Endpoints envolvidos​

  • DELETE /api/appointments/{id}/cpf/{cpf} (ver ../api/openapi.yaml)

Dados impactados​

  • appointments (soft delete)
  • cache (forget)
  • fila de e-mails
  • Referencia: ../data/model.md

Pendencias​

  • O endpoint retorna 500 para falha de ownership; tecnicamente um 403 pode ser mais adequado.
  • Evidencia: app/Http/Controllers/AppointmentController.php:416