📄 PDF Conversion

Sistema profissional de conversão automatizada de documentos Word para PDF utilizando Python, Playwright e arquitetura baseada em Tasks.

✨ Destaques

🚀 Conversão Automática - Word (.docx, .doc) → PDF via web automation
🏗️ Arquitetura Sólida - Design patterns (Template Method, Chain of Responsibility)
⚙️ Multi-Ambiente - Development/Production com Dynaconf
📊 Logging Robusto - Sistema completo com rotação e níveis configuráveis
🔄 Retry Inteligente - Retry automático com backoff exponencial
🎯 Extensível - Sistema de tasks modular e fácil de estender
🤖 IA-Ready - Documentação completa para agentes IA (1950+ linhas)

📋 Características Técnicas

Funcionalidades

✅ Conversão automática de documentos Word para PDF
✅ Suporte a múltiplos formatos (.docx, .doc)
✅ Processamento em lote otimizado
✅ Validação de arquivos (tamanho, formato, integridade)
✅ Download e validação de PDFs gerados
✅ Sistema de logs estruturado (success/failed)
✅ Retry automático em caso de falhas
✅ Configuração externalized (12-factor app)

Arquitetura

🎨 Template Method Pattern - BaseTask com lógica comum
🔗 Chain of Responsibility - Workflow orquestrando tasks
💉 Dependency Injection - Baixo acoplamento entre componentes
🔒 Singleton - Configuração centralizada
🧹 Context Manager - Gerenciamento automático de recursos

🚀 Quick Start

# 1. Clone o repositório
git clone https://github.com/RennoDev/PDF-Conversion.git
cd PDF-Conversion

# 2. Instale dependências (usando uv)
uv sync

# 3. Instale navegadores Playwright
uv run playwright install chromium

# 4. Configure ambiente (copie e edite)
cp .env.example .env

# 5. Adicione arquivos Word para converter
cp seu_arquivo.docx documents/documents_to_convert/

# 6. Execute a conversão
uv run main
# ou
uv run pdf-conversion

🎯 Resultado

✅ PDFs gerados em: documents/converted_documents/
📊 Logs de sucesso: logs/success/
❌ Logs de erro: logs/failed/

📚 Documentação

📖 Documentação para Usuários

A documentação completa está em docs/:

Para Começar (20 min)

🚀 Início Rápido - Instalação e primeiro uso
⚙️ Configuração - Personalizar settings.toml

Entender o Projeto (45 min)

🏗️ Arquitetura - Design patterns e fluxo de execução
📦 Tasks - Sistema de tasks e BaseTask
🔄 Workflow - Orquestração de tasks

Referência Técnica

🌐 Playwright - Automação web e navegadores
📊 Logs - Sistema de logging
📖 API Reference - Documentação completa das classes
🔧 Troubleshooting - Resolução de problemas

Desenvolvimento

🤝 Contributing - Como contribuir
📏 Code Standards - Padrões de código
📂 Directory Structure - Organização

📖 Índice Completo da Documentação

🤖 Documentação para Agentes IA

Documentos Principais (~1.950 linhas)

📖 Copilot Instructions - Instruções completas (1.261 linhas)
⚡ Quick Reference - Resumo executivo (157 linhas)
🤖 AI Contributors Guide - Guia de uso IA (280 linhas)
📚 Agent Docs Index - Índice e navegação (251 linhas)

Cobertura

✅ Arquitetura completa (5 design patterns)
✅ Todos os módulos documentados (7 módulos)
✅ Sistema de configuração (Dynaconf multi-ambiente)
✅ Fluxo de execução (6 fases detalhadas)
✅ Padrões de código (SOLID, nomenclatura, docstrings)
✅ 4 cenários de implementação de features
✅ 3 modos de debugging
✅ 8 problemas comuns com soluções

GitHub Copilot lê automaticamente .github/copilot-instructions.md!

⚙️ Configuração Avançada

🔧 Sistema de Configuração Multi-Ambiente

O projeto usa Dynaconf para gerenciamento avançado de configurações com suporte a múltiplos ambientes.

Hierarquia de Configuração

1. settings.toml [default]      ← Base para todos os ambientes
2. settings.toml [development]  ← Override para desenvolvimento
3. settings.toml [production]   ← Override para produção
4. .env                         ← Define ambiente ativo
5. .secrets.toml                ← Dados sensíveis (não commitar!)
6. Variáveis de ambiente        ← Override final

🌍 Ambientes Disponíveis

Development (padrão)

[development]
debug = true

[development.logging]
level = "DEBUG"                    # Logs detalhados

[development.playwright]
headless = false                   # Browser VISÍVEL (para debug)
timeout = 60000                    # 60 segundos

[development.performance]
task_sleep_time = 1.0              # Mais lento (observar execução)

Production

[production]
debug = false

[production.logging]
level = "WARNING"                  # Apenas avisos/erros

[production.playwright]
headless = true                    # Browser INVISÍVEL
timeout = 30000                    # 30 segundos

[production.performance]
task_sleep_time = 0.2              # Mais rápido
max_concurrent_conversions = 5     # Mais concorrência

🔄 Trocar de Ambiente

Via arquivo .env (recomendado):

# .env
ENV_FOR_DYNACONF=production

Via linha de comando:

# Windows (PowerShell)
$env:ENV_FOR_DYNACONF="production"; uv run main

# Linux/Mac
ENV_FOR_DYNACONF=production uv run main

🔐 Configurar Secrets

Copie o template (se disponível):

cp .secrets.toml.example .secrets.toml

Edite .secrets.toml com suas credenciais:

[default]
api_key = "sua_chave_aqui"

[production]
api_key = "chave_producao"

⚠️ IMPORTANTE: .secrets.toml já está no .gitignore - NUNCA commite este arquivo!

📖 Usar Configurações no Código

from pdf_conversion.config import settings, get_path, is_development

# Acessar configurações
app_name = settings.app_name
log_level = settings.logging.level
headless = settings.playwright.headless

# Verificar ambiente
if is_development():
    print("Modo desenvolvimento ativo")

# Usar paths configuráveis
input_dir = get_path("input")
output_dir = get_path("output")

Para detalhes completos, veja: docs/configuration.md

🏗️ Estrutura do Projeto

pdf-conversion/
│
├── 📂 src/pdf_conversion/           # Código-fonte principal
│   ├── main.py                      # Entry point (asyncio.run)
│   ├── config/                      # ⚙️ Sistema de configuração
│   │   ├── config.py                # Dynaconf + helpers (ROOT_DIR, get_path)
│   │   └── playwright.py            # Browser manager (context manager)
│   └── workflow/                    # 🔄 Sistema de tasks e workflow
│       ├── workflow.py              # Orquestrador (Chain of Responsibility)
│       └── tasks/                   # Tasks modulares
│           ├── base_task.py         # ⭐ Classe abstrata (Template Method)
│           ├── document_task.py     # Busca e valida arquivos Word
│           └── navigation_task.py   # Conversão web com Playwright
│
├── 📂 docs/                         # 📚 Documentação técnica (13 arquivos)
│   ├── README.md                    # Índice da documentação
│   ├── getting-started.md           # Quick start
│   ├── architecture.md              # Design e arquitetura
│   ├── tasks.md                     # Sistema de tasks
│   └── ... (mais 9 arquivos)
│
├── 📂 examples/                     # 📖 Exemplos práticos (4 arquivos)
│   ├── example_base_task.py         # Como criar tasks customizadas
│   ├── example_config.py            # Usar configurações
│   ├── example_playwright.py        # Automação com Playwright
│   └── example_wait_for_input.py    # Input do usuário
│
├── 📂 documents/                    # 📂 I/O de arquivos
│   ├── documents_to_convert/        # ➡️ INPUT: Coloque .docx aqui
│   └── converted_documents/         # ⬅️ OUTPUT: PDFs gerados aqui
│
├── 📂 logs/                         # 📊 Sistema de logs
│   ├── success/                     # ✅ Logs de sucesso (timestamp)
│   └── failed/                      # ❌ Logs de erro (timestamp)
│
├── 📂 temp/                         # 🗑️ Arquivos temporários
│   └── downloads/                   # Downloads intermediários
│
├── 📂 .github/                      # 🤖 Configurações e instruções
│   └── copilot-instructions.md      # Instruções completas para agentes IA
│
├── ⚙️ settings.toml                 # Configurações multi-ambiente
├── 🔒 .secrets.toml                 # Segredos (não commitar)
├── 🌍 .env                          # Ambiente ativo (não commitar)
├── 📄 .env.example                  # Template do .env
├── 📦 pyproject.toml                # Dependências (uv)
├── 🤖 AGENT-QUICK-REF.md            # Quick ref para agentes
├── 🤖 AI-CONTRIBUTORS-GUIDE.md      # Guia de uso IA
├── 📚 AGENT-DOCS-INDEX.md           # Índice docs para agentes
└── 📖 README.md                     # Este arquivo

📁 Diretórios Principais

Diretório	Propósito	Quando Modificar
`src/pdf_conversion/`	Código-fonte	Adicionar features, corrigir bugs
`src/pdf_conversion/workflow/tasks/`	Tasks modulares	Criar novas tasks
`docs/`	Documentação técnica	Atualizar docs
`examples/`	Exemplos didáticos	Adicionar exemplos
`documents/`	I/O de arquivos	Uso diário (input/output)
`logs/`	Histórico de execuções	Análise de erros
`.github/`	CI/CD e instruções IA	Config GitHub Actions

💻 Como Usar

📖 Importar Configurações

from pdf_conversion.config import settings, get_path, is_development

# Acessar configurações
app_name = settings.app_name
log_level = settings.logging.level
max_size = settings.conversion.max_file_size_mb

# Verificar ambiente
if is_development():
    print("🔧 Modo desenvolvimento ativo")
else:
    print("🚀 Modo produção ativo")

# Obter paths configuráveis
input_dir = get_path("input")
output_dir = get_path("output")
temp_dir = get_path("temp")

🎯 Criar Task Customizada

from pdf_conversion.workflow.tasks.base_task import BaseTask

class MinhaTask(BaseTask):
    def __init__(self, parametro: str, **kwargs):
        super().__init__(name="minha_task", **kwargs)
        self.parametro = parametro
    
    async def execute(self):
        """Implementa lógica da task"""
        self.logger.info(f"Executando com {self.parametro}")
        
        # Sua lógica aqui
        resultado = processar_algo(self.parametro)
        
        # Sleep configurável
        self.sleep()
        
        return {
            "success": True,
            "resultado": resultado
        }

🔄 Adicionar Task ao Workflow

from pdf_conversion.workflow.workflow import Workflow
from minha_task import MinhaTask

async def run_custom_workflow():
    workflow = Workflow()
    
    # Adicionar task customizada
    workflow.add_task(MinhaTask(parametro="teste"))
    
    # Executar
    resultados = await workflow.run()
    return resultados

🌐 Usar Playwright Diretamente

from pdf_conversion.config.playwright import get_browser

async def automacao_customizada():
    async with get_browser() as manager:
        page = await manager.new_page()
        await page.goto("https://exemplo.com")
        
        # Sua automação aqui
        await page.click("#botao")
        conteudo = await page.text_content(".resultado")
        
        return conteudo

Para mais exemplos, veja: examples/

🎛️ Configurações Disponíveis

📊 Logging

Configuração	Development	Production	Descrição
`level`	DEBUG	WARNING	Nível de log
`dir`	logs	logs	Diretório de logs
`format`	Detalhado	Compacto	Formato de mensagens

📄 Conversão

Configuração	Valor	Descrição
`max_file_size_mb`	50	Tamanho máximo do arquivo
`allowed_formats`	["pdf", "doc", "docx"]	Formatos permitidos

🌐 Playwright

Configuração	Development	Production	Descrição
`headless`	false	true	Browser visível/invisível
`timeout`	60000	30000	Timeout em ms

⚡ Performance

Configuração	Development	Production	Descrição
`max_concurrent_conversions`	1	5	Conversões simultâneas
`retry_attempts`	3	5	Tentativas de retry
`task_sleep_time`	1.0	0.2	Sleep entre operações (s)

🎯 Features

Configuração	Valor	Descrição
`enable_batch_processing`	true	Processamento em lote
`enable_ocr`	false	OCR em imagens (futuro)

Para detalhes completos, veja: docs/configuration.md

🔐 Segurança e Boas Práticas

⚠️ Arquivos Sensíveis (NUNCA commitar)

.env - Ambiente ativo
.secrets.toml - API keys, passwords
logs/ - Pode conter dados sensíveis

✅ Checklist de Segurança

.gitignore configurado corretamente
.secrets.toml não commitado
Variáveis de ambiente usadas em produção
Logs não contêm senhas/tokens
Permissões de arquivos revisadas

📝 Licença

Este projeto é de código aberto. Sinta-se livre para usar, modificar e distribuir.

👤 Autor

RennoDev
📧 [email protected]
🐙 GitHub: RennoDev/PDF-Conversion

🤝 Como Contribuir

Contribuições são muito bem-vindas! Há várias formas de contribuir:

🐛 Reportar Bugs

Abra uma issue descrevendo:

O que aconteceu
O que era esperado
Passos para reproduzir
Logs relevantes

✨ Sugerir Features

Abra uma issue com:

Descrição da feature
Caso de uso
Mockups/exemplos (se aplicável)

🔧 Enviar Pull Request

Fork o projeto
Crie uma branch: git checkout -b feature/minha-feature
Commit suas mudanças: git commit -m 'feat: Adiciona minha feature'
Push para a branch: git push origin feature/minha-feature
Abra um Pull Request

📖 Melhorar Documentação

Documentação nunca é demais! PRs para:

Corrigir erros
Adicionar exemplos
Clarificar instruções
Traduzir conteúdo

Antes de contribuir, leia: AI-CONTRIBUTORS-GUIDE.md

⭐ Agradecimentos

Obrigado por usar o PDF Conversion! Se este projeto foi útil, considere dar uma ⭐ no GitHub.

Última Atualização: Outubro 2025
Versão: 0.1.0
Status: ✅ Produção

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
docs		docs
examples		examples
src/pdf_conversion		src/pdf_conversion
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
pyproject.toml		pyproject.toml
settings.toml		settings.toml
uv.lock		uv.lock

RennoDev/PDF-Conversion

Folders and files

Latest commit

History

Repository files navigation