📄 Card 70 [M13] — Inadimplência + Agendamento de Negociação

📚 Referência Genius: /controle-inadimplencia + /controle-inadimplencia/agendamentos — "Histórico de negociação + carta de cobrança + cobranças automáticas" + abas "Agendamentos"

🎯 Objetivo

Expandir o módulo Inadimplência (atualmente no Card 20 LOCAL financeiro) com:

• Agendamento de negociação: marcar reunião/ligação com responsável inadimplente
• Acordos de parcelamento: criar plano de pagamento renegociado (divide dívida em N parcelas)
• Carta de cobrança automática (PDF)
• Cobranças automáticas programadas (Job Bull: lembretes + escalonamento)
• Timeline completa do devedor (tentativas, contatos, acordos)
• Workflow: Novo → Em Negociação → Acordado → Quitado → Litígio

📚 Documentação de Referência

• docs/execucao/20-m4-financeiro-unidade.md — Inadimplência já existe
• prisma/schema.prisma — Payment.status OVERDUE

🛠️ Especificação Técnica

Schema Prisma (novo)

model DebtNegotiation {
  id              String   @id @default(cuid())
  code            String   @unique
  branchId        String
  branch          Branch   @relation(fields: [branchId], references: [id])
  studentId       String?
  student         Student? @relation(fields: [studentId], references: [id])
  guardianId      String?
  guardian        Guardian? @relation(fields: [guardianId], references: [id])
  // Origem
  originalPayments String[]                            // IDs das contas em atraso
  originalAmount   Decimal  @db.Decimal(12, 2)
  // Negociação
  status          NegotiationStatus @default(NEW)     // NEW, NEGOTIATING, AGREED, PAID, LITIGATION
  discountPercent Decimal? @db.Decimal(5, 2)
  installments    Int                                 // número de parcelas
  installmentAmount Decimal @db.Decimal(12, 2)
  firstDueDate    DateTime
  frequency       String                              // MONTHLY, WEEKLY
  notes           String?
  // Responsáveis
  negotiatorId    String
  negotiator      User     @relation(fields: [negotiatorId], references: [id])
  // Datas
  openedAt        DateTime @default(now())
  agreedAt        DateTime?
  paidAt          DateTime?
  closedAt        DateTime?
  // Timeline
  events          NegotiationEvent[]
  generatedPayments Payment[]                          // parcelas geradas pelo acordo
}

model NegotiationEvent {
  id              String   @id @default(cuid())
  negotiationId   String
  negotiation     DebtNegotiation @relation(fields: [negotiationId], references: [id])
  type            NegotiationEventType                // CALL, MEETING, EMAIL, WHATSAPP, NOTE, AGREEMENT
  description     String
  scheduledAt     DateTime?
  completedAt     DateTime?
  createdById     String
  createdAt       DateTime @default(now())
}

enum NegotiationStatus { NEW  NEGOTIATING  AGREED  PAID  LITIGATION }
enum NegotiationEventType { CALL  MEETING  EMAIL  WHATSAPP  NOTE  AGREEMENT }

Rotas

• /master/inadimplencia — visão consolidada + abas "Acordos" / "Agendamentos"
• /local/inadimplencia — por filial
• /local/inadimplencia/[negotiationId] — detalhe + timeline + parcelas
• /local/inadimplencia/carta-cobranca/[studentId] — gera PDF da carta

Procedures tRPC (master.inadimplence, local.inadmissence)

• debtorList (lista responsáveis com dívida + total + dias atraso)
• negotiation.create (abre negociação)
• negotiation.scheduleEvent (agenda call/reunião)
• negotiation.completeEvent
• negotiation.agree (formaliza: discount + installments → gera Payment[]s novos marcados como parcelas de acordo)
• negotiation.markPaid
• negotiation.timeline
• generateCollectionLetter (PDF via Puppeteer com dados do devedor + valor + prazo)

Job Bull de cobrança

• inadimplence-reminder: cron diário 09:00 — para cada Payment OVERDUE:
  • 1-7 dias: lembrete gentil por WhatsApp
  • 8-30 dias: e-mail + push + carta
  • 31-60 dias: SMS + chamada agendada
  • 60+ dias: marca LITIGATION + notifica MASTER
• Configurável por filial (turnos, canais, prazos)

✅ Critérios de Aceite

1. Lista de devedores com total + dias atraso + severidade
2. Abrir negociação por responsável (timeline visível)
3. Agendar eventos (call/reunião/WhatsApp) com lembretes
4. Acordo: define desconto + parcelas + 1º vencimento → gera novos Payments
5. Carta de cobrança PDF gerada com dados completos
6. Cobrança automática Job Bull (WhatsApp + e-mail + SMS por dias de atraso)
7. Status: NEW → NEGOTIATING → AGREED → PAID/LITIGATION
8. Build passa + lint OK

🔌 Handoff

• Job inadimplence-reminder no bootstrap
• Integração Card 28 (WhatsApp) e Card 31 (e-mail workflows)

🎯 Próximo

Card 71: Faturas (Agrupamento de Cobranças)

EXECUCAO — 2026-08-15

1. O que foi implementado

DebtNegotiation (ACD-AAAA-NNNN) + NegotiationEvent: debtorList agrupado por guardian com severidade (<7/30/60/60+ dias), acordo gera N parcelas Payment vinculadas (negotiationId), markPaid quita parcelas, carta de cobrança HTML completa (iframe+print). /local/inadimplencia (abas Devedores/Acordos/Agendamentos) + /master (consolidado).

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.