📄 Card 66 [M13] — Contas a Pagar + Fornecedores

📚 Referência Genius: /conta-pagar — "Controle geral de pagamentos e recebimentos" + /fornecedor 🔥 GENIOON hoje só tem Contas a Receber (mensalidades). Falta a Pagar (aluguel, salários, fornecedores).

🎯 Objetivo

Implementar o módulo Contas a Pagar + cadastro de Fornecedores:

• Cadastro de fornecedores (CNPJ, contato, formas pagamento, categorias)
• Lançamento de contas a pagar (despesas fixas e variáveis)
• Categorias e subcategorias (Aluguel, Salários, Material, Marketing, Impostos)
• Recorrência (mensal, semanal, anual)
• Baixa manual + importar (.ofx do banco — integração Card 68)
• Status: Pendente, Pago, Cancelado, Atrasado
• Fluxo de caixa consolidado (Receitas − Despesas)

📚 Documentação de Referência

• prisma/schema.prisma — Payment (receber); novo model Payable
• docs/execucao/20-m4-financeiro-unidade.md — base financeiro LOCAL

🛠️ Especificação Técnica

Schema Prisma (novo)

model Supplier {
  id              String   @id @default(cuid())
  name            String
  legalName       String?
  cnpj            String?  @unique
  email           String?
  phone           String?
  categoryId      String?
  category        ExpenseCategory? @relation(fields: [categoryId], references: [id])
  paymentMethods  String[]                           // PIX, BOLETO, TRANSFER
  bankInfo        Json?
  notes           String?
  branchId        String?                             // null = global (todos pagam)
  payables        Payable[]
  createdAt       DateTime @default(now())
}

model ExpenseCategory {
  id              String   @id @default(cuid())
  name            String                              // "Aluguel", "Salários"
  parentId        String?                             // subcategoria
  parent          ExpenseCategory? @relation("CatTree", fields: [parentId], references: [id])
  children        ExpenseCategory[] @relation("CatTree")
  color           String?
  isSystemDefault Boolean  @default(false)
}

model Payable {
  id              String   @id @default(cuid())
  code            String   @unique                   // "PG-2026-0001"
  description     String
  supplierId      String?
  supplier        Supplier? @relation(fields: [supplierId], references: [id])
  branchId        String
  branch          Branch   @relation(fields: [branchId], references: [id])
  categoryId      String?
  category        ExpenseCategory? @relation(fields: [categoryId], references: [id])
  amount          Decimal  @db.Decimal(12, 2)
  dueDate         DateTime
  paidAt          DateTime?
  paymentMethod   String?                             // PIX, BOLETO, TRANSFER, CASH, CARD
  status          PayableStatus @default(PENDING)    // PENDING, PAID, CANCELLED, OVERDUE
  isRecurring     Boolean  @default(false)
  recurrenceFreq  String?                             // MONTHLY, WEEKLY, YEARLY
  recurrenceEnd   DateTime?
  notes           String?
  attachments     String[]                            // S3 (nota fiscal, recibo)
  createdBy       String
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}

enum PayableStatus { PENDING  PAID  CANCELLED  OVERDUE }

Rotas

• /master/contas-pagar — lista + dashboard
• /local/contas-pagar — por filial
• /master/fornecedores — CRUD
• /master/categorias-despesa — admin categorias

Procedures tRPC (master.payables, local.payables, master.suppliers, master.expenseCategories)

• CRUD completo para fornecedores, categorias, contas a pagar
• pay (baixa — marca PAID + paidAt + paymentMethod)
• cancel
• dashboard (total pendente, pago, atrasado por período)
• recurring.generateNext (Job Bull mensal gera contas recorrentes)

Recorrência

• Job Bull payables-recurring-generator (diário 02:00): para cada Payable com isRecurring=true, gera próxima instância baseado em recurrenceFreq

✅ Critérios de Aceite

1. MASTER cadastra fornecedores + categorias (com subcategorias)
2. LOCAL lança contas a pagar por filial
3. Recorrência gera próxima conta automaticamente
4. Baixa manual com método de pagamento
5. Dashboard: total pendente/pago/atrasado por período e categoria
6. Relatório: despesas por categoria (pie chart)
7. Fluxo de caixa consolidado (Receber − Pagar)
8. Anexos (NF, recibo) por conta
9. Build passa + lint OK

🔌 Handoff

• Job payables-recurring-generator no bootstrap
• Integração Card 67 (Caixa Físico) e Card 68 (Conciliação)

🎯 Próximo

Card 67: Controle de Caixa Físico

EXECUCAO — 2026-08-15

1. O que foi implementado

Payable (PG-AAAA-NNNN) + ExpenseCategory (subcategorias) + Supplier compartilhado com Compras. /local/contas-pagar (KPIs+pie por categoria Recharts+baixa com método) e /master/contas-pagar (consolidado+gerar recorrentes+categorias). recurring.generateNext (MONTHLY/WEEKLY/YEARLY sem duplicar). OVERDUE calculado em query.

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.