📊 DRE Financeiro — Flask + MySQL

Demonstrativo de Resultado do Exercício para sub-adquirentes. API REST com cache em memória, breakdowns por produto/canal/parceiro e cálculo automático de impostos (ISS, PIS, COFINS).

---

✨ Funcionalidades

• DRE completo — receitas operacionais, antecipação, deduções fiscais, COGS, lucro bruto
• Breakdowns dinâmicos — por produto (crédito/débito/Pix), canal de captura e parceiro
• Tendência diária — série histórica de TPV, receita e custo por dia
• Cache em memória — TTL configurável, evita consultas repetidas ao banco
• KPIs automáticos — take rate, spread médio, taxa de chargeback, margem bruta
• Filtros por cliente — análise segmentada por parceiro/sub-adquirente

🏗️ Arquitetura

Request → Flask Route → Cache (TTL) → MySQL Query → JSON Response
                ↓ miss              ↑
         _build_*() function ───────┘

Cada endpoint tem sua própria função _build_*() pura — sem closures, fácil de testar. O cache usa dict em memória com timestamp; TTL padrão de 2 minutos.

📡 Endpoints

Método	Rota	Descrição
GET	/api/dre	DRE completo do período
GET	/api/breakdown/produto	Breakdown por produto (crédito/débito/Pix)
GET	/api/breakdown/canal	Breakdown por canal de captura
GET	/api/breakdown/parceiro	Top 50 parceiros por TPV
GET	/api/tendencia	Série diária de TPV e receita
GET	/api/clientes	Lista de clientes disponíveis
POST	/api/cache/flush	Limpa o cache em memória

Parâmetros comuns:

?data_inicio=2024-01-01&data_fim=2024-01-31&customer=NOME_PARCEIRO

🧾 Exemplo de resposta — /api/dre

{
  "periodo": { "inicio": "2024-01-01", "fim": "2024-01-31" },
  "tpv": 4500000.00,
  "qtd": 18432,
  "rec_bruta": 112500.00,
  "deducoes": { "iss": 2250.00, "pis": 731.25, "cofins": 3375.00, "total": 6356.25 },
  "rec_liquida": 106143.75,
  "cogs": {
    "custo_adm": { "credito": 21000.00, "debito": 4500.00, "pix": 900.00, "total": 26400.00 },
    "bandeiras": { "visa": 18000.00, "mc": 13500.00, "elo": 9000.00, "total": 43200.00 },
    "chargebacks": { "perdas": 1350.00, "multas": 450.00, "total": 1800.00 },
    "total": 72000.00
  },
  "lucro_bruto": 34143.75,
  "kpis": {
    "take_rate": 2.359,
    "spread_medio": 1.85,
    "cb_rate": 0.030,
    "margem_bruta": 32.17
  }
}

🛠️ Stack

Camada	Tecnologia
Backend	Python 3.10 + Flask 3.0
Banco de dados	MySQL 8.0
Cache	In-memory dict com TTL
Frontend	HTML + JavaScript (Chart.js)
Servidor de produção	Gunicorn / Waitress

📁 Estrutura

dre/
├── app.py          # Flask — todas as rotas e lógica de DRE
├── db.py           # Abstração de conexão MySQL
├── config.py       # Configurações via variáveis de ambiente
├── templates/
│   └── dre.html    # Dashboard frontend
├── static/
│   └── img/
├── .env.example    # Modelo de configuração
└── start.bat       # Atalho Windows

🚀 Como rodar

pip install Flask PyMySQL python-dotenv
cp .env.example .env   # configure seu banco

python app.py

# Consultar DRE do mês atual:
curl "http://localhost:5000/api/dre"

# Com filtro de período e parceiro:
curl "http://localhost:5000/api/dre?data_inicio=2024-01-01&data_fim=2024-01-31&customer=PARCEIRO_X"

💡 Destaques técnicos

• SQL com CASE WHEN para pivot de métricas em uma única query (evita múltiplos round-trips)
• Cache key por hash MD5 dos parâmetros — colisão zero entre períodos diferentes
• Serializer customizado para Decimal e datetime sem depender de bibliotecas externas
• Cálculo progressivo de ISS/PIS/COFINS sobre receita bruta

---

Desenvolvido por Raquel Daud — LinkedIn · Portfolio