Pular para o conteúdo principal

Feature - Exportacao de Agendamentos para CSV no S3

Introducao ao documento​

Documenta a feature de exportacao consolidada de agendamentos para arquivo CSV com publicacao em bucket S3.

Versionamento​

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

Referencial teorico​

  • Data export pattern
  • Object storage integration

Visao geral​

A feature gera um snapshot de appointments com joins de clients/employees/types e publica em appointments/last-update.csv.

Atores​

  • Sistema consumidor da API.
  • Infra AWS S3.
  • Evidencia: routes/api.php:46
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:91

Pre-condicoes​

  • Conectividade com banco e permissao de leitura das tabelas.
  • Credenciais AWS validas para disco s3.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:20
  • Evidencia: config/filesystems.php:47
  • Evidencia: .env.example:39

Fluxo principal​

  1. GET /api/export-appointments.
  2. Executa SQL com left joins.
  3. Cria CSV local com cabecalho e linhas.
  4. Envia arquivo para S3 e retorna URL.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:20
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:42
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:79
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:92
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:96

Fluxos alternativos​

  • 500 em falha de upload para S3.
  • 500 em exception no processo de exportacao.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:103
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:106

Regras de negocio​

  • additional_fields e saneado para evitar quebra por virgulas (substitui por /).
  • Path de destino e fixo appointments/last-update.csv.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:83
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:91

Estados possiveis​

  • Exportado com sucesso (200)
  • Erro de exportacao (500)

Endpoints envolvidos​

  • GET /api/export-appointments

Dados impactados​

  • appointments, clients, employees, types (leitura)
  • bucket s3 (escrita)
  • Referencia: ../data/model.md

Pendencias​

  • Query inclui coluna appointments_additional_fields no header, mas o SELECT nao projeta explicitamente este alias.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:61
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:22