Instruções: Gerenciamento de Arquivos

Este documento detalha a implementação e a arquitetura da funcionalidade de Gerenciamento de Arquivos, um explorador de arquivos integrado para navegar no acervo do Google Drive. Utilize as informações de arquitetura e convenções do arquivo Visão Geral de Engenharia de Rede como base para o desenvolvimento.

📋 Visão Geral da Funcionalidade

O Gerenciamento de Arquivos é uma interface de explorador de arquivos (semelhante ao Windows Explorer ou Finder) que permite aos usuários navegar pela estrutura de pastas e arquivos do projeto armazenados no Google Drive.

A funcionalidade é encapsulada na view Armazenamento.vue e seu componente principal é gerenciadordearquivos.vue.

Responsabilidades Principais:

1. Navegação Hierárquica: Permitir a navegação entre pastas, com histórico (voltar/avançar) e breadcrumbs.
2. Visualização de Conteúdo: Exibir arquivos e pastas em diferentes modos (grade, lista, detalhes).
3. Operações de Arquivo: Suportar upload de novos arquivos, criação de pastas e download.
4. Busca: Filtrar o conteúdo da pasta atual ou realizar uma busca global.
5. Integração: Conectar-se ao "Gerenciador de Dados" para verificar o status de um arquivo no fluxo de trabalho de catalogação.

---

🔧 Arquitetura e Arquivos Chave

Camada	Tecnologia	Arquivos Principais	Propósito
Frontend	Vue.js 3	iface-frontend-vuejs/src/views/Armazenamento/Armazenamento.vue	View principal que hospeda o explorador de arquivos.
Frontend	Vue.js 3	iface-frontend-vuejs/src/components/gerenciadordearquivos/gerenciadordearquivos.vue	Componente central que implementa toda a lógica e UI do explorador de arquivos.
Backend	Node.js, Express	node/backend/routes/gerenciadorDriveGoogle.js	Fornece endpoints para listar pastas/arquivos, fazer upload e sincronizar com o Google Drive.
Backend	Python	estudos/1_funcionais/fregeRAG_v1/gerenciador_drive/GerenciadorDriveGoogle.py	Script CLI para mapeamento e operações no Google Drive (autenticação, sync, upload).
Backend	Node.js, Express	node/backend/routes/fileBrowserRoute.js	Ferramenta auxiliar. Inicia uma instância separada do filebrowser para acesso direto ao servidor.

Nota Importante sobre o Backend: O componente Vue (gerenciadordearquivos.vue) interage com a API em /api/google-drive/.... O backend Node.js orquestra chamadas ao script Python GerenciadorDriveGoogle.py para operações que requerem autenticação OAuth com o Google Drive.

Configuração do Script Python (Backend)

O arquivo gerenciadorDriveGoogle.js define as seguintes constantes para executar o script Python:

const PYTHON_SCRIPT_DIR = '/home/arboreolab/estudos/1_funcionais/fregeRAG_v1/gerenciador_drive';
const PYTHON_SCRIPT_FILE = 'GerenciadorDriveGoogle.py';
const PYTHON_EXECUTABLE = '/home/arboreolab/estudos/.venv/bin/python';

Comandos suportados pelo script Python:

Comando	Descrição
check_auth <email>	Verifica se o usuário está autenticado
get_auth_url <email>	Obtém URL para autenticação OAuth
submit_code <email> <code>	Submete código de autorização OAuth
map <email>	Mapeia toda a estrutura do Google Drive
map_folder <email> --folder-id <id>	Mapeia apenas uma pasta específica
upload_file <email> --folder-id <id> --file-path <path>	Faz upload de arquivo
create_folder <email> --folder-id <parent> --folder-name <name>	Cria pasta
delete_item <email> --file-id <id>	Remove arquivo/pasta

Arquivos gerados pelo mapeamento:

• GoogleDrive/<email>/drive_structure.json - Estrutura completa de pastas/arquivos
• GoogleDrive/<email>/drive_stats.json - Estatísticas do mapeamento
• GoogleDrive/<email>/token.json - Token OAuth do usuário

---

⚙️ Fluxo de Funcionamento (Frontend)

O componente gerenciadordearquivos.vue opera em três fases distintas:

1. Fase 1: Identificação (currentPhase === 'email')

   • O usuário informa seu e-mail.
   • O frontend valida o usuário e obtém a estrutura inicial.

2. Fase 2: Seleção da Raiz (currentPhase === 'selectRoot')

   • O usuário escolhe entre ver toda a estrutura de pastas ou iniciar a partir de uma pasta específica.
   • Se "Escolher Pasta" for selecionado, uma árvore de pastas é exibida para seleção.

3. Fase 3: Explorador (currentPhase === 'explorer')

   • A interface principal do explorador de arquivos é exibida.
   • O conteúdo é carregado e gerenciado via API.
   • Toda a interatividade (navegação, busca, upload, etc.) ocorre nesta fase.

---

🔌 Endpoints da API (Servidos pelo Backend Node.js)

O frontend gerenciadordearquivos.vue depende dos seguintes endpoints (prefixo /api/google-drive):

Método	Rota	Corpo/Parâmetros da Requisição	Resposta Esperada
GET	/structure/:email	-	Estrutura completa de pastas (árvore) para navegação.
GET	/status/:email	-	Status da conexão e sincronização.
POST	/sync	{ email: string }	Inicia uma sincronização com o Google Drive e retorna o status.
POST	/upload	FormData com os arquivos e o folderId.	Resultados do upload para cada arquivo.
POST	/create-folder	{ parentId: string, folderName: string, email: string }	Confirmação da criação da nova pasta.
GET	/collections	?email=string	Lista coleções disponíveis (pastas raiz).
POST	/prepare-user-upload	{ email, collectionId, userEmail, targetSubfolder }	Prepara estrutura de pastas para upload de usuário (role=usuario).
GET	/api/gerenciador-dados/documento/by-drive-id/:id	-	Dados do documento da tabela gerenciador_dados para o modal de workflow.

---

✨ Funcionalidades Detalhadas

Navegação

• Histórico: Botões de "Voltar" e "Avançar" manipulam um histórico de navegação (navigationHistory, forwardHistory).
• Subir Nível: O botão "Subir" navega para a pasta pai da pasta atual.
• Breadcrumbs: Permitem a navegação rápida para qualquer pasta no caminho atual.
• Painel de Navegação: Um painel lateral com uma TreeView completa da estrutura de pastas.

Visualização

• Modos de Exibição: O usuário pode alternar entre grid, list e details. O estado é mantido na variável viewMode.
• Ordenação: No modo details, as colunas podem ser clicadas para ordenar os itens por nome, data, tipo ou tamanho.

Menu de Contexto (Clique com o Botão Direito)

• Aparece ao clicar com o botão direito em um item.
• Ações:
  • Visualizar/Abrir: Abre o arquivo ou pasta.
  • Baixar: Inicia o download do arquivo.
  • Fluxo de Trabalho: Abre um modal que busca informações do item na tabela gerenciador_dados (integração com o Gerenciador de Dados).
  • Copiar Caminho: Copia o breadcrumbs do item para a área de transferência.
  • Propriedades: Exibe um modal com metadados detalhados do item.

Upload de Arquivos

• Um modal permite o upload de arquivos via arrastar e soltar (drag-and-drop) ou seleção manual.
• Para usuários administradores, o upload é feito para a pasta atualmente visualizada.
• Para não-administradores, os arquivos são redirecionados para uma pasta de trabalho pessoal para evitar desorganização do acervo principal.

Rota fileBrowserRoute.js

• Esta rota é uma ferramenta administrativa e não faz parte do fluxo principal do usuário.
• Ela inicia uma instância do filebrowser (um software de terceiros) que expõe todo o sistema de arquivos do servidor (root: "/").
• Propósito: Oferecer uma maneira rápida para administradores acessarem e gerenciarem arquivos diretamente no servidor, se necessário.
• Segurança: A rota define um tempo de expiração de 60 minutos, após o qual o processo do filebrowser é encerrado automaticamente.