Pular para o conteúdo principal

Arquitetura C4 L3

Introducao ao documento​

Este documento descreve o contexto e os componentes internos da aplicacao, focando em pontos de mudanca com potencial de quebra (rotas, regras de agendamento, auth, fila e integracoes).

Versionamento​

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

Referencial teorico​

  • C4 Model (Simon Brown)
  • Laravel 11 Architecture
  • RFC 7231 (HTTP semantics)

Responsabilidade do servico​

  • Expor API de agendamentos e cadastro de clientes/colaboradores.
  • Expor painel administrativo com controle de acesso por papeis/permissoes.
  • Executar notificacoes por e-mail associadas a criacao/cancelamento de agendamentos.
  • Exportar agenda consolidada para CSV e armazenar no S3.
  • Evidencia: routes/api.php:27
  • Evidencia: routes/web.php:35
  • Evidencia: app/Http/Controllers/MailController.php:43
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:92

Dependencias​

  • DB MySQL para persistencia principal.
  • Redis para cache/fila/Horizon.
  • S3 para artefatos de exportacao.
  • SMTP para envio de e-mails.
  • Evidencia: docker-compose.yml:22
  • Evidencia: docker-compose.yml:42
  • Evidencia: config/filesystems.php:45
  • Evidencia: config/mail.php:31

Componentes internos por camada​

Camada de Interface HTTP​

  • routes/api.php (API publica com api_key + API admin v1 com auth:api).
  • routes/web.php (painel admin autenticado).
  • Evidencia: routes/api.php:26
  • Evidencia: routes/api.php:55
  • Evidencia: routes/web.php:35

Camada de Aplicacao (Controllers)​

  • AppointmentController: regras de validacao, conflito de horario, slots e movimentacao de agenda.
  • ClientController e EmployeeController: CRUD e busca por CPF.
  • ExportAppointmentsController: extracao SQL + upload S3.
  • Evidencia: app/Http/Controllers/AppointmentController.php:161
  • Evidencia: app/Http/Controllers/AppointmentController.php:445
  • Evidencia: app/Http/Controllers/ClientController.php:46
  • Evidencia: app/Http/Controllers/EmployeeController.php:50
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:20

Camada de Dominio (Models)​

  • Appointment, AppointmentType, Client, Employee como nucleo funcional.
  • Relacoes belongsTo entre appointment-client/employee/type.
  • Regras de disponibilidade e agrupamento de slots no model Appointment.
  • Evidencia: app/Models/Appointment.php:34
  • Evidencia: app/Models/Appointment.php:42
  • Evidencia: app/Models/Appointment.php:50
  • Evidencia: app/Models/Appointment.php:84
  • Evidencia: app/Models/Appointment.php:134

Camada de Seguranca e Autorizacao​

  • ApiKeyMiddleware valida header Authorization contra tabela api_keys.
  • AuthGates constroi gates dinamicos a partir de roles/permissoes.
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:22
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:39
  • Evidencia: app/Http/Middleware/AuthGates.php:16
  • Evidencia: app/Http/Middleware/AuthGates.php:26

Camada de Assincronia​

  • Mails implementam ShouldQueue.
  • Queue driver configuravel e Horizon com supervisor redis.
  • Evidencia: app/Mail/AppointmentMail.php:9
  • Evidencia: config/queue.php:16
  • Evidencia: config/horizon.php:184

Fluxos criticos​

Fluxo 1 - Criacao de agendamento​

  1. Requisicao entra em POST /api/appointments.
  2. API valida campos e resolve employee/client por CPF.
  3. API verifica conflito de horario (exceto tipo group).
  4. Agendamento e persistido e pode disparar e-mail.
  5. Cache de slots do dia e invalidado.
  • Evidencia: routes/api.php:28
  • Evidencia: app/Http/Controllers/AppointmentController.php:133
  • Evidencia: app/Http/Controllers/AppointmentController.php:147
  • Evidencia: app/Http/Controllers/AppointmentController.php:172
  • Evidencia: app/Http/Controllers/AppointmentController.php:210

Fluxo 2 - Cancelamento de agendamento​

  1. Requisicao DELETE /api/appointments/{id}/cpf/{cpf}.
  2. API valida ownership (employee_id do agendamento).
  3. Registro e removido (soft delete) e cache e limpo.
  4. Para tipos > 1, envia notificacao de cancelamento.
  • Evidencia: routes/api.php:29
  • Evidencia: app/Http/Controllers/AppointmentController.php:396
  • Evidencia: app/Http/Controllers/AppointmentController.php:401
  • Evidencia: app/Http/Controllers/AppointmentController.php:403

Fluxo 3 - Consulta de slots disponiveis​

  1. GET /api/appointments/slots/{date}/employee/{employee_cpf}/client/{client}.
  2. Retorna do cache se houver chave getAvailableSlotsByDate.
  3. Caso contrario, calcula slots e grava cache por 600s.
  • Evidencia: routes/api.php:30
  • Evidencia: app/Http/Controllers/AppointmentController.php:581
  • Evidencia: app/Http/Controllers/AppointmentController.php:583
  • Evidencia: app/Http/Controllers/AppointmentController.php:602

Fluxo 4 - Transferencia de agendamentos futuros​

  1. POST /api/appointments/move/from/{from}/to/{to}/class/{class_id}.
  2. Busca agendamentos futuros por colaborador e turma.
  3. Move somente itens sem conflito para colaborador destino.
  • Evidencia: routes/api.php:38
  • Evidencia: app/Http/Controllers/AppointmentController.php:475
  • Evidencia: app/Http/Controllers/AppointmentController.php:490

Fluxo 5 - Exportacao CSV para S3​

  1. GET /api/export-appointments.
  2. Executa query consolidada de appointments + clients + employees + types.
  3. Gera CSV e publica em s3://appointments/last-update.csv.
  • Evidencia: routes/api.php:46
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:20
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:42
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:91

Diagrama​

Pendencias​

  • Relacao services e usada em AppointmentsApiController, mas nao foi encontrada no model Appointment.
    • Evidencia: app/Http/Controllers/Api/V1/Admin/AppointmentsApiController.php:18
    • Evidencia: app/Models/Appointment.php:34
  • Rota updateDate para API v1 nao possui metodo correspondente neste controller.
    • Evidencia: routes/api.php:76
    • Evidencia: app/Http/Controllers/Api/V1/Admin/AppointmentsApiController.php:12