📄 Documento de Execução — Card 20: [M4] Financeiro da Unidade

🎯 1. O que foi implementado

O Card 20 entrega o painel financeiro completo para a direção da unidade (LOCAL/SUPERVISOR/MASTER). Cobre fluxo de caixa, inadimplência, geração de cobranças e baixa manual.

Backend — local.financial (7 procedures)

1. financial.dashboard — KPIs do período (mês/ano selecionável): previsto, recebido, pendente, inadimplência (valor + %), com contagens por status. Usa 4 aggregates + 1 groupBy em paralelo.
2. financial.cashflow — Série temporal de recebimentos (PAID) agrupados por dia, por período (WEEK/MONTH/QUARTER). Inclui breakdown por método de pagamento.
3. financial.inadimplencia — Lista pagamentos OVERDUE com dias de atraso calculados, dados do responsável e aluno vinculado. Retorna total, valor acumulado e atraso médio.
4. financial.generateMonthly — Gera cobranças mensais para todos os alunos ativos. Calcula valores (base - desconto - pontualidade), define vencimento por dueDay. Pula cobranças já existentes e matrículas sem responsável financeiro. No Go-Live (M7) vira Job Bull automático dia 1 às 03:00.
5. financial.markPaid — Baixa manual de pagamento com método (PIX/BOLETO/CASH/etc).
6. financial.applyDiscount — Aplica desconto percentual manual com motivo.
7. financial.list — Lista pagamentos com filtros (status, mês, ano) para tabela detalhada.

Frontend — 2 páginas

1. /local/financeiro (REESCRITA) — Dashboard com 4 KPIs coloridos (Previsto/Recebido/Pendente/Inadimplência), gráfico AreaChart (Recharts) de fluxo de caixa 30 dias, distribuição por status, tabela de cobranças do período com botão "Baixar", seletor de mês/ano, e modal "Gerar Cobranças".
2. /local/financeiro/inadimplencia (NOVA) — KPIs de inadimplência (total, quantidade, atraso médio), tabela com severidade colorida por dias de atraso (>30 vermelho, >7 amarelo), ações por pagamento (quitar, aplicar desconto, contato), e modal de desconto.

Decisões do cliente aplicadas (9/9)

✅ Critérios de aceite validados

📁 2. Arquivos criados/modificados

Criados

Modificados

🗄️ 3. Schema do banco (mudanças)

Nenhuma mudança de schema. O model Payment já tinha todos os campos necessários:

• amount, discountAmount, finalAmount, punctualityAmount, lateFeeApplied
• dueDate, dueDay, paidAt, status (PENDING/PAID/OVERDUE/CANCELLED/REFUNDED)
• method (PIX/BOLETO/CREDIT_CARD/DEBIT_CARD/CASH/TRANSFER)
• Campos NFSe: nfseNumber, nfseXmlUrl, nfsePdfUrl

🔌 4. Handoff para o próximo card

Procedures disponíveis

• local.financial.dashboard/cashflow/inadimplencia/list — leituras
• local.financial.generateMonthly/markPaid/applyDiscount — mutations

Pendências para Go-Live (M7)

• Job Bull payment-generator: automação dia 1 às 03:00 (hoje é manual)
• Job Bull payment-reminder: lembretes 3d antes, 1d antes, no dia
• Job Bull overdue-marker: marcar OVERDUE após dueDate+1
• NFSe: integração real (hoje campos existem mas não são preenchidos)
• Conciliação bancária: upload de arquivo retorno CNAB
• Relatórios PDF/Excel: Puppeteer

📋 5. Checklist do Trello

[Entregas] 4/4 (2 diretos + 2 pendências M7)

Fluxo de caixa ✅, Inadimplência ✅, Conciliação ⏳ (M7), Relatórios ⏳ (M7)

[Especificação Técnica] — 7 rotas marcadas ✅

[Validar com Cliente] 9/9 ✅

🚀 6. Deploy DEV

• Build: ✅ local + VPS
• Commit: aee19ba
• VPS: git pull + build + pm2 reload
• Smoke test: HTTP 200 ✅
• URL: https://sistemaescolar.wellka.com.br/local/financeiro

🎯 8. Próximo card

Card 21: [M4] Comunicados & Avisos da Unidade — CRM de comunicados da direção para alunos/pais/professores. Aprovação prévia (decisão cliente), canais (app+email+WhatsApp), e templates.