Card 33 [M7] Migração de Dados & Carga Inicial

⚠️ 9 perguntas SEM RESPOSTA (decisoes.md seção "OPERACAO E MIGRAÇÃO"): dados antigos para migrar? volume (qtd alunos)? formato? janela de migração? reset de senhas dos migrados? fotos para migrar? Estes precisam ser respondidos pelo cliente ANTES de executar este card.

🎯 Objetivo

Migrar dados do sistema antigo da ANIK para o GENIOON: alunos, responsáveis, matrículas, histórico de pagamentos, turmas, fotos. Scripts de ETL com validação, janela de migração definida com cliente. Carga inicial das tabelas de domínio (cursos, filiais, configurações). Reset de senhas dos migrados (forçar troca no primeiro login ou enviar por WhatsApp — a confirmar).

📋 Especificação técnica

Scripts (Prisma + Node)

scripts/migrate/01-branches.ts — carga inicial das 10 filiais (nome, CNPJ, endereço, cores)
scripts/migrate/02-courses.ts — cursos (Desenho, Pintura, Inglês, Faculdade do Sucesso, Outros)
scripts/migrate/03-students.ts — alunos + responsáveis + vínculos (StudentGuardian)
scripts/migrate/04-enrollments.ts — matrículas ativas (gera RA: ano + sequencial)
scripts/migrate/05-payments-history.ts — histórico financeiro (somente leitura)
scripts/migrate/06-photos.ts — migra fotos (webcam/S3) — se aplicável
scripts/migrate/validate.ts — relatório de integridade (counts, órfãos, duplicados)

Formatos suportados (a confirmar com cliente)

CSV / Excel export do sistema antigo
Dump SQL (se acessível)
Planilhas Google Sheets fornecidas pela ANIK

Componentes

scripts/migrate/lib/etl.ts — helpers (parse, transform, upsert, dry-run)
scripts/migrate/lib/dedup.ts — deduplicação por CPF/RA/telefone
docs/migracao/PLANO-MIGRACAO.md — janela, rollback, checkpoints

tRPC procedures (masterProcedure)

master.migrate.dryRun — simula import (conta, mostra erros, não grava)
master.migrate.run — executa carga (transacional, com checkpoint)
master.migrate.rollback — desfaz último lote

Schema

Popula modelos existentes: Branch, Course, Student, Guardian, StudentGuardian, Enrollment, Payment, Document
Geração de RA: ano + sequencial (decisão)
Senhas migradas: hash provisório + flag mustResetPassword=true (User)

🎨 UX (processo)

┌─────────────────────────────────────────────────────┐
│  Migração — Painel Master                           │
├─────────────────────────────────────────────────────┤
│  DRY RUN                                             │
│  • 2.450 alunos a importar                          │
│  • 10 filiais (carga inicial)                       │
│  • 4 cursos                                         │
│  • ⚠️ 12 duplicados por CPF (revisar)               │
│  • ⚠️ 8 sem telefone (bloqueia WhatsApp)            │
│                                                      │
│  [Executar carga]  (transacional, com checkpoint)   │
│                                                      │
│  PROGRESSO  ████████░░  82%  (2.010/2.450)          │
│  Checkpoint salvo: 2026-10-09 02:14                 │
└─────────────────────────────────────────────────────┘

Sempre dry-run antes de gravar. Rollback disponível.

🔌 Dependências

Respostas do cliente (9 perguntas pendentes — decisoes.md)
Card 18 (M4): modelo Enrollment + geração de RA
Card 28 (M6): reset de senha por WhatsApp (se adotado)
Cards 22-23 (M5): Branches e vinculação
decisoes.md seção "⚙️ OPERAÇÃO E MIGRAÇÃO" (9 perguntas sem resposta)

📦 Entregáveis

Plano de migração (janela, rollback, checkpoints)
Scripts ETL por entidade (filiais, cursos, alunos, matrículas, pagamentos, fotos)
Carga inicial das tabelas de domínio
Dry-run + relatório de integridade
Deduplicação por CPF/RA/telefone
Reset de senhas dos migrados (forçar troca ou WhatsApp)
Validação pós-migração (counts, órfãos, integridade)

✅ Critérios de aceite

9 perguntas de migração respondidas pelo cliente
Dry-run mostra counts e erros antes de gravar
Carga transacional com checkpoint (retomável)
RA gerado automaticamente (ano + sequencial)
Deduplicação por CPF funciona
Rollback desfaz último lote
Senhas migradas forçam reset no primeiro login
Validação pós-migração sem órfãos/duplicados
Build passa + lint OK

🔗 Links

Trello: https://trello.com/c/rnccd0Rr
Decisões relevantes: decisoes.md seção "⚙️ OPERAÇÃO E MIGRAÇÃO" (9 perguntas pendentes)
Doc anterior: 32-m7-uat.md
Próximo: Card 34 (Treinamento dos Usuários)