Pular para conteúdo

OCR Pipeline — Extração de Documentos

1. Visão Geral

  • Slug: ocr-pipeline
  • Grupo: Geral
  • Página (rota): /ocr-pipeline
  • API base: /api/ocr-pipeline
  • Permissão RBAC: tool:ocr-pipeline ou tool:* (ADMIN acessa)

Envie PDFs, imagens (JPG, PNG, TIFF, BMP) ou um ZIP contendo vários arquivos. O sistema realiza OCR, classifica o tipo de documento (nota fiscal, recibo, contrato…) e extrai campos como CNPJ, CPF, datas e valores. O resultado é uma planilha Excel com todos os dados organizados.

2. Objetivo Operacional

  • Automatizar a leitura e indexação de documentos físicos digitalizados ou PDFs nativos sem necessidade de digitação manual.
  • Suporta envio único, múltiplos arquivos e ZIP com vários documentos internos.
  • Exibe aviso explícito para arquivos que não foram convertidos corretamente, sem interromper o lote.

3. Arquivos Relacionados (Verificados)

  • Página HTML: public/ocr-pipeline.html
  • Script JS da ferramenta: public/js/ocr-pipeline.js
  • Router Node: src/routes/tools/ocr-pipeline.routes.js
  • Multer (storage): src/services/tool-storage.service.js → uploadOcrPipeline
  • Endpoint Python: api/integra_api.py → POST /api/ocr-pipeline/processar
  • Pipeline Python: Robôs Leonardo/OCR Pipeline/pipeline.py (chamado via pipeline.run())
  • Catálogo: src/core/tool-catalog.json → slug ocr-pipeline
  • Sidebar: public/js/sidebar.js → grupo geral

4. Rotas e Endpoints

  • Rota de página: /ocr-pipeline
  • Base de API: /api/ocr-pipeline
  • Endpoints no router:
  • POST /processar — recebe arquivos via multer, salva em job dir, chama Python via axios
  • GET /download/:jobId — serve o Excel gerado para download

5. Fluxo Técnico (Página → Node → Python)

  1. Usuário seleciona arquivos (drag-and-drop ou seleção manual) e clica em Processar.
  2. Frontend faz POST /api/ocr-pipeline/processar com multipart/form-data (campo files).
  3. Node salva os arquivos em data/ocr-pipeline/<jobId>/input/.
  4. Node chama axios.post(PY_BASE_URL + '/api/ocr-pipeline/processar', { input_dir, output_excel }).
  5. Python (integra_api.py) extrai ZIPs, chama pipeline.run() e devolve JSON com total, ok_count, failed[].
  6. Node retorna { ok, total, ok_count, failed, downloadUrl } ao frontend.
  7. Frontend habilita o botão de download e exibe aviso com a lista de arquivos com problema.
  8. GET /api/ocr-pipeline/download/:jobId serve o arquivo resultado.xlsx.

6. Configuração (variáveis de ambiente opcionais)

Variável Padrão Descrição
OCR_PIPELINE_DIR ../../Robôs Leonardo/OCR Pipeline (relativo ao repositório) Caminho até a pasta do pipeline OCR Python

Se o pipeline estiver instalado no mesmo ambiente Python que o integra_api.py, nenhuma variável extra é necessária — o caminho padrão é resolvido automaticamente.

7. Segurança e Governança

  • Exige autenticação ativa no portal.
  • RBAC por ferramenta (tool:ocr-pipeline, tool:*, ADMIN).
  • Multer: disco, máximo 50 arquivos por envio, 200 MB por arquivo.
  • Download protegido por validação de jobId (regex [\w-]+) e path.resolve anti-traversal.
  • auditLog registra page_view_ocr_pipeline na abertura da página.

8. Entradas e Saídas Esperadas

  • Entradas: arquivos .pdf, .jpg, .jpeg, .png, .tiff, .tif, .bmp, .zip (campo files).
  • Saídas:
  • JSON { ok, total, ok_count, failed[], downloadUrl } no POST.
  • Arquivo ocr-pipeline-resultado.xlsx no GET de download.
  • Erros esperados:
  • 503 se o módulo OCR Pipeline não estiver carregado no ambiente Python.
  • 400 se nenhum arquivo for enviado.
  • 404 no download se o Excel não tiver sido gerado (pipeline falhou completamente).

9. Troubleshooting Rápido

  • 503 no processamento: verificar se OCR_PIPELINE_DIR aponta para a pasta correta e se as dependências do pipeline estão instaladas no venv Python (pip install -r requirements.txt na pasta do pipeline).
  • 401/403: conferir sessão do usuário e permissão RBAC.
  • 404 no download: o pipeline pode ter falhado antes de gerar o Excel — verificar logs do integra_api.py.
  • 500: inspecionar logs do Node (console.error) e logs do servidor Python.
  • Arquivos no aviso de falha: normal para PDFs corrompidos ou imagens muito baixa resolução — os demais arquivos do lote são processados normalmente.

10. Observações de Manutenção

  • Os arquivos de job em data/ocr-pipeline/ não são limpos automaticamente — implementar rotina de limpeza periódica se necessário.
  • Ao atualizar o pipeline Python, verificar compatibilidade da interface pipeline.run() e dos campos de DocumentRecord.
  • Se incluir nova API/fluxo, atualizar este documento e src/core/tool-catalog.json.