📄 Card 59 [M11] — Implantação de Unidades (Wizard Multi-Etapa)

📚 Referência SULTS: https://www.sults.com.br/produtos/implantacao-de-unidades Gerenciamento de projetos de abertura de novas unidades. Cronograma Gantt, dependências, templates por tipo (loja/quiosque), NPS do franqueado 30/60/90 dias. Adaptação escolar: wizard padronizado para abrir novas filiais ANIK (quer crescer 10→30 unidades).

🎯 Objetivo

Criar o módulo Implantação de Unidades — wizard estruturado de abertura de nova filial:

Templates por tipo (Escola padrão, Posto avançado, Quiosque de atendimento)
Cronograma com fases e tarefas (versão simplificada do SULTS — não 120 passos)
Upload obrigatório de evidências (foto da obra, alvará, contrato de aluguel)
Checklists por fase (integração com Card 51)
Treinamento obrigatório da equipe (integração Card 53/55 — bloqueia inauguração se não certificado)
Vistoria final via Checklist (Card 51)
NPS do novo franqueado em 30/60/90 dias (integração Card 49)
Acompanhamento de portfólio (múltiplas inaugurações simultâneas)

📚 Documentação de Referência

prisma/schema.prisma — novos models
Card 23 (criar filial) — base já existe
Card 51 (Checklist) — integração

🛠️ Especificação Técnica

Schema Prisma (novo)

model ImplementationProject {
  id              String   @id @default(cuid())
  branchId        String                             // filial em implantação
  branch          Branch   @relation(fields: [branchId], references: [id])
  templateId      String
  template        ImplementationTemplate @relation(fields: [templateId], references: [id])
  status          ImplStatus @default(PLANNING)      // PLANNING, IN_PROGRESS, AUDIT, COMPLETED, CANCELLED
  startDate       DateTime
  forecastOpenDate DateTime
  actualOpenDate  DateTime?
  phases          ImplementationPhase[]
  managerId       String                             // responsável da matriz
  manager         User     @relation(fields: [managerId], references: [id])
  capex           Decimal? @db.Decimal(12, 2)
  notes           String?
  createdAt       DateTime @default(now())
}

model ImplementationTemplate {
  id              String   @id @default(cuid())
  name            String                             // "Escola Padrão", "Quiosque", "Posto Avançado"
  phases          ImplementationPhaseTemplate[]
}

model ImplementationPhaseTemplate {
  id              String   @id @default(cuid())
  templateId      String
  template        ImplementationTemplate @relation(fields: [templateId], references: [id])
  name            String                             // "Documentação", "Obra", "Contratação", "Treinamento"
  order           Int
  defaultDurationDays Int
  tasks           ImplementationTaskTemplate[]
}

model ImplementationTaskTemplate {
  id              String   @id @default(cuid())
  phaseId         String
  phase           ImplementationPhaseTemplate @relation(fields: [phaseId], references: [id])
  name            String
  description     String?
  requiresEvidence Boolean @default(false)           // exije anexo
  requiresCertification Boolean @default(false)      // exige certificado (Card 55)
  order           Int
}

model ImplementationPhase {
  id              String   @id @default(cuid())
  projectId       String
  project         ImplementationProject @relation(fields: [projectId], references: [id])
  templatePhaseId String
  name            String
  order           Int
  startDate       DateTime?
  endDate         DateTime?
  progressPct     Int      @default(0)
  tasks           ImplementationTask[]
}

model ImplementationTask {
  id              String   @id @default(cuid())
  phaseId         String
  phase           ImplementationPhase @relation(fields: [phaseId], references: [id])
  templateTaskId  String?
  name            String
  assignedToId    String?
  status          ImplTaskStatus @default(PENDING)  // PENDING, IN_PROGRESS, DONE, BLOCKED
  evidenceUrls    String[]                           // anexos obrigatórios
  dueDate         DateTime?
  completedAt     DateTime?
  order           Int
}

enum ImplStatus { PLANNING  IN_PROGRESS  AUDIT  COMPLETED  CANCELLED }
enum ImplTaskStatus { PENDING  IN_PROGRESS  DONE  BLOCKED }

Rotas (page.tsx)

/master/implantacao — portfólio (múltiplas inaugurações)
/master/implantacao/[projectId] — Gantt simplificado + tarefas + evidências
/master/implantacao/templates — admin templates

Procedures tRPC

master.impl.templates.* (CRUD)
master.impl.projects.create (a partir de template + nova filial)
master.impl.projects.update / progress
master.impl.tasks.updateStatus / uploadEvidence
master.impl.dashboard (portfólio agregado)

Bloqueio de inauguração

Antes de marcar actualOpenDate, valida:
- Todos os checklists de fase aprovados (Card 51)
- Toda equipe certificada (Card 55)
- Tarefas com requiresEvidence têm anexos
- Vistoria final aprovada
Se bloqueado → alerta + lista do que falta

✅ Critérios de Aceite

MASTER cria projeto a partir de template (3+ tipos)
Cronograma simplificado (fases + tarefas)
Upload obrigatório de evidências
Bloqueio de inauguração se pendências
NPS automático em 30/60/90 dias pós-inauguração (Card 49)
Dashboard portfólio (múltiplas inaugurações)
Integração com Cards 51 (checklists), 53 (treinamento), 55 (certificações)
Build passa + lint OK

🔌 Handoff

Job impl-post-open-nps agenda NPS 30/60/90
Templates default (seed): Escola Padrão, Posto Avançado, Quiosque

🎯 Próximo

Card 60: Compras & Marketplace B2B

EXECUCAO — 2026-08-15

1. O que foi implementado

ImplementationTemplate/Phases/Tasks + instanciação de projeto. /master/implantacao (portfólio+criar+builder templates) e [id] (timeline fases/tasks, evidências obrigatórias, requiresCertification badge). Registrar inauguração VALIDA bloqueios e lista pendências (retorna missing[] sem lançar erro).

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.