pdf-toolkit/docs/fases.md

🗺️ Roadmap de Execução & Fases — PDF Toolkit

Documento de acompanhamento do ciclo de vida e marcos do PDF Toolkit.

---

🟢 Fase 1: Arquitetura Base & Motor Orquestrador (core/)

• Configuração central em config.py com limites de payload, presets e portas.
• Criação do validador de integridade e magic bytes (core/validators.py).
• Implementação da fachada orquestradora PDFEngine (core/engine.py).
• Testes unitários do motor base com geração de PDFs sintéticos.

---

🟢 Fase 2: Módulo de Otimização & Compressão

• Algoritmo de reamostragem de imagens via Pillow com filtro LANCZOS (core/compress.py).
• Mapeamento dos 4 presets padrão (screen, ebook, printer, prepress).
• Implementação de guarda defensiva anti-inflação de arquivo.
• Coleta de métricas e estatísticas comparativas de redução.

---

🟢 Fase 3: Detecção & Higienização de PDF/A

• Detecção de nós XMP <pdfaid:part> / conformance via regex (core/pdfa.py).
• Detecção de /OutputIntents no dicionário raiz.
• Conversão de PDF/A para PDF comum (strip_pdfa) removendo restrições.
• Compressão compatível com PDF/A (compress_pdfa).

---

🟢 Fase 4: Operações Estruturais & Extração

• Concatenação de múltiplos arquivos (merge_pdfs em core/operations.py).
• Divisão por intervalos de páginas (split_pdf).
• Extração de páginas específicas (extract_pages).
• Rotação de páginas em 90°, 180° e 270° (rotate_pages).
• Extração de texto bruto (extract_text).
• Extração de imagens embutidas (extract_images).

---

🟢 Fase 5: Interface Web Interativa (Streamlit)

• Criação da aplicação Streamlit (app.py).
• Aba de compressão com slider de preset e cálculo de economia percentual.
• Aba de conversão e saneamento de PDF/A.
• Abas de operações estruturais (Merge, Split, Extract, Rotate).
• Aba de extração de texto e imagens com download imediato.
• Aba de inspeção e metadados com badge de conformidade.

---

🟢 Fase 6: API REST & Documentação OpenAPI (FastAPI)

• Criação dos endpoints em api.py correspondentes a todas as operações.
• Documentação automática Swagger UI (/docs) e Redoc (/redoc).
• Middleware CORS para conexões externas.
• Autenticação opcional por header X-API-Key.
• Endpoint de monitoramento de integridade (GET /health).

---

🟢 Fase 7: Containerização & Scripts de Execução

• Criação de Dockerfile.web (Streamlit) e Dockerfile.api (FastAPI).
• Configuração de docker-compose.yml para orquestração de ambos os serviços.
• Scripts de inicialização Linux scripts/run-web.sh e scripts/run-api.sh.

---

🟢 Fase 8: Testes Automatizados & Qualidade

• Criação da suíte de testes em tests/test_core.py.
• Validação de compressão, detecção PDF/A, rotação, extração e merge.
• Verificação de integridade dos streams gerados.

---

🟢 Fase 9: Integração com Obsidian Vault & Memória Técnica

• Criação da ficha mestra 00_Index.md em 03_Dev_Projetos/PDF_Toolkit/.
• Criação do documento padroes-arquitetura.md no cofre.
• Criação do registro gotchas-e-bugs.md no cofre.
• Documentação de Architecture Decision Records (ADR-001, ADR-002, ADR-003).
• Criação do arquivo de ponte para agentes AGENTS.md na raiz do repositório.
• Especificação de escopo em docs/escopo.md e roadmap em docs/fases.md.

---

🟡 Fase 10: Próximas Evoluções (Backlog Futuro)

• Módulo opcional de OCR com suporte a Tesseract para PDFs digitalizados.
• Processamento assíncrono em segundo plano com Celery / Redis para lotes maciços (> 50 arquivos).
• Suporte a Linearização ("Fast Web View") via integração opcional com binário qpdf.
• Endpoint para assinatura de carimbo d'água personalizado com transparência.