TODO: Nova Hierarquia de Documentos e Sistema de Storage

Criado em: 2026-01-10
Status: 📋 Planejamento
Prioridade: Alta

📚 1. Sistema de Hierarquia de Documentos (Estilo Biblioteca)

Visão Geral

Reelaborar completamente o sistema de hierarquia de documentos utilizando uma metáfora de biblioteca, permitindo agrupamentos mais elaborados e uma estrutura visual indentada no menu lateral.

Nova Estrutura Hierárquica

📁 Departamento (Department)
  └── 📚 Estante (Bookshelf)
      └── 📖 Prateleira (Shelf)
          └── 📕 Livro (Book)
              └── 📑 Capítulo (Chapter)
                  └── 📄 Página/Seção (Page/Section)

Tarefas

1.1 Análise e Planejamento

• Analisar estrutura atual do banco de dados (docs, spaces, etc.)
• Mapear migração de dados existentes para nova estrutura
• Definir limites por nível hierárquico (quantos itens permitidos por nível)
• Documentar regras de negócio para cada nível

1.2 Modelagem de Banco de Dados

• Criar nova tabela ou adaptar existente para suportar níveis hierárquicos
• Definir campos necessários:
  • id (UUID)
  • parent_id (referência ao item pai)
  • type (enum: department, bookshelf, shelf, book, chapter, page)
  • title (string, i18n)
  • slug (string, único por nível)
  • order_index (integer, ordenação dentro do nível)
  • icon (string, opcional)
  • color (string, opcional)
  • metadata (jsonb, dados extras)
  • created_at, updated_at
• Criar índices para performance
• Criar migrations

1.3 API e Backend

• Criar/atualizar endpoints para CRUD de cada nível
• Implementar lógica de movimentação entre níveis
• Implementar validações de profundidade máxima
• Criar queries otimizadas para carregamento em árvore
• Implementar cache para estrutura hierárquica

1.4 Frontend - Menu Lateral

• Redesenhar componente de navegação lateral
• Implementar expansão/colapso de níveis (accordion)
• Adicionar indicadores visuais por tipo (ícones diferenciados)
• Implementar indentação visual clara
• Adicionar drag-and-drop para reorganização
• Implementar busca/filtro na árvore
• Adicionar breadcrumbs de navegação

1.5 Frontend - Gestão

• Criar interface para criação de novos níveis
• Implementar modal/drawer para edição de propriedades
• Adicionar confirmação para exclusão (com alerta de itens filhos)
• Implementar preview da estrutura

1.6 Internacionalização (i18n)

• Adicionar traduções para todos os novos termos (PT, EN, ES, FR)
• Criar labels para tipos de níveis
• Traduzir mensagens de erro e validação

1.7 Acessibilidade (a11y)

• Implementar navegação por teclado na árvore
• Adicionar atalhos de teclado:
  • Cmd/Ctrl + N - Novo item
  • Cmd/Ctrl + ↑/↓ - Navegar entre itens
  • Cmd/Ctrl + →/← - Expandir/colapsar
• Adicionar ARIA labels adequados
• Testar com leitores de tela

1.8 Migração de Dados

• Criar script de migração de spaces → departments/bookshelves
• Criar script de migração de docs → books/chapters
• Implementar rollback de migração
• Testar em ambiente de staging

🖼️ 2. Sistema de Armazenamento de Imagens e Arquivos

Visão Geral

Implementar funcionalidade de upload e armazenamento de imagens/arquivos, vinculada aos planos de assinatura (recurso pago).

Tarefas

2.1 Análise de Requisitos

• Definir tipos de arquivo permitidos (imagens, PDFs, etc.)
• Definir limites de tamanho por arquivo
• Definir cotas de armazenamento por plano:
  • Free: Sem armazenamento (ou limite mínimo ex: 10MB)
  • Starter: X GB
  • Pro: Y GB
  • Enterprise: Z GB ou ilimitado
• Definir política de retenção e exclusão

2.2 Infraestrutura de Storage

• Avaliar opções de storage:
  • Supabase Storage
  • Cloudflare R2
  • AWS S3
• Configurar bucket/container de armazenamento
• Configurar políticas de acesso (RLS)
• Configurar CDN para entrega otimizada
• Implementar compressão automática de imagens

2.3 Modelagem de Banco de Dados

• Criar tabela files ou assets:
  • id (UUID)
  • user_id (referência ao usuário)
  • doc_id (referência ao documento, opcional)
  • filename (nome original)
  • storage_path (caminho no storage)
  • mime_type (tipo do arquivo)
  • size_bytes (tamanho em bytes)
  • width, height (para imagens)
  • public_url (URL pública)
  • created_at
• Criar tabela storage_usage para tracking de consumo:
  • user_id
  • total_bytes
  • file_count
  • updated_at
• Criar migrations

2.4 API e Backend

• Criar endpoint de upload (POST /api/files/upload)
• Criar endpoint de listagem (GET /api/files)
• Criar endpoint de exclusão (DELETE /api/files/:id)
• Implementar validação de plano antes do upload
• Implementar cálculo de uso de storage
• Criar webhook/trigger para atualizar uso ao upload/delete
• Implementar geração de thumbnails

2.5 Frontend - Upload

• Criar componente de upload com drag-and-drop
• Implementar preview antes do upload
• Mostrar progresso de upload
• Tratar erros de upload (tamanho, tipo, cota)
• Integrar com editor de documentos (inserir imagem)

2.6 Frontend - Gestão de Arquivos

• Criar página/modal de biblioteca de mídia
• Implementar visualização em grid/lista
• Adicionar busca e filtros
• Implementar seleção múltipla
• Adicionar ações em lote (excluir, mover)

2.7 Integração com Planos

• Adicionar campo storage_limit_bytes na tabela de planos
• Criar componente de uso de storage no dashboard
• Implementar alertas de aproximação do limite (80%, 90%, 100%)
• Bloquear upload quando limite atingido
• Mostrar CTA de upgrade quando próximo do limite

2.8 Internacionalização (i18n)

• Adicionar traduções para mensagens de upload
• Traduzir labels de tipos de arquivo
• Traduzir mensagens de erro de cota

2.9 Acessibilidade (a11y)

• Adicionar atalho de teclado para upload rápido
• Implementar navegação por teclado na biblioteca
• Adicionar alt text obrigatório para imagens

📊 Cronograma Sugerido

Total estimado: 10-16 semanas

🔗 Dependências e Considerações

Dependências Técnicas

• Verificar compatibilidade com Supabase RLS atual
• Avaliar impacto no MCP Server
• Verificar necessidade de atualizar extensão

Considerações de UX

• Manter retrocompatibilidade com URLs existentes
• Implementar redirecionamentos se slugs mudarem
• Criar onboarding/tutorial para nova estrutura

Considerações de Performance

• Limitar profundidade de busca na árvore
• Implementar lazy loading para níveis profundos
• Cache agressivo da estrutura de navegação

📝 Notas Adicionais

⚠️ Importante: Este documento será expandido conforme novos requisitos forem identificados.

Última atualização: 2026-01-10