[API] Centralizar upload de imagens no backend com Supabase Storage

[Ronildo22]

Centralizar upload de imagens no backend com Supabase Storage

Contexto

Atualmente o fluxo de upload de imagens ainda não está centralizado no backend. Isso dificulta aplicar validações consistentes, controlar credenciais sensíveis e padronizar o retorno de URLs públicas para consumo pelo frontend.

Ao mover o upload para o backend, a aplicação passa a ter um ponto único de controle para validação de arquivo, integração com armazenamento e regras de segurança.

Objetivo

Centralizar o upload de imagens no backend usando Supabase Storage, com autenticação, validação de tipo e tamanho de arquivo e retorno da URL pública gerada após o upload.

Exemplos de requisição e resposta

Exemplo 1 — Upload de imagem válido

Requisição:

POST /events/image
Authorization: Bearer <token>
Content-Type: multipart/form-data

Campo esperado:

• file — arquivo de imagem

Resposta esperada (201/200): retorna a URL pública do arquivo enviado.

{
  "url": "https://<project>.supabase.co/storage/v1/object/public/imagens/eventos/banner.png"
}

Exemplo 2 — Arquivo com tipo inválido

Requisição: envio autenticado de arquivo que não seja image/*.

Resposta esperada (400): arquivo rejeitado por tipo inválido.

Exemplo 3 — Arquivo acima do limite

Requisição: envio autenticado de arquivo maior que 5MB.

Resposta esperada (400): arquivo rejeitado por exceder o tamanho permitido.

Exemplo 4 — Upload sem token válido

Requisição: envio sem token ou com token inválido.

Resposta esperada (401): acesso negado pelo guard de autenticação.

Comportamento esperado

• O backend deve usar @supabase/supabase-js para integração com o Supabase Storage.
• O client do Supabase deve ser configurado com SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY.
• O endpoint POST /events/image deve aceitar multipart/form-data.
• O endpoint POST /events/image deve estar protegido por autenticação.
• Apenas arquivos do tipo image/* devem ser aceitos.
• O tamanho máximo permitido deve ser 5MB.
• Uploads válidos devem ser enviados ao bucket imagens.
• A resposta deve retornar a URL pública válida do arquivo.
• Arquivos inválidos devem ser rejeitados com erro apropriado.

Tarefas

• Instalar @supabase/supabase-js no backend.
• Configurar client do Supabase com SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY.
• Criar endpoint POST /events/image.
• Configurar recebimento de multipart/form-data.
• Aplicar guard de autenticação no endpoint de upload.
• Validar tipo de arquivo para aceitar apenas image/*.
• Validar tamanho máximo de 5MB.
• Fazer upload do arquivo no bucket imagens.
• Retornar a URL pública do arquivo enviado.
• Documentar o endpoint e o formato de upload no Swagger.
• Adicionar testes cobrindo upload válido e rejeição de arquivos inválidos.

Critérios de aceite

• Upload válido retorna URL pública válida.
• Upload sem token válido retorna 401.
• Arquivos com tipo inválido são rejeitados.
• Arquivos acima de 5MB são rejeitados.
• O endpoint utiliza Supabase Storage no backend.
• A integração usa SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY.
• Existem testes cobrindo os cenários principais.

Dependências

• Bucket imagens criado e acessível no Supabase Storage.
• Variáveis de ambiente SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY configuradas.
• Issue [API] Proteger rotas administrativas com JWT do Supabase #15