Pular para o conteúdo principal

Gerenciamento OCR (IDP) - Instruções de Engenharia e Arquitetura

📋 Contexto Estratégico (Intelligent Document Processing)​

O módulo de Gerenciamento de OCR é o coração da visualização de dados processados no ArboreoLab. Estamos em uma fase crítica de ingestão de dados com as seguintes premissas de escala:

  • Volume: 150.000 documentos (imagens/PDFs) em ingestão.
  • Estado Atual: ~16.000 registros já processados com OCR.
  • Unidade de Trabalho: O documento final (PDF tratado/concatenado). Arquivos de imagens soltos são considerados etapas intermediárias.

🏛️ Diretrizes Arquiteturais (Senior Engineer Mandates)​

  1. Escalabilidade Obrigatória (Server-Side First):

    • É proibido carregar listas completas (SELECT *) no Frontend.
    • Todas as listagens devem implementar Paginação no Backend (LIMIT, OFFSET) e filtros via WHERE.
    • A interface deve suportar navegação fluida mesmo com 1 milhão de registros.

  2. Separação de Responsabilidades (Role Separation):

    • Consultores ArboreoLab (Backend UI): Responsáveis pela Produção (disparo de scripts, reprocessamento, correção estrutural).
    • Assinantes/Usuários (Frontend UI): Responsáveis pela Visualização/Auditoria. Edição de conteúdo é restrita ao Proprietário do projeto.

  3. Robustez de Dados:

    • O sistema deve ser resiliente a múltiplos formatos de JSON de OCR (Legacy Support).
    • A integridade (vinculação entre OCR, Drive e Metadados) é a métrica de sucesso.

🗺️ Roadmap de Execução​

FASE 1: Escalabilidade e Navegação (Frontend Assinante)​

Foco: Refatorar GerenciadorOCR.vue e endpoints para suportar paginação e filtros hierárquicos.

1.1. Paginação Server-Side​

  • Backend:
    • Deprecar/Remover endpoint /list-all.
    • Criar endpoint GET /api/gerenciador-dados/ocr/list aceitando:
      • page (default: 1)
      • limit (default: 50)
      • search (termo de busca SQL LIKE)
      • collection (filtro por pasta/coleção)
      • sortBy (coluna de ordenação)
    • Retornar objeto: { data: [], meta: { total, pages, current } }.

1.2. Sidebar de Navegação (Filtro por Coleções)​

  • Requisito: O usuário precisa filtrar os OCRs baseando-se na estrutura de pastas (Coleções) do seu projeto.
  • Implementação:
    • Criar endpoint para listar "Coleções com OCR" (SELECT DISTINCT google_drive_folder_nome ou join com gerenciamento_googledrive).
    • Atualizar Sidebar do GerenciadorOCR.vue para exibir uma árvore ou lista de coleções selecionáveis.
    • Ao selecionar uma coleção, recarregar a lista (reset page=1) passando o filtro para o Backend.

FASE 2: Workflow de Produção (Backend UI - Consultores)​

Foco: Interface exclusiva para consultores dispararem o processamento.

2.1. Card de Produção de OCR​

  • Localização: Interface Vue.js administrativa (Backend UI).
  • Funcionalidade:
    • Listar projetos/assinantes com demanda de OCR.
    • Visualizar fila de processamento.
    • Botão de Ação: Disparar serviço Python de OCR para um lote específico.
    • Feedback: Monitorar logs de inserção no MariaDB.

FASE 3: Robustez e Visualização (Refatoração)​

Foco: Garantir que o gerenciadordeocr.vue (visualizador) nunca quebre, independente do formato do JSON.

3.1. Serviço de Parsing (OcrContentParser)​

  • Extrair lógica de extractedText (atualmente no .vue) para src/services/OcrContentParser.ts.
  • Padronizar a saída para um formato intermediário consumível pela UI.
  • Garantir suporte aos 7 formatos conhecidos de resposta do Gemini/OCR.

FASE 4: Segurança e RBAC​

Foco: Controle de acesso granular.

  • Middleware: Garantir requireRead() para listagem e requireOwner() para qualquer rota de edição/correção manual de texto (se implementada).
  • Frontend:
    • Utilizar usePermissions para renderizar condicionalmente botões de ação.
    • Visualização: Aberta para visitante (dentro do projeto).
    • Edição: Apenas owner (regra de negócio atual).

🛠️ Especificações Técnicas​

Padrão de Query (Listagem Otimizada)​

-- Query Principal
SELECT 
  id, workflow_id, name, url_id, 
  data_ultima_atualizacao, qtde_caracteres, 
  google_drive_folder_nome, cluster_id
FROM clio_ocr
WHERE 
  (@collection IS NULL OR google_drive_folder_nome = @collection)
  AND (@search IS NULL OR name LIKE CONCAT('%', @search, '%'))
ORDER BY data_ultima_atualizacao DESC
LIMIT @limit OFFSET @offset;

-- Query de Contagem (para paginação)
SELECT COUNT(*) as total 
FROM clio_ocr 
WHERE ... (mesmos filtros);

---

# Contrato de Interface (OcrContentParser)

```TypeScript
interface IOcrParserOutput {
  rawText: string;           // Texto corrido para copy/paste
  structuredPages: Array<{   // Para visualização paginada
    pageNumber: number;
    text: string;
    confidence?: number;
  }>;
  metadata: Record<string, any>;
  formatDetected: string;
}

O Que Não Fazer
Nunca fazer cache de 150k registros no Frontend (Pinia/Vuex).
Nunca permitir que a busca (search) filtre arrays em memória no cliente. O banco de dados é otimizado para isso, o browser não.
Nunca misturar rotas de "Produção" (Admin/Consultor) com rotas de "Consumo" (Assinante) no mesmo arquivo de rota do Express.