📄 Card 64 [M12] — CRM Expansão (Captação de Franquias)

📚 Referência SULTS: https://www.sults.com.br/produtos/expansao CRM B2B para gerenciar funil completo de prospecção e venda de novas unidades/franquias (diferente do Card 30 que captura alunos). Fluxo pós-venda integrado: quando fecha, dados migram nativamente pra Implantação (Card 59).

🎯 Objetivo

Criar o CRM Expansão — funil de captação de novos franqueados ANIK (não alunos, mas investidores que querem abrir filial):

• Funis e etapas personalizáveis (primeiro contato → COF → proposta → assinatura)
• Checkpoints e qualificação (critérios pra avançar)
• Captação automática (formulários landing page + importação base)
• Gestão de candidatos com histórico + atividades
• Controle legal COF (Circular de Oferta de Franquia — Lei do Franchising)
• Dashboards: pipeline value, tempo médio fechamento, taxa conversão
• Sync pós-venda: candidato vencido → vira filial automaticamente (Card 23 + Implantação Card 59)

📚 Documentação de Referência

• prisma/schema.prisma — novo FranchiseLead (distinto do Lead do Card 30 que é de alunos)
• Card 30 — referência de Kanban
• Card 59 — Implantação (sync pós-venda)

🛠️ Especificação Técnica

Schema Prisma (novo)

model FranchiseLead {
  id              String   @id @default(cuid())
  name            String
  email           String
  phone           String
  city            String?
  state           String?
  budget          Decimal? @db.Decimal(12, 2)         // investimento disponível
  source          String?                             // "Instagram", "Indicação", "Feira"
  // Funil
  stage           FranchiseStage @default(NEW)        // NEW, CONTACTED, QUALIFIED, COF_SENT, PROPOSAL, NEGOTIATION, WON, LOST
  lostReason      String?
  // Atribuição
  assignedToId    String?
  assignedTo      User?    @relation(fields: [assignedToId], references: [id])
  // Contexto
  notes           String?
  activities      FranchiseActivity[]
  // Conversão
  wonAt           DateTime?
  convertedBranchId String?                           // filial criada (se WON)
  cofSentAt       DateTime?                           // Circular de Oferta enviada
  cofAcceptedAt   DateTime?
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
}

model FranchiseActivity {
  id              String   @id @default(cuid())
  leadId          String
  lead            FranchiseLead @relation(fields: [leadId], references: [id])
  type            ActivityType                       // CALL, EMAIL, MEETING, NOTE
  description     String
  scheduledAt     DateTime?
  completedAt     DateTime?
  createdById     String
  createdAt       DateTime @default(now())
}

enum FranchiseStage { NEW  CONTACTED  QUALIFIED  COF_SENT  PROPOSAL  NEGOTIATION  WON  LOST }
enum ActivityType { CALL  EMAIL  MEETING  NOTE }

Rotas (page.tsx)

• /master/expansao — Kanban (estilo Card 30) + dashboard
• /master/expansao/[leadId] — detalhe + atividades + conversão
• /master/expansao/dashboard — KPIs (pipeline value, conversão, tempo médio)

Procedures tRPC (master.expansion.*)

• leads.list (Kanban filtros)
• leads.create / update / moveStage / lose
• leads.activities.* (CRUD)
• leads.dashboard
• leads.convertToBranch (sync pós-venda):
  • Cria Branch (Card 23)
  • Cria ImplementationProject (Card 59)
  • Cria User franqueado (Card 25)
  • Atualiza lead stage=WON, wonAt, convertedBranchId

Controle COF (Lei do Franchising)

• Checklist obrigatório: COF enviada ≥ 10 dias antes da assinatura
• Validação: não permite mover pra PROPOSAL sem cofSentAt ou se < 10 dias
• Documento COF armazenado no Disco Virtual (Card 45)

✅ Critérios de Aceite

1. MASTER cadastra leads de franquia + funil Kanban
2. Atividades (calls/emails/reuniões) registradas
3. Controle COF (validação Lei do Franchising)
4. Sync pós-venda: lead WON → cria Branch + Implantação + User
5. Dashboards (pipeline value, conversão, tempo médio)
6. Importação CSV de leads
7. Build passa + lint OK

🔌 Handoff

• Procedimento convertToBranch orquestra Cards 23/25/59
• Integração com Card 30 (CRM alunos) — schemas distintos
• Job franchise-followup (após N dias sem contato → notifica)

🎯 Próximo

Após M12 (cards 44-64) concluído → M7 Go-Live (cards 32-37)

EXECUCAO — 2026-08-15

1. O que foi implementado

FranchiseLead/Activity: Kanban 8 estágios em /master/expansao com KPIs (pipeline value/conversão/tempo médio). VALIDAÇÃO COF Lei 13.966: mover p/ PROPOSAL exige cofSentAt ≥10 dias. convertToBranch cria Branch em transação e marca WON. Atividades (call/email/meeting/nota) com agendamento.

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.