req-090: Transição do Gerenciador de Arquivos para Árvore Física no Disco e CRUD Completo de Diretórios no Módulo Admin-Arquivos

Descrição do Problema / Contexto

Esta requisição (BATCH-090) altera a arquitetura de gerenciamento de mídias e arquivos do Quantiflow. Atualmente, o módulo admin-arquivos e os campos de seleção de imagem (Image Picker) dependem de registros na tabela arquivos do banco de dados. Isso gera inconsistências graves quando usuários gerenciam arquivos manualmente no disco (via FTP ou gerenciadores de arquivos externos), pois a tabela do banco e o disco físico saem de sincronia.

Para resolver essa ineficiência, a estrutura será migrada para uma abordagem baseada exclusivamente em árvore física de diretórios no disco, sob a raiz apontada pela constante/variável $_GESTOR['contents-path'].

Detalhamento dos Requisitos

1. Migração do Banco de Dados para o Disco e Gerenciamento de Categorias

• Descontinuação da Tabela arquivos: Novos uploads e listagens não lerão nem gravarão registros de arquivos individuais na tabela arquivos.

• Identificação de Arquivos: O identificador único de cada arquivo para associação de metadados será o seu caminho relativo em relação à raiz de conteúdos $_GESTOR['contents-path'] (ou um hash MD5 desse caminho relativo para facilitar indexação).

• Relações de Categorias: A tabela de relação arquivos_categorias (ou uma nova tabela equivalente) deve usar o caminho relativo (ou o hash do caminho) do arquivo para associá-lo a uma ou mais categorias. A filtragem por categorias na listagem lerá as associações no banco e cruzará com os arquivos físicos presentes na pasta consultada.

2. Listagem de Arquivos e Ações Individuais/Lote

Na página inicial do módulo /admin-arquivos/:

• Navegação Física: Listar dinamicamente as subpastas e arquivos da pasta atual através de varredura física do disco (ex: scandir(), DirectoryIterator). Exibir um breadcrumb interativo com o caminho atual.

• 4 Modos de Visualização: O usuário poderá alternar a listagem entre os seguintes formatos via botões no topo:

  1. Grande com detalhes (Layout de card atual com miniatura grande, nome, data e tipo).

  2. Listagem (Tabela ou linha simples e compacta, exibindo detalhes em colunas).

  3. Ícones pequenos (Visualização em grade compacta).

  4. Ícones médios (Visualização em grade média).

• Ações Individuais: Para cada item da listagem, deve haver ações rápidas:

  • Copiar URL: Copia o link público do arquivo para a área de transferência.

  • Excluir: Exclui o arquivo ou pasta física.

  • Selecionar: Exclusivo para quando o módulo for aberto via iframe (Image Picker), retornando os dados do arquivo ao componente pai.

• Seleção em Lote: Implementar checkboxes para seleção múltipla de arquivos e pastas, permitindo a exclusão em lote de uma só vez.

• Ordenação e Filtros:

  • Ordenação por Nome (asc/desc) e Data de Modificação (asc/desc), lendo os metadados diretamente do sistema de arquivos (filemtime).

  • Filtragem por períodos de data de modificação e por categorias associadas.

3. Upload de Arquivos com Drag & Drop

Na página de adição de arquivos /admin-arquivos/adicionar/:

• Drag and Drop: Permitir arrastar e soltar arquivos na área de upload.

• Tamanho de Pré-visualização: Oferecer um seletor visual com 3 ou 4 tamanhos diferentes para as miniaturas das imagens em processo de upload, permitindo conferir arquivos antes do envio.

• Destino do Upload: Permitir ao usuário navegar pelas pastas físicas ou criar uma pasta destino antes de iniciar o upload, enviando os arquivos para a pasta correta no disco.

4. Miniaturas Dinâmicas via AJAX em Lotes

• Estrutura Física: As miniaturas de imagens de uma pasta X serão gravadas em uma subpasta física X/mini/ com o mesmo nome do arquivo original.

• Processamento sob Demanda (Lazy):

  • Ao carregar a listagem de uma pasta, o backend verifica se há arquivos de imagem que não possuem correspondente na subpasta mini/.

  • Se houver, o backend retorna a lista de arquivos identificando as miniaturas faltantes e o frontend exibe uma barra de status discreta no topo: "Processando miniaturas...".

  • O frontend dispara requisições AJAX assíncronas em lotes para que o backend processe as miniaturas (usando a biblioteca SimpleImage).

  • Conforme as miniaturas são geradas no servidor, o frontend atualiza as imagens na listagem em tempo real. A barra de status some assim que o processamento do lote termina.

5. CRUD Completo de Diretórios (Pastas)

• Gerenciamento de Pastas: Implementar interface e backend para:

  • Criar novas pastas.

  • Renomear pastas existentes.

  • Excluir pastas (bloquear ou pedir confirmação se a pasta contiver arquivos/subpastas, e oferecer opção de exclusão recursiva).

• Limites: O usuário tem liberdade de criar e aninhar pastas sem limite de profundidade sob a raiz $_GESTOR['contents-path'], respeitando apenas a capacidade do disco e as permissões de leitura/escrita do sistema de arquivos.

6. Acessos Externos e Retrocompatibilidade (Image Picker)

• Image Picker (Biblioteca interface.php):

  • O picker aberto via iframe deve retornar o caminho relativo do arquivo no disco em vez do ID numérico.

  • Atualizar as funções de renderização de campos tipo imagepick para suportar tanto o ID numérico legado (consultando a tabela arquivos antiga) quanto o caminho físico direto no banco (usando o arquivo no disco para pegar os metadados de exibição).

Sugestões do Engenheiro Chefe (Alternativas & Segurança)

1. Prevenção de Path Traversal: Todas as rotas do backend que manipulam diretórios e arquivos (CRUD, listagem, upload) devem sanitizar estritamente os parâmetros de entrada para garantir que nenhum caminho consiga acessar diretórios fora da árvore de $_GESTOR['contents-path'] (impedir sequências como ../, ..\\ ou caminhos absolutos arbitrários).

2. Bloqueio de Uploads Perigosos: Implementar validação estrita no backend para proibir o upload de arquivos executáveis (ex: .php, .phtml, .py, .htaccess, etc.) mesmo que o usuário tente burlar a extensão no frontend, a fim de blindar o servidor contra a execução de scripts maliciosos.

3. Paginação de Leitura Física: Para pastas muito grandes, a leitura total de arquivos pode degradar a performance. Recomenda-se implementar paginação de leitura no backend (ex: ler apenas um limite por vez de arquivos correspondente à página atual solicitada pelo AJAX).

4. Cache-bust de Miniaturas: Ao carregar imagens mini, usar o timestamp de modificação da imagem original no URL (mini/imagem.jpg?t=TIMESTAMP) para garantir que o navegador atualize o cache caso a imagem original seja substituída no disco por outra de mesmo nome.

5. Sanitização de Nomes de Arquivos/Pastas: Nomes de pastas e arquivos criados/enviados devem ser higienizados para remover caracteres especiais inadequados a sistemas de arquivos de rede ou diferentes sistemas operacionais (evitar :, *, ?, ", <, >, |).

Plano de Validação e Testes

1. Validação de Sintaxe: Garantir que as alterações em admin-arquivos.php, interface.php e demais controladores não quebrem o PHP.

2. Testes Unitários / Integração:

   • Criar testes unitários para a rotina de sanitização de caminhos (Path Traversal).

   • Criar testes de validação para as miniaturas dinâmicas.

3. Validação Manual:

   • Abrir o módulo /admin-arquivos/ e testar a alternância entre os 4 modos de visualização.

   • Criar, renomear e excluir pastas.

   • Enviar imagens via drag and drop e conferir se as miniaturas são geradas dinamicamente com os status corretos na tela.

   • Testar a inserção de imagens em um módulo que utilize o Image Picker e validar a persistência retrocompatível.