contas-pagamentos

📊 Sistema Financeiro - Robô de Comprovantes v2.0

📋 Visão Geral

Sistema automatizado de processamento de comprovantes financeiros com:

🏗️ Arquitetura Modular (9 Camadas)

1. config.py - Configurações Centralizadas

Responsabilidade: Todas as constantes, credenciais e bancos de dados

Contenido:

Uso:

from config import (
    PASTA_ENTRADA, EMAIL_REMETENTE,
    DB_FORNECEDORES_CATEGORIA
)

Por que separado?

2. models.py - Estruturas de Dados (Dataclasses)

Responsabilidade: Define todas as estruturas com type hints

Classes principais:

Enums:

Uso:

from models import Pagamento, Comprovante

pagamento = Pagamento(
    nome="João Silva",
    valor=1000.00,
    categoria="12201 - Salários"
)

Por que separado?

3. ocr_processor.py - Extração de Dados

Responsabilidade: Ler PDFs, aplicar OCR, extrair texto e dados

Classes principais:

Uso:

processor = OCRProcessor()
comprovante = processor.processar_comprovante("comprovante.pdf")
dados = ExtratorDados.extrair_todos_dados(comprovante.texto_extraido)

Por que separado?

4. data_classifier.py - Auto-classificação

Responsabilidade: Classifica fornecedores por CNPJ/nome/heurísticas

Classes principais:

Estratégia de classificação (em ordem):

  1. CNPJ exato (confiança 1.0)
  2. Nome parcial (confiança 0.95)
  3. Heurísticas por palavra-chave (0.75)
  4. Fallback para “A CLASSIFICAR” (0.0)

Uso:

clf = DataClassifier()
classificacao = clf.auto_classificar_fornecedor(
    "TEXTIL FAVERO LTDA",
    "08.883.683/0001-84"
)
# → Classificacao(responsavel="COMPRAS", categoria="12101 - Tecidos")

Por que separado?

5. database.py - Persistência SQLite

Responsabilidade: Todas as operações no banco de dados

Classes principais:

Schema:

Uso:

db = DatabaseManager()
db.criar_schema()
id_pag = db.inserir_pagamento(pagamento)

pagamentos, total = db.listar_pagamentos(
    filtros=FiltrosPagamento(categoria="A CLASSIFICAR"),
    limite=100
)

Por que separado?

6. email_handler.py - Comunicação

Responsabilidade: Enviar emails via SMTP/Outlook

Classes principais:

Uso:

email = EmailHandler()
email.enviar_resumo_processamento(
    total_comprovantes=5,
    total_pagamentos=10,
    total_valor=5000.00,
    sucesso=5,
    erros=0,
    tempo_segundos=45.2
)

Por que separado?

7. file_organizer.py - Gerenciamento de Arquivos

Responsabilidade: Move/copia/organiza arquivos

Classes principais:

Estrutura de pastas:

ENTRADA/
  ├─ comprovante1.pdf
  └─ comprovante2.pdf

SAIDA_ORGANIZADA/
  ├─ Filial_Barra/2026/01_Janeiro/
  │  ├─ comp1.pdf
  │  └─ comp2.pdf
  └─ Filial_SDB/2026/01_Janeiro/

PROCESSADOS/
  ├─ SUCESSO/2026/01_Janeiro/
  └─ ERRO/2026/01_Janeiro/

backup em Z:\01-Administrativo\02-Financeiro\04-Comprovantes/

Por que separado?

8. interface.py - GUI Tkinter

Responsabilidade: Interface gráfica do usuário

Classe principal:

Features:

Uso:

root = tk.Tk()
interface = Interface(root)
interface.callback_processar = algumas_funcao
interface.adicionar_log("Mensagem ao usuário")
interface.atualizar_progresso(50, 100)  # 50%
root.mainloop()

Por que separado?

9. main.py - Orquestrador

Responsabilidade: Ponto de entrada e orquestração

Classe principal:

Pipeline (dentro de processar_comprovantes()):

  1. Lista arquivos em ENTRADA/
  2. Para cada arquivo:
    • Extrai texto (OCR/PDF)
    • Extrai dados (nome, valor, CNPJ)
    • Classifica (fornecedor/colaborador)
    • Insere em DB
    • Move para SAIDA_ORGANIZADA/
    • Faz backup em rede
  3. Envia email com resumo

Uso:

if __name__ == "__main__":
    sistema = SistemaFinanceiro()
    sistema.executar()  # Inicia GUI

Por que separado?

🚀 Como Usar

Instalação

cd "c:\Users\Roberto\Desktop\CONTAS A PAGAR\PROJETOS\FINANCEIRO"

# Criar virtualenv (opcional)
python -m venv venv
venv\Scripts\activate

# Instalar dependências
pip install pypdf pytesseract pdf2image pillow openpyxl beautifulsoup4

Começar

python main.py

Fluxo Normal

  1. Coloque comprovantes em ENTRADA/
  2. Clique “Processar Comprovantes” na interface
  3. Sistema processa e organiza automaticamente
  4. Verifique resultados em SAIDA_ORGANIZADA/
  5. Consulte dados na aba “Consultas”

📊 Diagrama de Fluxo

[main.py] inicia
    ↓
[SistemaFinanceiro.__init__()]
    ├─ OCRProcessor()
    ├─ DatabaseManager()
    ├─ DataClassifier()
    ├─ EmailHandler()
    ├─ FileOrganizer()
    └─ Interface()
    ↓
[Interface.mainloop()] ← GUI aguarda
    ↓
[Usuário clica "Processar"]
    ↓
[SistemaFinanceiro.processar_comprovantes()]
    ├─ FileOrganizer.listar_arquivos_entrada()
    └─ Para cada arquivo:
        ├─ OCRProcessor.processar_comprovante()
        │  └─ ExtratorDados.extrair_*
        ├─ DataClassifier.classificar_pagamento_completo()
        ├─ DatabaseManager.inserir_*
        ├─ FileOrganizer.organizar_comprovante()
        ├─ FileOrganizer.fazer_backup_rede()
        −─ Interface.atualizar_progresso()
        └─ EmailHandler.enviar_resumo_processamento()

🔄 Melhorias Implementadas (vs v14 Monolítica)

Aspecto v14 (Monolítico) v2.0 (Modular)
Arquivos 1 gigante (~1500 linhas) 9 módulos especializados
Testabilidade Impossível ✓ Mock individual
Manutenção Difícil ✓ Fácil (responsabilidade única)
Reutilização Não ✓ Modules independentes
Performance OK ✓ Índices no DB
Type Hints Não ✓ Completo
Documentação Inexistente ✓ Docstrings
Escalabilidade Limitada ✓ Web backend fácil
CI/CD Impossível ✓ Cada módulo testável

🛠️ Próximos Passos Sugeridos

  1. Testes Unitários 
    # test_classifier.py
def test_auto_classificar_por_cnpj():
    clf = DataClassifier()
    resultado = clf.auto_classificar_fornecedor("...", "08.883.683/0001-84")
    assert resultado.responsavel == "COMPRAS"
  2. Logging de Produção 
    import logging
logger = logging.getLogger(__name__)
logger.info("Comprovante processado")
  3. Web API (FastAPI) 
    @app.post("/processar")
def processar_via_api(arquivo: UploadFile):
    ... # Reutiliza SistemaFinanceiro
  4. Migração para PostgreSQL
    • Trocar apenas database.py
    • Resto do código fica igual
  5. Dashboard Interativo
    • Usar React/Vue ao invés de Tkinter
    • API fica a mesma

📝 Notas de Desenvolvimento

📞 Suporte

Qualquer dúvida sobre arquitetura ou funcionamento, consulte os docstrings em cada módulo.

v2.0 - Reestruturação Completa Transformando monolítico em arquitetura modular