pdf-toolkit/docs/escopo.md

📋 Especificação de Escopo — PDF Toolkit

1. Visão Geral do Produto & Personas

O PDF Toolkit é uma plataforma utilitária completa de processamento, otimização e saneamento de arquivos PDF desenvolvida para resolver as necessidades diárias de manipulação documental de forma rápida, privada e desacoplada de soluções em nuvem públicas de terceiros.

Personas:

• Consultores Técnicos & Usuários Administrativos: Necessitam compactar arquivos pesados para envio por e-mail/WhatsApp, converter arquivos restritos no padrão PDF/A para PDF editável, rotacionar digitalizações e unir/separar relatórios através de uma interface web simples e interativa.
• Desenvolvedores & Agentes Autônomos de IA: Necessitam de uma API REST stateless de alto desempenho para submeter fluxos de arquivos e receber PDFs transformados ou dados extraídos (texto/imagens/metadados) em pipelines de automação.

---

2. Requisitos Funcionais do MVP (In-Scope)

1. Otimização & Compressão Inteligente:

   • Compressão de arquivos através da reamostragem e re-compressão de imagens rasterizadas com algoritmo LANCZOS.
   • Quatro presets pré-configurados: screen (30% / 1200px), ebook (60% / 2000px), printer (85% / 3500px) e prepress (95% / 5000px).
   • Mecanismo de guarda anti-inflação: se a regravação gerar um arquivo maior, o sistema descarta e entrega o original intacto.

2. Saneamento & Gestão de PDF/A:

   • Detecção automática de conformidade PDF/A via análise de metadados XMP (pdfaid:part/conformance) e /OutputIntents.
   • Conversão e desregulamentação (pdfa-to-regular): remoção cirúrgica de restrições PDF/A mantendo a fidelidade visual das páginas.
   • Compressão preservando a estrutura PDF/A (compress-pdfa).

3. Operações Estruturais de Páginas:

   • Merge (Concatenação): Junção ordenada de múltiplos arquivos PDF com preservação de estrutura.
   • Split (Divisão): Separação de documentos em intervalos de páginas configuráveis.
   • Extract Pages: Extração pontual de listas de páginas (ex: 1, 3, 5-8) em um único arquivo de saída.
   • Rotate: Rotação de páginas individuais ou em lote em ângulos de 90°, 180° ou 270°.

4. Extração de Informações:

   • Extração de Texto: Extração de texto bruto indexável por página.
   • Extração de Imagens: Localização e download de todas as imagens embutidas no documento no formato PNG/JPEG.
   • Inspeção de Metadados: Análise de número de páginas, tamanho, integridade e diagnóstico de conformidade PDF/A.

5. Interfaces & Acesso:

   • Interface Web (Streamlit): GUI em abas temáticas, drag-and-drop, sliders interativos e cálculo de delta de compressão.
   • API REST (FastAPI): Endpoints assíncronos, documentação interativa Swagger (/docs) e Redoc (/redoc), suporte a autenticação por X-API-Key.

6. Containerização & Deploy:

   • Empacotamento em Docker multi-container com docker-compose para execução simultânea da API (:8555) e da Web (:8550).

---

3. Limites do MVP (Anti-Scope)

• ❌ OCR (Optical Character Recognition) Complexo: O MVP não executa OCR com Tesseract/EasyOCR em imagens escaneadas sem camada de texto (extração de texto limita-se ao texto vetorial/digital existente).
• ❌ Linearização Binária True Fast Web View: Não inclui reestruturação de baixo nível com dependências binárias C (qpdf/Ghostscript) para manter a portabilidade 100% Python.
• ❌ Assinatura Digital Criptográfica / PKCS#7: Não realiza assinatura de certificados A1/A3 (ICP-Brasil) ou aposição de carimbos do tempo nesta versão.
• ❌ Persistência de Histórico de Arquivos em Banco de Dados: A aplicação é 100% stateless; arquivos processados não são salvos em banco nem retidos após a entrega do stream.