Como colocar a Plataforma Mobiliza no ar

A Mobiliza é uma aplicação multi-tenant: vários projetos (Mobiliza Curitiba, Semil Circular, etc.) compartilham o mesmo host, isolados por um slug. Cada projeto tem sua homepage pública, curso, gincana, premiação e marca própria — inclusive instalação como app no celular com nome e ícone do projeto.

A implementação se divide em quatro frentes, e este manual segue exatamente essa ordem:

São sete papéis no enum app_role. Vivem em src/contexts/AuthContext.tsx, ProtectedRoute.tsx, ProjectProtectedRoute.tsx e src/App.tsx.

Vive em src/components/master/CreateProjectForm.tsx (rota /master/projetos/novo).

1. No painel /master, clicar em "Criar novo projeto".
2. Preencher os campos do formulário (detalhados abaixo).
3. Clicar "Salvar projeto". O sistema insere em projects, vincula os admins existentes e redireciona para /master com toast mostrando o /<slug>.

Campos do formulário

Gerir o projeto e vincular o curso

Vive em src/pages/master/ProjectDetails.tsx (rota /master/projetos/:id), com abas:

• Visão geral: seletor "Curso vinculado" — só cursos published aparecem; grava em projects.course_id. Botões de status e arquivar/desarquivar.
• Redes / Escolas: mesma função do painel admin (Bloco B). Remover rede apaga as escolas em cascata.
• Admins: adicionar por e-mail com feedback explícito ("Usuário não encontrado", "Já é administrador").
• Parceiros: nome + ordem.

Cadastrar editores de curso

Vive em src/pages/master/EditorManagement.tsx (rota /master/editores).

1. Em /master/editores, digitar o e-mail do usuário e clicar Adicionar.
2. O sistema busca profiles por e-mail. Não achou → "Usuário não encontrado". Já é editor → "Este usuário já é editor".
3. Sucesso: insere user_roles com role: 'editor' (sem project_id).

Vive em src/pages/admin/AdminConfig.tsx (rota /projeto/<slug>/admin/config). Seis abas: Geral, Hierarquia, Homepage, Visual, Parceiros, KPIs.

Aba Geral

Nome e Slug são somente leitura. Logotipo (sobe para <slug>/logo-<ts>.<ext>), Status, Camada de coleta (toggle que esconde Coletores/Coord. Coleta do menu quando off) e quatro toggles de "quem pode se inscrever pelo formulário público".

Aba Hierarquia

Renomeia rótulos sem mudar função: Nível 1 (Rede), Nível 2 (Escola), Papel A (Professor), B (Coord. Pedagógico), C (Coord. Coleta), D (Coletor) + a "área de atuação" do Papel A. Preview mostra o efeito no menu/cadastro.

Aba Visual

Cinco cores: Primária, Secundária, Destaque, Texto Principal, Header/Navbar. Preview ao vivo. Salvar com "Salvar cores".

Aba Parceiros

Nome, Categoria (Iniciativa, Realização, Co-realização, Patrocínio, Apoio, Parceiro), Site, logo. Reordena categorias (não parceiros individuais).

Aba KPIs

Metas (taxas de cadastro/início/conclusão, totais) e pesos de evidências de engajamento — esses pesos alimentam o ranking em Relatórios.

Aba Homepage

Cada card persiste em colunas de project_homepage_settings: ordem dos blocos, Hero (foto/mesh/static), overlay, rodapé (3 colunas), SEO/favicon/OG, e os campos PWA (próxima seção). Cada bloco tem toggle de visibilidade.

PWA dinâmico — instalação no celular

Card "App instalável (PWA)" em AdminConfig.tsx, mais src/lib/pwa-icons.ts e a edge function supabase/functions/project-manifest/index.ts.

Todos os projetos compartilham o host, mas cada um deve instalar no celular com a sua própria marca. O manifest.webmanifest é gerado dinamicamente pela edge function lendo quatro campos de project_homepage_settings.

1. Nome completo (splash) → pwa_name. Vazio = nome do projeto.
2. Nome curto (homescreen) → pwa_short_name. Máx. 12 caracteres.
3. Cor do app → pwa_theme_color. Botão "Usar cor do projeto" copia a primária.
4. Ícone → PNG quadrado 512×512 ou maior. O upload gera 4 derivados via canvas (icon-192, icon-512, icon-maskable-512, apple-touch-180) com o mesmo timestamp.
5. Clicar "Salvar configuração do app".

Hierarquia rede → escola → pessoas

Redes e Escolas (AdminSchools.tsx): cadastro manual ou import CSV (botão "Modelo CSV"). Cada escola gera unique_code e dispara geocodificação assíncrona.

Professores / Coordenadores (AdminTeachers, AdminCoordPedagogico, AdminCoordColeta): nome, e-mail, escola. Coord. de Coleta tem checkbox "Mesmo que o Coord. Pedagógico".

Coletores e aprovação (AdminColetores.tsx): entram como pendente. Ao aprovar, dispara automaticamente um magic link para o e-mail apontando para /projeto/<slug>/operador. Botão "Identificação" gera cartão imprimível com QR code real por escola.

Campanhas e régua de e-mail

Campanhas pontuais (AdminEmailCampaign.tsx): escolher grupos destinatários, escrever (ou gerar com IA), enviar agora ou agendar. Variáveis {{nome}}, {{escola}}, {{link_curso}} etc.

Régua automática (AdminEmailAutomation.tsx): réguas por persona com mensagens em sequência (atraso em dias ou vinculado a etapa do projeto). "Log de Envios" lê email_automation_logs (fonte de verdade).

Gincana e premiação

Gincana (AdminGincana.tsx): configurar (ativa, datas, pontos por kg coletado), criar missões (título, categoria, pontos, multiplicador, exigências de relato/foto/link) e aprovar/rejeitar submissões com feedback ao participante. Existe uma missão de sistema "Coleta" não-excluível.

Premiação (AdminPremiacao.tsx): liberar/revogar certificados (personalizáveis: assinatura, logo parceiro, cidade), troféus (pódio + menções honrosas) e relatório consolidado.

Dashboard e relatórios

Dashboard (AdminDashboard.tsx): três camadas — Conversão, Engajamento, Alertas de intervenção. Cada alerta tem botão "Enviar e-mail" que pré-seleciona grupo e filtro.

Relatórios (AdminRelatorios.tsx): três abas (Curso, Engajamento, Coleta), cada uma com Exportar CSV (BOM UTF-8).

Relatório WhatsApp (AdminWhatsAppReport.tsx): template com variáveis resolvidas por dados reais, "Gerar hoje" + "Copiar".

Vive em src/pages/master/CourseCatalog.tsx (rotas /master/cursos e /editor/cursos).

• Novo curso: botão → /<base>/cursos/novo.
• Duplicar: cria cópia draft clonando módulos → aulas → perguntas.
• Publicar/Despublicar: alterna courses.status entre published e draft. É aqui que se publica — não no editor.
• Excluir: só master; bloqueado se o curso estiver vinculado a ≥1 projeto.

Editor de curso

Vive em src/pages/master/CourseEditor.tsx (rota /<base>/cursos/:courseId).

1. Aba Informações: Nome (obrigatório), Descrição, Carga horária (default 40h), Nota mínima (default 70%). "Criar curso" insere em courses como draft.
2. Aba Conteúdo: "Novo módulo" (só nome). Dentro do módulo, "Adicionar aula".
3. Aula: Título + tipo de conteúdo (Vídeo URL, Texto rich, Imagem, Galeria até 20, PDF legado) + duração opcional.
4. Perguntas da aula: 1+, cada uma com tipo, enunciado e pontos.

Tipos de pergunta suportados

Preview e revisão pedagógica externa

Dois caminhos, mesma UI (player em previewMode — não grava progresso/XP/streak, não afeta ranking):

1. Preview autenticado: botão "Pré-visualizar curso" no editor → /cursos/:id/preview (master/editor).
2. Preview público compartilhável: botão "Compartilhar" (só master). Define rótulo + validade, gera token em course_preview_tokens e copia o link. A rota /cursos/:id/preview/:token é pública; a edge function course-preview valida server-side com service_role e devolve o curso inteiro.

Liberação de módulos por projeto

Vive em src/pages/admin/AdminCurso.tsx e AdminCursoLiberacao.tsx. Nota: AdminModulos.tsx gerencia etapas/fases do projeto (project_stages), não módulos de curso.

Quem vincula o curso ao projeto é o master (Bloco A). O admin do projeto controla, por módulo: Liberar, Bloquear ou Programar liberação (data + hora) — grava em project_module_overrides. Ações em massa incluem "Cronograma sequencial" (data inicial + intervalo).

SPA Vite + React 18 + TypeScript, Tailwind/shadcn no front, Supabase como backend completo (Postgres + Auth + Storage + Edge Functions Deno). Deploy gerido pelo Lovable.

• Cliente Supabase (src/integrations/supabase/client.ts): único, tipado por types.ts (gerado — nunca editar à mão; o Lovable regenera após cada migration). Usa a anon/publishable key — o isolamento é todo via RLS.
• AuthContext: fonte de verdade de identidade e papéis. Master tem project_id = null e acesso global. Fallback via RPC is_master.
• GamificationContext: estado no localStorage namespaced por slug e resetado na troca de projeto — a gamificação nunca vaza entre tenants.
• Guardas de rota: ProtectedRoute (auth + papel global, tri-state com grace de 1,5 s) e ProjectProtectedRoute (resolve slug→id e escopa o papel ao tenant).

Banco de dados e migrations

São 101 migrations em supabase/migrations/. As escritas à mão recebem nome semântico e um *.README.md companheiro com prompt, validação e rollback.

RLS habilitado em todas as tabelas de domínio. Padrão de policy: master faz tudo (is_master), admin gere o próprio projeto (is_project_admin), participante vê o que é do seu projeto (get_user_project_ids), dono vê o próprio registro. Funções de segurança são SECURITY DEFINER para evitar recursão de RLS.

Migration destacada — operator_security_hardening (20260513100000)

Fechou dois gaps cross-tenant: (1) operador aprovado no projeto A podia gravar coleta com escola do projeto B — nova policy valida que project_id/school_id da linha batem com o vínculo do operador; (2) bucket Storage project-assets aberto a qualquer authenticated — nova policy extrai project_id do path (storage.foldername(name)[1]) e exige vínculo. Idempotente.

Edge functions

10 funções Deno + _shared/. verify_jwt = false declarado para as públicas (auth-email-hook, evaluate-answer, geocode-address, course-preview, project-manifest) — elas fazem a própria validação.

Deploy e ambiente

Lovable e o repo são bidirecionais. .env commitado só tem chave pública (anon key — isolamento é via RLS); os segredos reais ficam só nos secrets das edge functions.

git clone <git-url>
cd escolascirculares
npm i
npm run dev      # Vite em http://localhost:8080

O front local aponta para o Supabase de produção (não há Supabase local no repo). Edge functions em dev usam as já deployadas em produção.

Regras críticas de operação

1. Migration não é automática no merge. Sempre prompt explícito ao Lovable + README idempotente com validação e rollback + regenerar types.ts.
2. Segredos. service_role e LOVABLE_API_KEY só como secrets do Supabase. Endpoint novo com service_role precisa validar o tenant manualmente.
3. Multi-tenant por slug. projects.slug é a raiz do isolamento. Auditar policies novas contra escrita/leitura cross-tenant — inclusive Storage (path …/{project_id}/…).
4. Padrão do ícone PWA. pwa_icon_url deve apontar para …/icon-192-<ts>.png. Nunca colar URL fora do padrão.
5. Filas de e-mail. Produtores enfileiram; só o worker cron envia. Respeitar anti-duplicata e cooldown.
6. verify_jwt por função. Função pública nova decide o verify_jwt conscientemente e implementa validação própria.
7. course_modules.course_id é o link canônico curso↔módulo; project_id ali é legado — não usar para lógica nova.