Armazenamento de arquivos e gerenciamento de conteúdo

Seu aplicativo possui um sistema de arquivos de conteúdo dedicado para armazenar arquivos enviados pelo usuário, como imagens, documentos, PDFs e vídeos. Isso é separado do código do seu aplicativo e foi projetado para conteúdo dinâmico que os usuários criam ou carregam enquanto usam seu aplicativo.

Limites e notas importantes

  • Arquivos individuais podem ter até 500 MB de tamanho
  • A exclusão de arquivos é permanente — não há lixo ou lixeira
  • O uso do armazenamento é contabilizado na cota da sua conta

O que o sistema de arquivos de conteúdo permite

O sistema de arquivos de conteúdo fornece recursos poderosos de gerenciamento de arquivos para seu aplicativo:

  • Armazene avatares de usuários, fotos de perfil e galerias de imagens
  • Aceite uploads de documentos como currículos, contratos ou PDFs
  • Crie recursos de compartilhamento de arquivos entre usuários no seu aplicativo
  • Crie aplicativos com muitas imagens com otimização automática
  • Permita que os usuários baixem arquivos que eles enviaram ou que lhes pertencem
  • Crie ferramentas administrativas para gerenciar arquivos em nome dos usuários

Como funciona

Quando você descreve um recurso que precisa de armazenamento de arquivos para a IA, ela trata automaticamente de toda a implementação:

Configura a interface de upload — Cria formulários ou zonas de arrastar e soltar onde os usuários podem selecionar arquivos de seus dispositivos

Configura o controle de acesso — Determina quem pode visualizar, fazer upload ou excluir arquivos com base no que você está criando

Implementa a otimização de imagens — Redimensiona e exibe imagens automaticamente com eficiência para que seu aplicativo carregue rapidamente

Cria a estrutura de armazenamento — Organiza arquivos em pastas lógicas como /content/uploads/ ou /content/avatars/

Cuida do back-end — Gerencia o armazenamento, a recuperação e a entrega de arquivos sem que você precise se preocupar com isso

Os arquivos são armazenados em caminhos como /content/uploads/photo.jpg e podem ser referenciados diretamente no seu aplicativo. O sistema rastreia quem carregou cada arquivo, quando ele foi criado e aplica suas regras de acesso.

Controle de acesso para arquivos

Assim como as tabelas de banco de dados e as Edge Functions, os arquivos possuem políticas de segurança que controlam quem pode acessá-los. Os arquivos são privados por padrão — ninguém pode acessá-los até que você configure as permissões. A IA configura isso com base no que você está construindo:

Arquivos Públicos

Qualquer pessoa pode visualizá-los, mesmo sem fazer login. Usuários logados podem fazer upload, e somente a pessoa que fez upload de um arquivo pode excluí-lo. Perfeito para galerias de fotos, compartilhamento público de imagens ou sites de conteúdo gerado por usuários.

Arquivos privados

Somente o usuário que carregou um arquivo pode visualizá-lo ou excluí-lo. Usado para documentos confidenciais, fotos privadas, registros médicos ou qualquer coisa que os usuários não gostariam que outras pessoas vissem.

Arquivos compartilhados pela organização

Os usuários da mesma organização podem visualizar arquivos enviados por qualquer pessoa na organização. Os indivíduos só podem excluir os arquivos que enviaram. Ótimo para compartilhamento de documentos em equipe, recursos da empresa ou espaços de trabalho colaborativos.

Acesso somente para proprietário

Somente você (o criador do aplicativo) pode acessar esses arquivos, e não seus usuários finais. Útil para armazenar arquivos de sistema, modelos ou recursos administrativos que alimentam seu aplicativo, mas não devem ser voltados para o usuário.

Controle de acesso avançado

A IA pode criar regras de acesso sofisticadas baseadas em metadados de arquivos. Por exemplo:

  • Os artigos publicados são públicos, mas os rascunhos são visíveis apenas para o autor
  • Os arquivos marcados com um departamento só ficam visíveis para os usuários desse departamento
  • O conteúdo premium requer um sinalizador de assinatura na conta do usuário
  • Os arquivos compartilhados ficam visíveis para os colaboradores listados nos metadados do arquivo

Otimização de imagem

As imagens carregadas no sistema de arquivos de conteúdo são otimizadas automaticamente para carregamento rápido. Ao exibir uma imagem, você pode solicitar uma largura específica e o sistema cuida do resto:

<!-- Thumbnail (200px wide) -->
<img src="/content/gallery/photo.jpg?w=200" />

<!-- Standard display (800px wide) -->
<img src="/content/gallery/photo.jpg?w=800" />

<!-- Hero image (1920px wide) -->
<img src="/content/gallery/photo.jpg?w=1920" />

<!-- Original, full-size image -->
<img src="/content/gallery/photo.jpg" />

Como funciona a otimização

Carregamento progressivo — Na primeira vez que alguém solicita um tamanho otimizado, o sistema exibe a versão disponível mais próxima e gera o tamanho exato em segundo plano. Cada solicitação posterior obtém a imagem otimizada e de tamanho perfeito. O arquivo original é sempre preservado.

Fornecimento de formato moderno — O sistema fornece automaticamente formatos de imagem modernos (AVIF ou WebP) para navegadores que os suportam, com fallback automático para JPEG ou PNG para navegadores mais antigos. Isso acontece de forma transparente — basta especificar a largura e os usuários obtêm a versão de carregamento mais rápido que seu navegador pode suportar.

Otimização de desempenho — Use larguras menores para melhorar o desempenho. Uma miniatura de 200px carrega muito mais rápido que a imagem original de 4000px e usa menos largura de banda. Escolha a largura que corresponde à forma como você está exibindo a imagem.

Usando arquivos em seu aplicativo

A IA integra automaticamente o sistema de arquivos de conteúdo em seu aplicativo React. Quando você solicita recursos que envolvem arquivos, ele cria os componentes da UI, conecta a lógica de upload/download e trata de erros.

Padrões comuns que a IA implementa

Upload de avatar — Uma interface de upload de fotos de perfil que valida os tipos de imagem, mostra o progresso do upload, visualiza a imagem e salva o caminho para o perfil do usuário.

Galeria de Documentos — Um navegador de arquivos que lista documentos carregados, mostra miniaturas de imagens, fornece links para download e permite filtragem ou pesquisa.

Upload com recurso de arrastar e soltar — Uma zona de upload intuitiva onde os usuários podem arrastar arquivos de sua área de trabalho, ver o progresso do upload, cancelar uploads em andamento e receber mensagens de erro de arquivos inválidos.

Seletor de arquivos — Um modal ou barra lateral que mostra os arquivos que o usuário carregou anteriormente, permite selecionar um para reutilização e exibe miniaturas e nomes de arquivos.

Integração de Edge Functions

Edge Functions (seu código do lado do servidor) podem acessar o sistema de arquivos de conteúdo para processar arquivos, gerar arquivos programaticamente ou implementar uma lógica personalizada de manipulação de arquivos.

O que as edge functions podem fazer com arquivos

  • Gere relatórios em PDF e salve-os para download pelos usuários
  • Processar imagens enviadas (aplicar marcas d’água, criar miniaturas, extrair metadados)
  • Digitalize documentos carregados em busca de dados confidenciais antes de aceitá-los
  • Implementar backup personalizado ou lógica de arquivamento
  • Analise o conteúdo do arquivo e extraia dados estruturados
  • Acione workflows quando arquivos específicos são carregados

Aviso: Observação importante sobre segurança

As edge functions ignoram o controle de acesso normal. Quando sua função acessa arquivos, ela não é limitada pelas regras “públicas” ou “proprietárias” que se aplicam aos usuários. Isso significa que você deve implementar suas próprias verificações de autorização no código de função para garantir que os usuários possam acessar apenas os arquivos que deveriam ver.

Por exemplo, se um usuário chamar sua função solicitando um arquivo, você precisará verificar se ele é o proprietário desse arquivo ou se tem permissão para acessá-lo antes de retornar o conteúdo. A IA cuida disso ao criar suas funções, mas é importante entender que o código da função é executado com privilégios elevados.

Organização de armazenamento

A IA organiza os arquivos em pastas lógicas com base no que você está construindo. Você não precisa criar estruturas de pastas manualmente — apenas descreva o que você precisa e a IA configurará os caminhos apropriados.

Padrões Comuns de Organização

  • /content/uploads/ — Uploads gerais de usuários
  • /content/avatars/ — Fotos de perfil do usuário
  • /content/documents/ — PDFs e documentos
  • /content/gallery/ — Imagens da galeria de fotos
  • /content/private/ — Arquivos de usuário privados
  • /content/public/ — Arquivos acessíveis publicamente
  • /content/temp/ — Arquivos temporários que podem ser excluídos

A IA pode criar pastas aninhadas como /content/uploads/2024/ ou /content/users/[username]/ quando apropriado para o seu caso de uso. Os arquivos são rastreados pelo caminho completo, portanto, mover ou renomear arquivos atualiza todas as referências automaticamente.

Monitoramento e depuração

Todas as operações de arquivo são registradas — uploads, downloads, negações de acesso e erros. Você pode visualizar esses logs na interface administrativa para entender como o armazenamento de arquivos está sendo usado:

  • Veja quais arquivos são carregados com mais frequência
  • Identifique uploads com falha e o que deu errado
  • Rastreie padrões de download e arquivos populares
  • Monitore o uso e o crescimento do armazenamento ao longo do tempo
  • Depurar problemas de controle de acesso quando os usuários não conseguem acessar os arquivos que esperam ver

O sistema também rastreia métricas de armazenamento — total de arquivos armazenados, tamanho total, taxa de crescimento e arquivos maiores. Isso ajuda você a entender o espaço de armazenamento do seu aplicativo e planejar o escalonamento.

Limites e restrições

Por padrão, os arquivos individuais podem ter até 500 MB. Isso é configurável — a IA pode ajustar o limite com base no que você está construindo. Para a maioria dos aplicativos (uploads de imagens, compartilhamento de documentos, PDFs), o limite padrão é mais que suficiente.

Os arquivos são armazenados de forma redundante para maior confiabilidade. Se você excluir um arquivo, ele será removido permanentemente do sistema — não há lixo ou lixeira, portanto a exclusão é imediata e definitiva.

Trabalhando com a IA

Ao descrever recursos que precisam de armazenamento de arquivos, seja específico sobre:

  • Quem pode acessar os arquivos — Regras públicas, privadas, compartilhadas pela organização ou personalizadas
  • Quais tipos de arquivos — Somente imagens, PDFs, qualquer tipo de arquivo, limites de tamanho
  • Como os arquivos são organizados — Pastas, convenções de nomenclatura, se os usuários podem criar subpastas
  • O que acontece após o upload — Exiba em uma galeria, anexe a um registro, processe com uma função

A IA usa essas informações para configurar o armazenamento corretamente, definir políticas de acesso e criar uma interface que atenda às suas necessidades.


Documentação relacionada: