Introdução

Carregue e gerencie arquivos no armazenamento em nuvem com otimização automática.

🎯 O que este módulo faz?

O módulo FileUploading permite que você carregue, recupere e exclua arquivos no armazenamento em nuvem OneEntry - imagens, PDFs, vídeos, documentos e qualquer tipo de arquivo com otimização automática e entrega via CDN.

Pense nisso como seu gerenciador de armazenamento em nuvem - você carrega arquivos uma vez, e o OneEntry os armazena, otimiza as imagens automaticamente e as entrega rapidamente via CDN.

📖 Explicação Simples

Imagine que você está construindo um aplicativo onde os usuários podem:

• 📸 Carregar fotos de perfil - redimensionamento e otimização automáticos
• 📄 Carregar documentos - armazenar PDFs, DOCs com segurança
• 🖼️ Carregar imagens de produtos - várias imagens por produto
• 🎥 Carregar vídeos - armazenar e transmitir conteúdo de vídeo
• 📎 Carregar anexos - qualquer tipo de arquivo

Em vez de gerenciar seu próprio armazenamento:

• ✅ Carregue arquivos na nuvem OneEntry
• ✅ Otimização automática de imagens (redimensionar, comprimir)
• ✅ Entrega rápida via CDN em todo o mundo
• ✅ Organize por tipo de entidade (produto, usuário, página)
• ✅ Obtenha URLs de download instantaneamente
• ✅ Exclua arquivos quando não forem mais necessários

Exemplo do mundo real:

Without FileUploading (manual):
- Set up AWS S3 bucket ❌
- Configure CDN ❌
- Write image optimization code ❌
- Manage file permissions ❌
- Generate signed URLs ❌

With FileUploading (automatic):
- Upload file → Get download URL ✅
- Images auto-optimized ✅
- CDN delivery built-in ✅
- Easy file management ✅

✨ Conceitos Chave

O que é Carregamento de Arquivos?

Carregamento de arquivos é armazenar arquivos no armazenamento em nuvem:

• Carregar - Enviar arquivo para a nuvem OneEntry
• Armazenamento - Arquivos armazenados com segurança na nuvem
• CDN - Entrega rápida a partir de servidores próximos aos usuários
• Otimização - Imagens auto-comprimidas e redimensionadas
• URL - Obtenha um link de download permanente

Tipos de Arquivos Suportados

Carregue qualquer tipo de arquivo:

Categoria	Tipos de Arquivos	Auto-Otimização
Imagens	JPG, PNG, GIF, WebP, SVG	Sim (redimensionar, comprimir)
Documentos	PDF, DOC, DOCX, XLS, XLSX	Não (armazenados como estão)
Vídeos	MP4, MOV, AVI, WebM	Não (armazenados como estão)
Arquivos	ZIP, RAR, TAR, GZ	Não (armazenados como estão)
Outros	Qualquer tipo de arquivo	Não (armazenados como estão)

Otimização de Imagens

Ao carregar imagens, o OneEntry pode:

• 📐 Redimensionar - Reduzir dimensões (por exemplo, largura máxima de 1920px)
• 🗜️ Comprimir - Reduzir o tamanho do arquivo (menor, mais rápido)
• 🖼️ Formato - Converter para o formato ideal (WebP)
• 📱 Responsivo - Criar múltiplos tamanhos

Exemplo:

Original: 5MB, 4000x3000px
↓ (auto-optimize)
Optimized: 200KB, 1920x1440px

📋 O que Você Precisa Saber

Parâmetros de Carregamento

Ao carregar arquivos, você pode especificar:

await FileUploading.upload(file, {
  entity: 'product',     // Entity type (required)
  id: 123,               // Entity ID (optional)
  type: 'image',         // File type hint (optional)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true         // Compress images (optional)
});

Parâmetros explicados:

• file - O objeto do arquivo (do input ou arrastar-soltar)
• entity - Categoria: product, page, block, user, form, general
• id - ID da entidade para associar o arquivo (por exemplo, ID do produto)
• type - Dica do tipo de arquivo (geralmente detectado automaticamente)
• width - Largura máxima em pixels (apenas imagens)
• height - Altura máxima em pixels (apenas imagens)
• compress - Habilitar compressão (apenas imagens)

Resposta de Carregamento

Após o carregamento, você recebe:

{
  filename: "abc123-photo.jpg",              // Unique filename
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size (bytes)
}

Campos importantes:

• downloadLink - Use esta URL em <img>, <a>, <video> tags
• filename - Salve isso para excluir o arquivo depois
• size - Tamanho do arquivo em bytes (204800 bytes = 200KB)

Melhores Práticas de Organização de Arquivos

Organize arquivos por tipo de entidade

Opções de Otimização de Imagens

Controle como as imagens são otimizadas:

Opção	O que Faz	Exemplo
width	Largura máxima (mantém a proporção)	width: 1920
height	Altura máxima (mantém a proporção)	height: 1080
compress	Reduzir o tamanho do arquivo	compress: true

A proporção é preservada:

Original: 4000x3000 (4:3 ratio)
With width: 800
Result: 800x600 (still 4:3 ratio)

Excluindo Arquivos

Sempre forneça entidade, id e filename para excluir:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

Por que todos os três? Os arquivos são organizados por entidade → id → filename.

---

📊 Tabela de Referência Rápida - Métodos

Método	O que Faz	Quando Usar
upload()	Carregar arquivo para armazenamento em nuvem	O usuário carrega imagem, documento
getFile()	Obter informações do arquivo (tamanho, tipo, URL)	Verificar se o arquivo existe
delete()	Excluir arquivo do armazenamento	Remover arquivos antigos

---

❓ Perguntas Comuns (FAQ)

Quais tipos de arquivos posso carregar?

Qualquer tipo de arquivo é suportado:

• Imagens: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
• Documentos: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
• Vídeos: MP4, MOV, AVI, WebM, MKV
• Arquivos: ZIP, RAR, TAR, GZ
• Outros: Qualquer tipo de arquivo

Apenas imagens são auto-otimizadas. Outros arquivos são armazenados como estão.

---

Qual é o tamanho máximo do arquivo?

Verifique os limites do seu plano OneEntry. Normalmente:

• Plano gratuito: 5MB por arquivo
• Planos pagos: 50MB - 100MB por arquivo

Melhor prática: Otimize as imagens antes de carregar para reduzir o tamanho.

---

Os arquivos são armazenados permanentemente?

Sim, os arquivos são armazenados até que você os exclua manualmente usando FileUploading.delete().

Importante: Limpe arquivos não utilizados para economizar espaço de armazenamento.

---

Posso carregar arquivos do frontend (navegador)?

Sim! Use input de arquivo ou arraste e solte.

---

Como faço para validar arquivos antes do carregamento?

Verifique o tipo e o tamanho do arquivo.

---

Posso obter uma lista de todos os arquivos carregados para uma entidade?

Não diretamente com este SDK. Você precisa:

1. Rastrear os nomes dos arquivos ao carregar (salvar no banco de dados)
2. Usar a API Admin do OneEntry para listar arquivos

Melhor prática: Salve os nomes dos arquivos carregados no seu banco de dados.

---

Como lido com erros de carregamento?

Sempre use try/catch.

---

Posso carregar arquivos diretamente para a CDN?

Não, os uploads passam pela API do OneEntry, que:

1. Valida o arquivo
2. Otimiza as imagens (se habilitado)
3. Armazena na nuvem
4. Retorna a URL da CDN

Isso garante segurança e otimização.

---

O que acontece com os arquivos se eu excluir uma entidade (produto, usuário)?

Os arquivos permanecem no armazenamento mesmo se a entidade for excluída.

Melhor prática: Exclua os arquivos antes de excluir a entidade.

---

Posso redimensionar imagens para dimensões exatas?

Não, a proporção é sempre preservada para evitar distorções.

Como funciona:

• Você define width: 800, height: 600
• A imagem é redimensionada para caber dentro de 800x600
• A proporção é preservada

Exemplo:

Original: 1000x500 (2:1 ratio)
With width: 800, height: 600
Result: 800x400 (still 2:1 ratio, fits within 800x600)

---

💡 Notas Importantes

Segurança de Arquivos

Os arquivos carregados são acessíveis publicamente via CDN:

• ✅ Ótimo para imagens, documentos públicos
• ⚠️ Não carregue arquivos sensíveis (senhas, dados privados)

Para arquivos privados:

• Use a API Admin do OneEntry com autenticação
• Ou implemente seu próprio controle de acesso

---

Limites de Armazenamento

Monitore seu uso de armazenamento:

• Cada plano tem limites de armazenamento
• Limpe arquivos não utilizados regularmente
• Comprimir imagens antes do carregamento

---

Dicas de Otimização de Imagens

Para melhores resultados:

• ✅ Carregue originais de alta qualidade (deixe o OneEntry otimizar)
• ✅ Use compress: true para imagens da web
• ✅ Defina dimensões apropriadas (por exemplo, 1920px para imagens principais, 500px para miniaturas)
• ❌ Não carregue imagens já comprimidas (perda de qualidade)

Tamanhos recomendados:

• Fotos de perfil: 500x500
• Imagens de produtos: 1920x1920
• Banners principais: 1920x1080
• Miniaturas: 300x300

---

🎓 Melhores Práticas

• Valide o tipo e o tamanho do arquivo antes do carregamento
• Associe arquivos com IDs de entidades para organização
• Habilite a compressão para imagens da web
• Lide com erros de carregamento de forma elegante
• Salve os nomes dos arquivos para excluir arquivos depois
• Limpe arquivos não utilizados regularmente
• Mostre o progresso do carregamento para os usuários

---

Definição do módulo FileUploading

---

const { FileUploading } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

---

🔗 Documentação Relacionada

• Módulo de Produtos - Carregar imagens de produtos
• Módulo de Usuários - Carregar fotos de perfil de usuários
• Módulo de Páginas - Carregar arquivos de conteúdo de páginas
• Módulo de Blocos - Carregar arquivos de conteúdo de blocos

---