Prism DRE System — Documentação Técnica

Sistema financeiro da Brave Educação para importação de extratos OFX, classificação de lançamentos e geração de DRE por unidade/mês. Desenvolvido em Next.js 14 + Prisma + PostgreSQL (Neon), hospedado na Vercel com deploy automático via GitHub.

---

Stack

• Next.js 14 (App Router, full-stack — páginas e APIs no mesmo projeto)
• Prisma ORM + PostgreSQL (Neon free tier, sa-east-1)
• Recharts para gráficos
• TypeScript strict
• Vercel para deploy (build: prisma generate && prisma db push && next build)

Variáveis de ambiente (Vercel)

DATABASE_URL=   # Neon connection pooling URL
DIRECT_URL=     # Neon direct URL (para migrations)
ANTHROPIC_API_KEY=  # Claude API (assistente IA na página AI)

---

Estrutura de arquivos

financeiro/
├── prisma/
│   └── schema.prisma          # Modelos do banco
├── src/
│   ├── app/
│   │   ├── layout.tsx         # Title: "Prism DRE System", favicon losango amarelo
│   │   ├── page.tsx           # Redirect para /dashboard
│   │   ├── dashboard/         # Visão geral com métricas e gráfico DRE
│   │   ├── dre/               # DRE detalhada por mês/unidade
│   │   ├── lancamentos/       # Importação OFX + classificação (página principal)
│   │   ├── plano-de-contas/   # CRUD do plano de contas
│   │   ├── saldo/             # Evolução do saldo bancário
│   │   ├── unidades/          # Cadastro de unidades e contas bancárias
│   │   └── api/
│   │       ├── accounts/      # CRUD contas do plano (GET, POST, PUT, DELETE)
│   │       ├── classify/
│   │       │   └── suggest/   # POST — sugestões do classificador inteligente
│   │       ├── dre/           # GET — cálculo DRE agregado
│   │       ├── ofx/
│   │       │   ├── route.ts   # POST — salva lançamentos OFX em lote
│   │       │   └── parse/     # POST — parseia arquivo OFX (preview)
│   │       ├── saldo/         # GET — snapshots de saldo por conta bancária
│   │       ├── transactions/  # GET lista, PUT classifica, DELETE remove
│   │       └── units/         # GET unidades com bankAccounts aninhados
│   ├── components/
│   │   ├── Shell.tsx          # Layout (topbar "Prism" + sidebar com nav)
│   │   ├── AccountCombobox.tsx# Combobox buscável para seleção de conta do plano
│   │   └── AIAssistant.tsx    # Assistente IA (Claude API)
│   └── lib/
│       ├── prisma.ts          # PrismaClient singleton + seed de unidades/bancos/conta neutra
│       ├── ofx-parser.ts      # Parser OFX (transações, saldo, banco)
│       ├── dre.ts             # Cálculo do DRE (calcDRE, MONTH_NAMES)
│       └── classifier.ts      # tokenize() + jaccardSimilarity() para sugestões
└── src/app/icon.svg           # Favicon: losango amarelo (#eaca2d)

---

Banco de dados (schema.prisma)

Modelos

Unit — Unidades do negócio (MATRIZ, CICERO, CIPO, NOVA SOURE, FERNANDA)

• id, name (unique)
• Relações: bankAccounts[], transactions[]

BankAccount — Contas bancárias vinculadas a uma unidade

• id, name, unitId, initialBalance (Float, default 0)
• ofxBankId String? — identificador OFX (BANKID ou ORG do <FI>)
• ofxAcctId String? — número da conta OFX (ACCTID)
• Usado para auto-identificar o banco ao importar OFX

Account — Plano de contas

• id, code (unique, ex: "3.1.1"), name, type, dreGroup, active
• Tipos: RECEITA, DESPESA, ATIVO, PASSIVO, NEUTRO
• dreGroup controla onde aparece no DRE
• Conta especial: 9.9.01 — Transferência entre Contas (type=NEUTRO) — ao classificar, exibe seletores de unidade/conta destino e cria contrapartida automaticamente; aparece na DRE como seção informativa sem contabilizar

Transaction — Lançamentos financeiros

• id, date, description, amount, memo?, fitid? (unique — previne duplicatas OFX)
• accountId? — conta do plano (null = não classificado, não entra no DRE)
• unitId?, bankAccountId?
• transferToUnitId?, transferToBankAccountId? — preenchidos quando é saída de transferência; a contrapartida de entrada é criada automaticamente com fitid + '_entrada'
• month, year — índices para filtro

BalanceSnapshot — Saldos capturados via OFX

• id, bankAccountId, date, balance
• @@unique([bankAccountId, date]) — um snapshot por conta por dia
• Populado por: linhas isBalance do OFX + bloco <LEDGERBAL>

Seed automático (prisma.ts)

Ao iniciar, seedUnits() cria as 5 unidades e seus bancos se não existirem. seedTransferAccount() garante a conta 9.9.01.

Unidades e bancos pré-configurados:

MATRIZ:      ITAU MATRIZ, BRADESCO MATRIZ, BNB MATRIZ, BB MATRIZ
CICERO:      ITAU CICERO, BRADESCO CICERO
CIPO:        ITAU CIPO, BRADESCO CIPO
NOVA SOURE:  ITAU NOVA SOURE, CAIXA NOVA SOURE
FERNANDA:    ITAU FERNANDA, BRADESCO FERNANDA, BNB FERNANDA

---

Funcionalidades principais

Importação OFX (/lancamentos)

Fluxo:

1. Usuário arrasta/seleciona arquivo .OFX
2. POST /api/ofx/parse parseia o arquivo:
   • Detecta a conta bancária primeiro, depois verifica duplicatas de fitid escopadas à mesma conta — evita falsos positivos entre bancos diferentes
   • Extrai <FI><ORG> e <BANKACCTFROM> para identificar o banco
   • Extrai <LEDGERBAL> (saldo final)
   • Extrai todas as <STMTTRN> — marca isBalance=true se TRNTYPE=BALANCE ou memo começa com "SALDO"
3. Preview é exibido — linhas isBalance aparecem travadas (sem combobox)
4. Classificador inteligente roda em background (POST /api/classify/suggest) e abre painel flutuante com sugestões
5. Analista revisa, aceita/nega por linha ou em lote, pode arrastar o painel pela tela
6. POST /api/ofx salva em lote:
   • createMany({ skipDuplicates: true }) — uma query para todas as transações
   • Salva linhas isBalance como BalanceSnapshot diários
   • Salva LEDGERBAL como BalanceSnapshot
   • Atualiza ofxBankId/ofxAcctId na conta bancária (primeira vez)

This is the beginning of the README. Read the rest at the original. Read the full README ↗