Onboarding de Escolas — SSOT

Última atualização: 2026-04-16
Escopo: Fluxo completo de onboarding de uma escola na plataforma OLP, desde a geração do link de cadastro até a conclusão do onboarding administrativo.

Visão Geral

O onboarding é um processo de 9 etapas que leva uma escola do primeiro contato até a operação completa na plataforma:

text

Link de Cadastro → Formulário → Notificação Admin → Gestão Cadastro
→ Ativação Assinatura → Liberação de Acessos → Importação de Alunos
→ Criação de Turmas → Onboarding Completo

Etapas

Etapa 1 — Geração do Link de Cadastro (Admin)

Fluxo: Admin → Seção Escola → Gera token → Link limpo → Envia para escola

Aspecto	Detalhe
Edge Function	`cadastro-escola-publica` (action `generate_link`)
Auth	`extractAuthenticatedUser` + `principal_role === 'administrador'`
Client Supabase	`createSupabaseSystem()` (gera token sem RLS)
Componente	`src/components/admin-escola/`
Tabela	`cadastro_tokens` (tipo, token, escola_id, expira_em)
Rate Limit	20 tokens/min por admin
Log	`cadastro.generate_link`

Token: UUID v4, expira em 7 dias, uso único (usado = false).

Link gerado: https://olp.digital/cadastro/{token}

Etapa 2 — Formulário de Cadastro (Escola)

Fluxo: Escola recebe link → Valida token → Preenche dados → Envia → Token revogado → Cadastro criado

Aspecto	Detalhe
Edge Function	`cadastro-escola-publica` (actions `validate_token`, `complete_signup`)
Auth	Nenhuma (público)
Client Supabase	`createSupabaseSystem()` (cadastro pré-auth)
Componente	`src/pages/cadastro/CadastroCompletoPage.tsx`
Tabelas	`escolas`, `endereco_escola`, `cadastro_tokens`
Rate Limit	10 signups/hora por IP
Log	`escola.signup_create`

Validações:

Unicidade de CNPJ e nome da escola (verificada antes do insert)
Token válido, não expirado, não usado
Dados obrigatórios: nome, CNPJ, telefone, email, tipo

Pós-cadastro:

Token marcado como usado = true
Escola criada com status = 'em_analise'
Endereço salvo em endereco_escola
Rollback parcial em caso de erro (delete escola + endereço)

Etapa 3 — Notificação ao Admin + Navegação

Fluxo: Admin recebe notificação → Navega para cadastro da escola

Aspecto	Detalhe
Mecanismo	Notificação push via ntfy (se configurado)
Navegação	Admin → Lista de Escolas → Detalhes da escola recém-cadastrada
Status inicial	Escola em `em_analise`

Etapa 4 — Gestão do Cadastro (Admin opera a escola)

Fluxo: Admin visualiza + edita dados institucionais → Ajustes de informação

Aspecto	Detalhe
Edge Function	`admin-escolas` (actions `get_details`, `update`)
Auth	`requireAdmin(req)`
Componente	`src/components/admin-escola-detalhes.tsx`
Validação	`UpdateEscolaSchema` (Zod) — campos opcionais flexíveis para edição
State Machine	`validarTransicaoStatus()` — transições válidas de status

Campos editáveis: nome, telefone, tipo, status, CNPJ, código INEP, rede/mantenedora, email, cidade, estado, endereço.

Erros Zod: Formatados como "campo: mensagem" em pt-BR (não vaza "Required" genérico).

Etapa 5 — Ativação da Assinatura

Fluxo: Admin cria assinatura (trial ou paga) → Auto-ativação da escola → Skeleton de faturas gerado

Aspecto	Detalhe
Edge Function	`admin-escola-dados` (action `create_assinatura`)
Edge Function alt.	`admin-assinaturas` (actions `create`, `convert_trial_to_paid`)
Auth	`requireAdmin(req)`
Componente	`src/components/admin-escola/ativar-plano-modal.tsx`
Validação	`CreateAssinaturaSchema` (Zod)
Tabelas	`escola_assinaturas`, `escola_faturas`, `planos`, `escolas`

Schema de validação (CreateAssinaturaSchema):

escola_id, plano_id — UUIDs obrigatórios
status_assinatura — 'ativa' ou 'trial'
alunos_contratados — mínimo 1
dia_vencimento — 1 a 28 (default 10)
mes_inicio — formato YYYY-MM, deve ser posterior ao mês atual
data_fim_contrato — formato YYYY-MM, >= mes_inicio
valor_personalizado — opcional, override do cálculo automático
renovacao_automatica — boolean (default true)

Fórmula de valor:

valor_atual = preco_mensal + (alunos_contratados × valor_por_aluno_extra)

Override possível com valor_personalizado.

Geração de faturas (skeleton):

Faturas geradas para cada mês do range [mes_inicio, data_fim_contrato]
Status: pendente, sem link_pagamento (skeleton)
Vencimento: dia_vencimento de cada mês
O cron faturamento-cron completa os skeletons com link MP + WhatsApp

Auto-ativação:

Se status_assinatura = 'ativa' e escola está em_analise → escola.status = ativa
Regra conservadora: só ativa escolas em em_analise

Log: assinatura.create

Etapa 6 — Liberação de Acessos

Fluxo: Admin cria usuários da escola → Atribui papéis → Usuários conseguem fazer login

Aspecto	Detalhe
Edge Function	`admin-usuarios` (actions `create`, `update`)
Edge Function alt.	`admin-usuarios-escola`
Auth	`requireAdmin(req)`
Tabelas	`usuarios`, `usuario_papeis`, `usuarios_escola_permissoes`
Login	`send-otp` → `verify-otp` → JWT → cookie `olp_auth`

Papéis criáveis: escola (gestor), coordenador, diretor.

Seed de permissões: Ao criar coordenador/diretor, permissões padrão são semeadas automaticamente.

Etapa 7 — Importação em Massa de Alunos ⚠️ CRÍTICO

Fluxo: Admin ou coordenador importa alunos via planilha → Parsing, validação, deduplicação, inserção bulk

Aspecto	Detalhe
Edge Function	`gestao-alunos` (actions `start_import_session`, `get_import_session_status`)
Componente	Wizard de importação com sessionId em localStorage
Processamento	Background via `EdgeRuntime.waitUntil`, batches de 50
Validação	Zero-trust server-side, `safeExtractValue()` para ExcelJS
Tabelas	`alunos`, `importacao_alunos_sessoes`

Ref: docs/development/IMPORT_SYSTEM_STANDARD.md

Etapa 8 — Criação de Turmas e Vínculos ⚠️ CRÍTICO

Fluxo: Criação de turmas → Vinculação de alunos → Cruzamento com olimpíadas ativas

Aspecto	Detalhe
Edge Function	`gestao-turmas` (actions `create`, `create_batch`)
Tabelas	`turmas`, `alunos` (turma_id)
Matching	Alunos vinculados a turmas por série/ano

Etapa 9 — Onboarding Completo

Fluxo: Admin marca checkpoints do onboarding

Checkpoints:

✅ Onboarding inicial (dados da escola completos)
✅ Configuração da plataforma
✅ Ativação de assinatura
✅ Liberação de acessos (usuários criados)
✅ Importação de alunos
✅ Onboarding completo (overview + direcionamentos)

Ciclo Contratual e Métricas

Visualização por Ano

Edge Function: admin-faturas (action get_ciclo_contratual)

Parâmetros: escola_id, ano (opcional — default: ano corrente)

Retorno:

faturas — lista de faturas do ano filtrado
metricas — cálculos do ano: total_faturas, pagas, pendentes, valor_total, valor_pago, valor_pendente, taxa_adimplencia
metricas_gerais — cálculos de todo o contrato (sem filtro de ano): total, pagas, pendentes, valor_total, valor_pago, valor_pendente, taxa_adimplencia
assinatura — dados da assinatura ativa
plano — dados do plano
anos_disponiveis — lista de anos com faturas

Resumo Geral do Contrato

O metricas_gerais é independente do filtro de ano no frontend. Ao trocar de ano, apenas a seção superior (métricas por ano + timeline) recarrega — o resumo geral permanece estável.

Edge Functions Envolvidas

Edge Function	Etapas	Actions Relevantes
`cadastro-escola-publica`	1, 2	`generate_link`, `validate_token`, `complete_signup`, `trial_create`
`admin-escolas`	4	`get_details`, `update`, `create`, `soft_delete`
`admin-escola-dados`	5	`create_assinatura`, `get_details`, `get_dashboard`
`admin-assinaturas`	5	`create`, `convert_trial_to_paid`, `update`
`admin-faturas`	5	`list`, `get_ciclo_contratual`, `update_status`
`admin-usuarios`	6	`create`, `update`
`gestao-alunos`	7	`start_import_session`, `create`
`gestao-turmas`	8	`create`, `create_batch`

Componentes Frontend

Componente	Etapa	Descrição
`admin-escola-detalhes.tsx`	4, 5, 6	Tela principal de detalhes da escola (tabs)
`ativar-plano-modal.tsx`	5	Modal de criação de assinatura com range de faturas
`ciclo-contratual-dashboard.tsx`	5	Dashboard do ciclo contratual (métricas + timeline)
`CadastroCompletoPage.tsx`	2	Formulário público de cadastro

Schemas Zod

Schema	Arquivo	Uso
`CreateEscolaSchema`	`admin-escola-schemas.ts`	Criação de escola (admin-escolas)
`UpdateEscolaSchema`	`admin-escola-schemas.ts`	Edição de dados institucionais
`ToggleStatusSchema`	`admin-escola-schemas.ts`	Alteração de status com state machine
`CreateAssinaturaSchema`	`admin-escola-schemas.ts`	Criação de assinatura (admin-escola-dados)

Dívida Técnica

Item	Severidade	Status
`cadastro-escola-publica` sem Zod (806 linhas)	🟡 Média	Pendente — validação manual funcional
`admin-escola-dados` (656 linhas)	🟡 Média	Pendente — code split futuro
`admin-escolas` (870 linhas)	🟡 Média	Pendente — code split futuro
`admin-faturas` (980 linhas)	🟡 Média	Pendente — code split futuro
`admin-escola-detalhes.tsx` (1554 linhas)	🔴 Alta	Pendente — extrair tabs em subcomponentes

Referências

Subscription & Billing — Planos, faturas, cron
Edge Functions Catalog — Catálogo completo
Import System Standard — Padrão de importação
Audit Checklist — Checklist de auditoria @audit

Onboarding de Escolas — SSOT ​

Visão Geral ​

Etapas ​

Etapa 1 — Geração do Link de Cadastro (Admin) ​

Etapa 2 — Formulário de Cadastro (Escola) ​

Etapa 3 — Notificação ao Admin + Navegação ​

Etapa 4 — Gestão do Cadastro (Admin opera a escola) ​

Etapa 5 — Ativação da Assinatura ​

Etapa 6 — Liberação de Acessos ​

Etapa 7 — Importação em Massa de Alunos ⚠️ CRÍTICO ​

Etapa 8 — Criação de Turmas e Vínculos ⚠️ CRÍTICO ​

Etapa 9 — Onboarding Completo ​

Ciclo Contratual e Métricas ​

Visualização por Ano ​

Resumo Geral do Contrato ​

Edge Functions Envolvidas ​

Componentes Frontend ​

Schemas Zod ​

Dívida Técnica ​

Referências ​