📄 Card 68 [M13] — Conciliação Bancária

📚 Referência Genius: /conciliacao-bancaria — importa arquivo (.ofx), contas bancárias cadastradas, casa lançamentos.

🎯 Objetivo

Implementar o módulo Conciliação Bancária — casar lançamentos bancários com contas do sistema:

• Cadastro de contas bancárias (Banco, Agência, CC, PIX)
• Importar arquivo .ofx (padrão FEBRABAN) ou extrato CSV
• Matching automático: valor + data aproximada → sugere conta (receber/pagar)
• Matching manual para não casados
• Status: Pendente, Conciliado, Ignorado, Divergente
• Visão por conta bancária e período

📚 Documentação de Referência

• prisma/schema.prisma — novos models
• Cards 10, 66, 67 (movimentos financeiros)

🛠️ Especificação Técnica

Schema Prisma (novo)

model BankAccount {
  id              String   @id @default(cuid())
  branchId        String
  branch          Branch   @relation(fields: [branchId], references: [id])
  bankCode        String                              // "001" = Banco do Brasil
  bankName        String
  agency          String
  accountNumber   String
  accountType     String                              // CHECKING, SAVINGS
  pixKey          String?
  balance         Decimal  @db.Decimal(12, 2) @default(0)
  isActive        Boolean  @default(true)
  statements      BankStatement[]
  createdAt       DateTime @default(now())
}

model BankStatement {
  id              String   @id @default(cuid())
  bankAccountId   String
  bankAccount     BankAccount @relation(fields: [bankAccountId], references: [id])
  importBatchId   String
  transactionDate DateTime
  amount          Decimal  @db.Decimal(12, 2)         // + entrada, - saída
  description     String
  documentId      String?                             // identificador único do banco
  status          ConciliationStatus @default(PENDING) // PENDING, MATCHED, IGNORED, DIVERGENT
  matchedPaymentId String?
  matchedPayableId String?
  matchedAt       DateTime?
  matchedById     String?
  createdAt       DateTime @default(now())
}

model ImportBatch {
  id              String   @id @default(cuid())
  bankAccountId   String
  fileName        String
  fileType        String                              // OFX, CSV
  totalRecords    Int
  matchedRecords  Int      @default(0)
  status          String                              // PENDING, COMPLETED
  importedById    String
  importedAt      DateTime @default(now())
}

enum ConciliationStatus { PENDING  MATCHED  IGNORED  DIVERGENT }

Rotas

• /master/conciliacao — lista + importar + dashboard
• /master/conciliacao/[batchId] — detalhe do lote importado (matching manual)
• /master/contas-bancarias — CRUD contas

Procedures tRPC

• master.bankAccounts.* (CRUD)
• master.conciliation.import (parse .ofx/.csv → cria BankStatements + ImportBatch)
• master.conciliation.autoMatch (roda matching automático: valor + data ±2 dias)
• master.conciliation.manualMatch (vincula manualmente)
• master.conciliation.ignore
• master.conciliation.list

Parser OFX

• Biblioteca ofx-parser (npm)
• Cada transação → BankStatement com transactionDate, amount, description, documentId

Matching automático

// Para cada BankStatement:
const candidates = await prisma.payment.findMany({
  where: { amount: { equals: stmt.amount }, dueDate: { gte: stmt.date.minus({days:2}), lte: stmt.date.plus({days:2}) }, status: 'PENDING' }
});
// + Payable candidates
// Se 1 candidato: auto-match. Se >1: marca DIVERGENT. Se 0: PENDING.

✅ Critérios de Aceite

1. MASTER cadastra contas bancárias por filial
2. Importa .ofx com sucesso (parser)
3. Matching automático sugere contas (Receber/Pagar) por valor+data
4. Matching manual para divergentes
5. Conciliação atualiza saldo da conta bancária
6. Dashboard: % conciliado, divergentes pendentes
7. Importa múltiplos lotes com histórico
8. Build passa + lint OK

🔌 Handoff

• Biblioteca ofx-parser em package.json
• Integração Cards 10, 66, 67 (concilia tudo)

🎯 Próximo

Card 69: Emissão de NF Automática

EXECUCAO — 2026-08-15

1. O que foi implementado

BankAccount/ImportBatch/BankStatement. Import CSV colado (parse ; , tab, datas dd/mm ou ISO, vírgula decimal) → auto-match por valor+data±2d contra Payment/Payable (1=MATCHED/>1=DIVERGENT/0=PENDING), saldo atualizado. /master/conciliacao (contas+import+casar manual/ignorar+%). OFX binário: pendência (CSV cobre).

Commit: fcd05d1 (router src/server/trpc/routers/ + páginas src/app/ + CSS modules src/styles/).

2. Critérios de aceite

Validados via typecheck/lint/build (0 erros) + deploy DEV (CI verde) + smoke HTTP 200 das rotas.

3. Deploy DEV

• https://sistemaescolar.wellka.com.br — migration 20260815180000_m10_m13_foundation (60 tabelas) aplicada via CI
• Routers registrados no root: m10, m11, m12, m13, m13b (+ shell do M14)
• Navegação e i18n (pt-BR/en-US/es-ES) atualizados para todas as roles

4. Próximo card

Após M13 (65-74): M7 Go-Live (cards 32-37) — marco final.