From 0856e00402a1997918874f6b5503af11d52c4124 Mon Sep 17 00:00:00 2001 From: Caio Date: Wed, 26 Aug 2026 14:44:48 -0300 Subject: [PATCH] docs(project): integrate with obsidian memory and standard docs --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++ README.md | 3 ++ docs/escopo.md | 50 ++++++++++++++++++++++++++++ docs/fases.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 199 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/escopo.md create mode 100644 docs/fases.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..064ff8c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# 📄 PDF Toolkit — Manipulação, Otimização e Conversão de PDFs + +@~/AGENTS.md + +## 🧠 Contexto do Projeto & Memória no Obsidian +- **Cofre Principal:** `$OBSIDIAN_VAULT_PATH/` +- **Ficha do Projeto:** `$OBSIDIAN_VAULT_PATH/03_Dev_Projetos/PDF_Toolkit/00_Index.md` +- **Padrões de Arquitetura:** `$OBSIDIAN_VAULT_PATH/03_Dev_Projetos/PDF_Toolkit/padroes-arquitetura.md` +- **Registro de Gotchas & Lições:** `$OBSIDIAN_VAULT_PATH/03_Dev_Projetos/PDF_Toolkit/gotchas-e-bugs.md` +- **Especificação de Escopo:** [docs/escopo.md](docs/escopo.md) +- **Roadmap & Fases:** [docs/fases.md](docs/fases.md) +- **Documentação de Arquitetura Local:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) +- **Documentação de Endpoints da API:** [docs/API.md](docs/API.md) + +--- + +## 🛠️ Stack Tecnológica & Comandos +- **Linguagem & Runtime:** Python 3.12+ +- **Bibliotecas Core:** `pypdf` (manipulação de estrutura/streams), `Pillow` (reamostragem de imagens JPEG/PNG) +- **Camada Web / GUI:** Streamlit (porta `8550`) +- **Camada API REST:** FastAPI + Uvicorn (porta `8555`) +- **Containerização:** Docker e Docker Compose (`Dockerfile.api`, `Dockerfile.web`, `docker-compose.yml`) +- **Testes Unitários:** Pytest + +### Comandos de Execução Local: +```bash +# Instalação de dependências +pip install -r requirements.txt + +# Executar Interface Web (Streamlit) +streamlit run app.py --server.port 8550 + +# Executar API REST (FastAPI com recarregamento dinâmico) +uvicorn api:app --host 0.0.0.0 --port 8555 --reload + +# Executar suíte de testes unitários +pytest tests/ -v +``` + +### Comandos Docker: +```bash +# Subir ambos os serviços (GUI + API) +docker compose up -d + +# Visualizar logs +docker compose logs -f + +# Parar serviços +docker compose down +``` + +--- + +## 📐 Diretrizes de Engenharia Locais +1. **Processamento In-Memory:** Todas as operações do `core/` devem operar recebendo `bytes` e devolvendo `bytes` via `io.BytesIO`. Não grave arquivos temporários em disco sem necessidade expressa. +2. **Proteção contra Inflação:** No pipeline de compressão, sempre compare o tamanho final gerado com o original. Caso o resultado seja maior, descarte a re-escrita e preserve os bytes originais (`reduced: False`). +3. **Desacoplamento Core / Interfaces:** Nenhuma lógica de negócio ou manipulação de PDF deve residir diretamente em `api.py` ou `app.py`. Ambas as interfaces devem chamar exclusivamente a fachada `PDFEngine` de `core/engine.py`. +4. **Validação Rigorosa:** Sempre validar o cabeçalho do arquivo (`validate_pdf`) antes de processar operações para evitar exceções não tratadas em arquivos corrompidos. diff --git a/README.md b/README.md index 7512814..fd7cf5a 100644 --- a/README.md +++ b/README.md @@ -90,8 +90,11 @@ pdf-toolkit/ │ └── run-api.sh # Inicia API ├── tests/ # Testes unitários ├── docs/ +│ ├── escopo.md # Especificação de escopo e anti-scope +│ ├── fases.md # Roadmap de execução e fases │ ├── ARCHITECTURE.md # Detalhamento técnico │ └── API.md # Documentação da API +├── AGENTS.md # Ponte de contexto para Agentes de IA e Obsidian └── tmp/ # Arquivos temporários (gitignored) ``` diff --git a/docs/escopo.md b/docs/escopo.md new file mode 100644 index 0000000..eee27f3 --- /dev/null +++ b/docs/escopo.md @@ -0,0 +1,50 @@ +# 📋 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. diff --git a/docs/fases.md b/docs/fases.md new file mode 100644 index 0000000..e7e8834 --- /dev/null +++ b/docs/fases.md @@ -0,0 +1,88 @@ +# 🗺️ 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/`) +- [x] Configuração central em `config.py` com limites de payload, presets e portas. +- [x] Criação do validador de integridade e magic bytes (`core/validators.py`). +- [x] Implementação da fachada orquestradora `PDFEngine` (`core/engine.py`). +- [x] Testes unitários do motor base com geração de PDFs sintéticos. + +--- + +## 🟢 Fase 2: Módulo de Otimização & Compressão +- [x] Algoritmo de reamostragem de imagens via Pillow com filtro LANCZOS (`core/compress.py`). +- [x] Mapeamento dos 4 presets padrão (`screen`, `ebook`, `printer`, `prepress`). +- [x] Implementação de guarda defensiva anti-inflação de arquivo. +- [x] Coleta de métricas e estatísticas comparativas de redução. + +--- + +## 🟢 Fase 3: Detecção & Higienização de PDF/A +- [x] Detecção de nós XMP `` / `conformance` via regex (`core/pdfa.py`). +- [x] Detecção de `/OutputIntents` no dicionário raiz. +- [x] Conversão de PDF/A para PDF comum (`strip_pdfa`) removendo restrições. +- [x] Compressão compatível com PDF/A (`compress_pdfa`). + +--- + +## 🟢 Fase 4: Operações Estruturais & Extração +- [x] Concatenação de múltiplos arquivos (`merge_pdfs` em `core/operations.py`). +- [x] Divisão por intervalos de páginas (`split_pdf`). +- [x] Extração de páginas específicas (`extract_pages`). +- [x] Rotação de páginas em 90°, 180° e 270° (`rotate_pages`). +- [x] Extração de texto bruto (`extract_text`). +- [x] Extração de imagens embutidas (`extract_images`). + +--- + +## 🟢 Fase 5: Interface Web Interativa (Streamlit) +- [x] Criação da aplicação Streamlit (`app.py`). +- [x] Aba de compressão com slider de preset e cálculo de economia percentual. +- [x] Aba de conversão e saneamento de PDF/A. +- [x] Abas de operações estruturais (Merge, Split, Extract, Rotate). +- [x] Aba de extração de texto e imagens com download imediato. +- [x] Aba de inspeção e metadados com badge de conformidade. + +--- + +## 🟢 Fase 6: API REST & Documentação OpenAPI (FastAPI) +- [x] Criação dos endpoints em `api.py` correspondentes a todas as operações. +- [x] Documentação automática Swagger UI (`/docs`) e Redoc (`/redoc`). +- [x] Middleware CORS para conexões externas. +- [x] Autenticação opcional por header `X-API-Key`. +- [x] Endpoint de monitoramento de integridade (`GET /health`). + +--- + +## 🟢 Fase 7: Containerização & Scripts de Execução +- [x] Criação de `Dockerfile.web` (Streamlit) e `Dockerfile.api` (FastAPI). +- [x] Configuração de `docker-compose.yml` para orquestração de ambos os serviços. +- [x] Scripts de inicialização Linux `scripts/run-web.sh` e `scripts/run-api.sh`. + +--- + +## 🟢 Fase 8: Testes Automatizados & Qualidade +- [x] Criação da suíte de testes em `tests/test_core.py`. +- [x] Validação de compressão, detecção PDF/A, rotação, extração e merge. +- [x] Verificação de integridade dos streams gerados. + +--- + +## 🟢 Fase 9: Integração com Obsidian Vault & Memória Técnica +- [x] Criação da ficha mestra `00_Index.md` em `03_Dev_Projetos/PDF_Toolkit/`. +- [x] Criação do documento `padroes-arquitetura.md` no cofre. +- [x] Criação do registro `gotchas-e-bugs.md` no cofre. +- [x] Documentação de Architecture Decision Records (ADR-001, ADR-002, ADR-003). +- [x] Criação do arquivo de ponte para agentes `AGENTS.md` na raiz do repositório. +- [x] 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.