Site - Biblioteca de Mídia

O que é

A Biblioteca de Mídia é o repositório único de imagens da agência dentro do Viagilize. Tudo que é carregado pelo upload manual, pelas galerias de excursão, pelo blog, pelos hero slides e por outros pontos do admin é registrado aqui, com pasta, tags, dimensões, tamanho em disco e o histórico de onde a imagem está sendo usada.

O usuário costuma chegar nesta página em dois momentos: para subir um lote de fotos novas (ex.: imagens de uma excursão, banners promocionais) ou para limpar a biblioteca quando o armazenamento do plano se aproxima do limite. O cabeçalho mostra os três indicadores que orientam essa decisão: total de Imagens, total de Pastas e o uso de armazenamento em relação ao limite do plano (com barra que vira amarela aos 80% e vermelha aos 100%).

Como usar

1. Vá em Vitrine > Biblioteca de Mídia no sidebar (URL /admin/media).
2. Para subir imagens, clique em Upload (botão azul no canto superior esquerdo da toolbar) e selecione um ou mais arquivos no seletor do navegador. Formatos aceitos: jpg, jpeg, png, gif, webp, svg, bmp, avif, com no máximo 25 MB por arquivo (a imagem é otimizada automaticamente após o upload).
3. Para cada imagem selecionada, o modal de recorte abre em sequência (recorte livre, sem proporção fixa). Use os controles para ajustar o enquadramento e confirme - para pular o recorte de uma imagem, cancele o modal e o arquivo original será enviado sem alteração.
4. Quando o recorte de todas as imagens da fila terminar, o modal Upload em progresso mostra a barra individual de cada arquivo. Ao final, a página recarrega sozinha.
5. Para abrir uma imagem, dê duplo clique no card (modo grade) ou clique no ícone de olho na última coluna (modo lista). O modal Detalhes da Imagem permite editar Título, Texto alternativo (SEO) e Descrição, além de oferecer os botões Abrir (URL em nova aba) e Copiar URL.
6. Para selecionar várias imagens, clique uma vez no card (ou marque o checkbox no canto superior esquerdo). A barra de ações em massa aparece logo abaixo do botão Upload com o contador "X selecionado(s)" e os botões Editar (só com 1 selecionada) e Excluir.

Filtrar e buscar

• Buscar imagens... (caixa com ícone de lupa, lado direito da toolbar): pesquisa por nome do arquivo, título, alt ou descrição. O formulário envia via GET - basta apertar Enter.
• Pastas (sidebar esquerda): clica em Todas as imagens para limpar o filtro ou em uma pasta da árvore para listar apenas o que está dentro dela. O botão Expandir/Recolher no cabeçalho da árvore abre todas as subpastas de uma vez.
• Tags (sidebar esquerda, abaixo das pastas): clique em uma tag colorida para filtrar a listagem pelas imagens que receberam aquela marcação.
• Ordenação (select à direita da busca): Mais recentes (padrão), Nome ou Tamanho.
• Visualização: dois botões com ícones de grade ou linhas, na ponta direita da toolbar. O modo lista também mostra dimensões em pixels e data de upload.

Mover imagens em massa

A ação de mover existe na API (bulk-move) e é usada por integrações: selecione imagens, envie o array de IDs e o folder_id de destino (ou null para a raiz). A reorganização também acontece automaticamente quando se exclui uma pasta com conteúdo (ver Casos especiais).

Ver onde a imagem está sendo usada

Antes de excluir, o sistema consulta a origem de cada imagem selecionada. A confirmação Excluir imagens lista, em um bloco âmbar, as entidades vinculadas (ex.: "Foto da galeria: Excursão Caldas Novas", "Imagem do blog", "Imagem da empresa"). O texto avisa que os vínculos também serão removidos ao confirmar.

A rota interna GET /admin/media/{medium}/usages devolve, em JSON, todos os pontos de uso de uma única mídia (campo, modelo dono, tipo de referência e URL de edição quando disponível) - útil para integrações e diagnóstico.

Casos especiais

Pastas criadas automaticamente

As pastas não são criadas manualmente pela interface: o Viagilize gera a estrutura conforme o contexto do upload (ex.: excursoes/{id}, blog, paginas, empresa, veiculos, guias). Algumas pastas internas são ocultas da listagem (excludedFolders no model MediaFolder) para não poluir a visualização do usuário final. As contagens de imagens e armazenamento exibidas nos cards do topo já desconsideram essas pastas ocultas.

Excluir pasta com conteúdo

Quando uma pasta com mídias é removida via API (DELETE /admin/media-folders/{mediaFolder}), o controlador move tudo para a pasta indicada em move_media_to (ou para a raiz, se vier vazio) - inclusive o conteúdo das subpastas, de forma recursiva. Nenhum arquivo físico é apagado nesse caso.

Imagem em uso bloqueia exclusão

Excluir uma imagem isoladamente (DELETE /admin/media/{medium}) é bloqueado quando o sistema de tracking identifica vínculos: a resposta vem com mensagem "Esta mídia está em uso e não pode ser removida" e o contador de usos. Já a exclusão em massa não é bloqueada por padrão - os vínculos são listados na confirmação e removidos junto. Para forçar exclusão individual mesmo em uso, integrações podem enviar force=true no bulk-destroy.

Substituição preserva o vínculo com a galeria de excursões

Ao trocar o arquivo de uma mídia (POST /admin/media/{medium}/replace, usado pelo editor de imagem embutido), o registro ExcursaoFoto vinculado pelo mesmo path é atualizado para o novo caminho, e o thumbnail antigo da galeria é removido. Isso evita que a galeria pública da excursão fique apontando para o arquivo antigo.

Imagens órfãs (arquivo sumiu do disco)

Quando o registro existe no banco mas o arquivo físico não está no disco, o card aparece listrado em vermelho com o aviso "Arquivo não encontrado". A listagem filtra esses registros automaticamente em tempo real (campo file_exists). Para diagnosticar e limpar, há duas rotas dedicadas:

• GET /admin/media/orphans - devolve o JSON com a contagem e a lista de órfãos (id, nome do arquivo, caminho, data).
• POST /admin/media/orphans/cleanup - apaga os registros (com opção de force=true para forceDelete) e desfaz tags e vínculos antes de remover.

Ambas exigem a permissão de excluir a biblioteca de mídia. Use quando o painel mostrar muitas miniaturas quebradas.

Editor de imagem (Editar com 1 selecionada)

O botão Editar abre um modal de edição em canvas com três abas: Ajustes (brilho, contraste, saturação, exposição, temperatura), Transformar (girar -90°/+90°/180°, espelhar horizontal/vertical, abrir recorte) e Filtros (presets P&B, Sépia, Quente, Frio, Vintage, Vívido, Desbotado, Dramático). Salvar Alterações envia o resultado para a rota replace e substitui o arquivo original - não é uma nova mídia, é a mesma com o conteúdo atualizado.

Erros comuns e como resolver

• "Selecione apenas arquivos de imagem" - Causa: foi escolhido algum arquivo que não é imagem (PDF, vídeo, etc.). Solução: o upload aceita só jpg, jpeg, png, gif, webp, svg, bmp, avif. Refaça a seleção apenas com imagens.
• "Esta mídia está em uso e não pode ser removida" - Causa: tentativa de excluir um único item que está vinculado a alguma entidade (excursão, página, blog, etc.). Solução: exclua pela barra de ações em massa (que mostra os vínculos e os remove junto) ou primeiro tire a imagem da entidade que a referência.
• "Não é possível mover uma pasta para dentro de si mesma ou de suas subpastas" - Causa: ao reorganizar pastas via API, o parent_id informado é a própria pasta ou um descendente. Solução: escolha outra pasta destino.
• Card aparece riscado em vermelho com "Arquivo não encontrado" - Causa: o registro no banco aponta para um arquivo que não existe mais no disco (migração de bucket, exclusão manual via S3, etc.). Solução: rode POST /admin/media/orphans/cleanup para limpar esses registros.
• Barra de armazenamento vermelha (100% ou mais) - Causa: uso ultrapassou o limite do plano (storage_mb em config/planos.limits). Solução: apague imagens não usadas, limpe órfãos ou faça upgrade do plano. Novos uploads continuam funcionando, mas o aviso visual no topo permanece.
• A imagem subiu mas não aparece na galeria pública da excursão - Causa: o upload pela Biblioteca de Mídia não cria automaticamente o registro ExcursaoFoto da galeria pública daquela excursão. Solução: vincule a imagem pela tela da própria excursão (aba Galeria); a Biblioteca de Mídia espelha o vínculo depois.

Onde encontrar

• URL: /admin/media
• Caminho no menu: Vitrine > Biblioteca de Mídia
• Permissão necessária: ver a biblioteca de mídia para abrir a página; media.upload para subir; editar a biblioteca de mídia para editar metadados, substituir e mover; excluir a biblioteca de mídia para excluir, excluir em massa e limpar órfãos
• Módulo necessário: nenhum

Veja também

• Hero Slides (Carrossel) - consome imagens da biblioteca para o topo do site
• Galeria de Vídeos - equivalente da biblioteca para vídeos do YouTube e Instagram
• Seções da Home - várias seções configuráveis usam imagens cadastradas aqui