Cockpit Inteligente de Gestão Escolar

1Resumo executivo

O produto não deve ser tratado como um simples dashboard. A proposta é criar uma camada de inteligência de gestão sobre o Sponte: os dados operacionais continuam sendo registrados no Sponte, enquanto a nova plataforma organiza, historiza, cruza e transforma esses dados em indicadores, alertas e ações.

• Sponte permanece como sistema de origem e fonte operacional.
• A nova plataforma atua como camada de integração, analytics e gestão.
• O foco da experiência é responder: como está a escola, o que mudou, onde há risco e quem precisa agir.
• A primeira versão deve priorizar retorno financeiro e adoção: financeiro, matrículas/comercial e Central de Atenção.
• Acadêmico, evasão, automações avançadas e copiloto com IA entram de forma incremental.

1.1Proposta de valor

Transformar dados dispersos em decisões. Em vez de exigir que o gestor navegue por relatórios, a plataforma deve apresentar prioridades do dia, explicar desvios de indicadores, disponibilizar listas acionáveis e permitir executar ou delegar ações.

DADO → INDICADOR → DIAGNÓSTICO → PRIORIDADE → AÇÃO → AUTOMAÇÃO → RESULTADO

1.2Usuários-alvo

2Escopo funcional do produto

2.1Página inicial — Hoje na Escola

A home deve priorizar exceções e ações. Gráficos são secundários; o bloco mais importante é “O que exige atenção hoje?”.

• Alunos ativos, novas matrículas e cancelamentos.
• Receita prevista, recebida e vencida.
• Taxa de inadimplência e saldo em aberto.
• Ticket médio.
• Novas matrículas e progresso contra meta.
• Quantidade de alunos com frequência crítica.
• Leads sem contato e oportunidades paradas.
• Turmas com lotação alta ou baixa ocupação.
• Resumo de alertas críticos e tarefas pendentes.

HOJE NA ESCOLA

Alunos       Receita mês     Inadimplência    Matrículas
1.248        R$ 482 mil      8,4%             37

ATENÇÃO HOJE
• 27 alunos com risco financeiro
• 14 alunos abaixo de 75% de frequência
• 19 oportunidades sem contato há mais de 48h
• 3 turmas acima de 95% de ocupação

[Ver prioridades do dia]

2.2Módulo Executivo

• Indicadores sempre com valor atual, meta, período anterior e tendência.
• Comparação mês anterior, mesmo período do ano anterior e meta.
• Receita, alunos, matrículas, cancelamentos, evasão, rematrícula, ocupação e ticket médio.
• Filtros por unidade, curso, turma, modalidade e período, quando disponíveis.
• Relatório executivo diário, semanal e mensal.

2.3Módulo Financeiro

• Faturamento previsto x realizado.
• Recebimentos do período.
• Receita por unidade, curso, turma e modalidade.
• Valores a vencer e vencidos.
• Aging de inadimplência: 1-7, 8-15, 16-30, 31-60 e 60+ dias.
• Lista de inadimplentes com valor, dias de atraso, histórico e prioridade.
• Ticket médio, descontos, bolsas e receita perdida por descontos, se os dados existirem.
• Métrica de recuperação obtida por automações de cobrança.

2.4Módulo Comercial e Matrículas

• Leads por origem e status.
• Tempo até primeiro contato.
• Leads sem contato e leads parados.
• Funil: lead → contato → visita → proposta → matrícula.
• Conversão por atendente, curso e origem.
• Meta de matrículas e projeção de fechamento.
• Receita potencial do pipeline.
• Rematrículas: elegíveis, concluídas, pendentes, sem contato e recusadas.

2.5Módulo Acadêmico

• Frequência geral, por turma e por aluno.
• Faltas consecutivas.
• Alunos abaixo de limite configurável de presença.
• Médias, evolução de notas e alunos abaixo da média, caso existam dados.
• Alunos em recuperação.
• Risco de evasão por regras auditáveis.
• Listas de acompanhamento para coordenação.

2.6Aluno 360º

Consolidar em uma única tela o histórico relevante de um aluno.

• Dados cadastrais e responsáveis.
• Matrícula atual e histórico de matrículas.
• Curso, turma e unidade.
• Situação financeira e últimas parcelas.
• Frequência e faltas.
• Notas e desempenho, se disponíveis.
• Contratos e pendências.
• Alertas, tarefas, contatos e automações relacionadas.

2.7Turmas e capacidade

• Quantidade de alunos por turma.
• Capacidade planejada e taxa de ocupação.
• Turmas lotadas, próximas da lotação e com baixa ocupação.
• Disponibilidade por horário, curso e unidade.
• Receita estimada por turma.
• Margem estimada por turma somente se houver dados confiáveis de custos.

2.8Central de Atenção

Camada transversal que transforma indicadores em exceções priorizadas.

2.9Central de Tarefas

• Tarefa associável a aluno, lead, turma, alerta ou cobrança.
• Responsável, prioridade, prazo, status e histórico.
• Criação manual ou automática.
• Filtros por responsável, setor, vencimento, prioridade e origem.
• Registro de conclusão e resultado para auditoria.

2.10Metas

• Matrículas, receita, recebimentos, inadimplência, rematrícula, evasão, ocupação e conversão.
• Meta por período e, quando necessário, por unidade/curso/equipe.
• Progresso, projeção de fechamento e diferença para meta.

3Integração com Sponte

Base fornecida: documentação/listagem de APIs do Sponte contendo endpoints de clientes, coletas de indicadores, pesquisas, Movidesk e consulta SQL dinâmica. O endpoint mais relevante para descoberta é POST /api/query, descrito como execução de consulta SQL dinâmica somente SELECT, exigindo WITH(NOLOCK) nas tabelas.

3.1Endpoints identificados no material fornecido

Fonte: arquivo de APIs Sponte fornecido pelo solicitante.

3.2Regra obrigatória para /api/query

Nunca expor SQL arbitrário ao frontend e nunca permitir que usuário ou IA monte SELECT livre e o envie diretamente ao Sponte.

Frontend / IA
    ↓
Analytics API interna
    ↓
Catálogo de consultas homologadas e parametrizadas
    ↓
SponteClient
    ↓
POST /api/query

Exemplos de consultas internas versionadas:

financial.overdue_students
financial.monthly_revenue
financial.aging
academic.low_attendance
commercial.open_leads
enrollment.new_students
classes.occupancy

3.3Discovery obrigatório antes do desenvolvimento completo

1. Homologar autenticação e limites da API.
2. Descobrir tabelas e campos disponíveis para a credencial real da escola.
3. Identificar chaves únicas: aluno, matrícula, turma, parcela, contrato, lead e responsável.
4. Determinar como diferenciar registros ativos, cancelados e históricos.
5. Validar parcelas, recebimentos, datas de vencimento, descontos e acordos.
6. Validar frequência, notas, avaliações, professores e turmas.
7. Validar CRM/leads e histórico de contatos.
8. Mapear códigos de situação e regras de negócio do Sponte.
9. Medir latência, limites e estabilidade do endpoint.
10. Documentar cada consulta homologada e seu significado.

3.4Observação sobre WITH(NOLOCK)

O uso obrigatório de WITH(NOLOCK) favorece leituras sem bloquear o banco transacional, mas pode produzir leituras momentaneamente inconsistentes. Os dados devem ser tratados como gerenciais/operacionais. Não assumir que são equivalentes a um fechamento contábil oficial sem validação específica.

4Arquitetura proposta

Adotar inicialmente um monólito modular. Microserviços não são recomendados no MVP porque aumentariam complexidade operacional sem benefício proporcional.

┌───────────────────────────────┐
│ Frontend Web — Next.js        │
└──────────────┬────────────────┘
               │ HTTPS
┌──────────────▼────────────────┐
│ Backend — NestJS / TypeScript │
│ Auth | Dashboard | Financeiro │
│ Comercial | Acadêmico         │
│ Alertas | Tarefas | Automação │
│ Integração Sponte | IA        │
└───────┬─────────┬─────────────┘
        │         └──────────────► Sponte API
        ▼
 PostgreSQL
        │
        └──────────────► Redis / BullMQ (jobs e filas)

4.1Stack recomendada

4.2Estratégia de sincronização

O dashboard não deve consultar o Sponte em tempo real a cada abertura de tela.

Sponte
  ↓ jobs de sincronização
PostgreSQL local
  ↓ métricas / agregações
Dashboard, alertas e IA

As cadências devem ser ajustadas aos limites reais da API e à criticidade de cada dado.

4.3Multi-tenant

Mesmo com um único cliente inicial, a arquitetura deve nascer multiempresa. Todas as entidades de domínio devem ser vinculadas a tenant_id/school_id e as consultas devem aplicar isolamento obrigatório.

5Modelo de dados conceitual

School
├── Unit
├── User / Role
├── Student
│   ├── Guardian
│   ├── Enrollment
│   ├── Attendance
│   ├── Grade
│   ├── Invoice
│   └── Payment
├── Course
│   └── Class
│       └── Teacher
├── Lead
│   └── Opportunity
├── Goal
├── Alert
├── Task
├── Automation
├── AutomationExecution
└── MetricSnapshot

5.1Campos de integração

Toda entidade sincronizada deve possuir rastreabilidade da origem:

id                  UUID interno
tenant_id           UUID da escola
external_id         identificador no Sponte
source              "sponte"
source_updated_at   timestamp de origem, quando existir
last_synced_at      timestamp da última sincronização
raw_hash            opcional, para detectar alterações
created_at
updated_at

5.2Snapshots de métricas

metric_snapshots
- id
- tenant_id
- date
- metric_key
- dimension_type
- dimension_id
- value
- metadata_json

Essa tabela deve permitir comparações históricas, tendências e futuras previsões sem depender de reconsultar o Sponte para períodos antigos.

6Motor de regras, alertas e risco

No MVP, preferir regras determinísticas e auditáveis. Machine learning deve ser uma evolução posterior, quando houver histórico suficiente e labels confiáveis.

6.1Exemplo de risco de evasão

score = 0

if attendance < 75%:            score += 30
if overdue_days > 15:            score += 25
if grade_drop > 20%:            score += 15
if consecutive_absences >= 3:   score += 15
if reenrollment_not_started:     score += 15

O sistema deve mostrar os fatores que formaram o score, evitando uma classificação opaca.

6.2Severidades

7Automações

As automações devem ser baseadas em gatilho + condições + ações, com logs completos de execução.

7.1Requisitos técnicos de automação

• Fila assíncrona com retry e backoff.
• Idempotência para impedir mensagens duplicadas.
• Janela de horário permitida.
• Templates versionados.
• Opt-out/consentimento quando aplicável.
• Log de tentativa, sucesso, erro e resposta externa.
• Capacidade de pausar uma automação imediatamente.
• Ambiente de teste/sandbox antes de habilitar produção.

8Copiloto de gestão com Claude

O recurso de IA deve ser implementado após existir uma camada analítica confiável. O modelo nunca recebe acesso irrestrito ao banco ou ao endpoint SQL do Sponte.

Usuário
  ↓
Claude
  ↓ tool calling
Analytics API interna
  ↓
Serviços autorizados
  ↓
PostgreSQL / métricas homologadas

8.1Tools permitidas — exemplos

getExecutiveSummary(period)
getFinancialSummary(period)
getOverdueStudents(filters)
getEnrollmentSummary(period)
getStudentsAtRisk(filters)
getClassOccupancy(filters)
getGoalProgress(goalId)
getAlerts(severity, domain)

8.2Casos de uso

• “Como foi agosto?”
• “Por que a inadimplência aumentou?”
• “Quais alunos precisam de atenção esta semana?”
• “Quais turmas estão com baixa ocupação?”
• “O que devo priorizar hoje?”

Toda resposta quantitativa da IA deve ser baseada em dados retornados por tools internas, preferencialmente indicando período e contexto.

9Segurança, privacidade e LGPD

• HTTPS obrigatório.
• Autenticação segura e sessões com expiração.
• Senhas com hash forte; nunca armazenar senha em texto puro.
• RBAC por papel e possibilidade de restrição por unidade.
• Isolamento multi-tenant obrigatório em todas as queries.
• Secrets somente em secret manager/variáveis seguras; nunca no repositório.
• Logs de auditoria para acesso e ações sensíveis.
• Criptografia em trânsito e, quando aplicável, em repouso.
• Backups com teste de restauração.
• Rate limiting e proteção contra abuso.
• Validação de entrada e DTOs.
• Política de retenção de dados.
• Minimização dos dados enviados ao provedor de IA.
• Consentimento/base legal e controles de comunicação com responsáveis conforme LGPD.

9.1Perfis iniciais

10Requisitos não funcionais

11Organização recomendada do backend

apps/api/src/
├── modules/
│   ├── auth/
│   ├── tenants/
│   ├── users/
│   ├── students/
│   ├── finance/
│   ├── academic/
│   ├── commercial/
│   ├── classes/
│   ├── goals/
│   ├── alerts/
│   ├── tasks/
│   ├── automations/
│   ├── analytics/
│   ├── ai/
│   └── integrations/
│       └── sponte/
├── common/
├── config/
└── main.ts

11.1Adapter Sponte

integrations/sponte/
├── sponte.module.ts
├── sponte.client.ts
├── sponte.config.ts
├── sponte.types.ts
├── sponte.errors.ts
├── queries/
│   ├── financial.queries.ts
│   ├── academic.queries.ts
│   ├── commercial.queries.ts
│   └── enrollment.queries.ts
└── sync/
    ├── students.sync.ts
    ├── finance.sync.ts
    ├── academic.sync.ts
    └── commercial.sync.ts

12Organização recomendada do frontend

apps/web/
├── app/
│   ├── (auth)/
│   ├── dashboard/
│   ├── financeiro/
│   ├── comercial/
│   ├── academico/
│   ├── alunos/
│   ├── turmas/
│   ├── alertas/
│   ├── tarefas/
│   ├── metas/
│   ├── automacoes/
│   └── assistente/
├── components/
│   ├── dashboard/
│   ├── charts/
│   ├── tables/
│   └── ui/
├── lib/
└── types/

12.1Padrões de UX

• Cada KPI mostra contexto, não apenas um número.
• Listas críticas devem ter ação direta.
• Filtros globais de período e unidade devem ser consistentes.
• Alertas devem explicar por que foram criados.
• Evitar excesso de gráficos na home.
• Priorizar tabelas pesquisáveis e listas acionáveis quando a decisão exige identificar pessoas/casos.
• Layout responsivo para notebook e tablet; mobile pode ter foco em leitura e tarefas.

13Plano de implementação

Entrega particionada em etapas pequenas e executáveis. Cada etapa fecha com lint, typecheck e testes.

MVP Etapas 0–3  ·  Evolução Etapas 4–7

Etapa 0Discovery e POC do Sponte

Objetivo: comprovar o contrato real de dados antes de construir módulos dependentes dele.

• Criar SponteClient com autenticação, timeout, retry e logs.
• Homologar /api/query e endpoints de indicadores.
• Mapear schema e códigos importantes.
• Criar 10-20 consultas de leitura controladas.
• Gerar documento “Sponte Data Dictionary”.

Critério de aceite: conseguir recuperar amostras de dados essenciais e mapear identificadores/relacionamentos com segurança.

Etapa 1Fundação da plataforma

• Monorepo ou repositórios web/api.
• PostgreSQL, migrations e multi-tenant.
• Autenticação e RBAC.
• Docker e configuração de ambientes.
• Observabilidade mínima e CI.

Etapa 2Sincronização e camada analítica

• Jobs de sync Sponte → PostgreSQL.
• Idempotência e upsert por external_id.
• Snapshots de métricas.
• Tela técnica de status da integração.

Etapa 3MVP executivo + financeiro

• Home Hoje na Escola.
• Receita, recebimentos, vencidos e aging.
• Lista de inadimplentes.
• Metas básicas.
• Alertas financeiros.

Etapa 4Comercial e matrículas

• Funil, leads, tempo de atendimento e conversão, se os dados existirem.
• Matrículas e projeção contra meta.
• Rematrículas.
• Alertas e tarefas comerciais.

Etapa 5Acadêmico e Aluno 360º

• Frequência, faltas, desempenho e risco por regras.
• Aluno 360º.
• Alertas e tarefas de acompanhamento.

Etapa 6Automações

• Motor de gatilhos/condições/ações.
• Fila, retries, idempotência e histórico.
• WhatsApp oficial/e-mail após validação comercial e jurídica.

Etapa 7Copiloto com IA

• Claude com tool calling controlado.
• Resumo executivo e Morning Briefing.
• Perguntas sobre métricas.
• Guardrails e auditoria de tools.

14Escopo do MVP recomendado

Para controlar prazo e risco, o primeiro release vendável deve se limitar a:

• Login e perfis.
• Dashboard executivo.
• Financeiro e inadimplência.
• Matrículas e metas.
• Central de Atenção.
• Tarefas.
• Integração periódica com Sponte.
• Histórico de métricas.

15Critérios de aceite gerais

• Nenhum dado de outra escola pode ser acessado por usuário de tenant diferente.
• Nenhum SQL do Sponte pode ser fornecido pelo browser ou pelo modelo de IA.
• Toda sincronização deve registrar início, fim, volume, erro e última execução válida.
• Jobs devem ser idempotentes.
• KPIs devem declarar período e unidade/filtro aplicados.
• Alertas devem registrar regra, motivo e momento da geração.
• Automação deve registrar gatilho, ação, destinatário, status e resultado.
• Dashboard deve continuar apresentando último snapshot válido quando a integração estiver temporariamente indisponível.
• Mudanças de schema devem ocorrer somente por migration.
• Regras financeiras e de risco devem possuir testes unitários.

16Estratégia de testes

17Documentação obrigatória no repositório

• README.md com setup local e arquitetura.
• docs/architecture.md
• docs/sponte-data-dictionary.md
• docs/metrics-catalog.md
• docs/automation-rules.md
• docs/security.md
• docs/runbooks/sponte-sync.md
• .env.example sem secrets.
• OpenAPI/Swagger da API interna.

18Regras para o Claude / Claude Code

Estas regras devem ser tratadas como instruções obrigatórias durante a implementação:

1. Não inventar tabelas, colunas ou endpoints do Sponte. Quando o contrato não estiver confirmado, criar interface/placeholder e marcar TODO de homologação.
2. Nunca expor credenciais do Sponte ao frontend.
3. Nunca aceitar SQL arbitrário vindo do frontend ou da IA.
4. Priorizar monólito modular; não introduzir microserviços sem necessidade comprovada.
5. Não adicionar dependências sem explicar a utilidade.
6. Manter módulos com controllers, services, DTOs e repositories/Prisma quando aplicável.
7. Aplicar tenant_id em todos os domínios persistidos e testar isolamento.
8. Toda integração externa deve ter timeout, tratamento de erro, retry apenas quando seguro e logs.
9. Toda rotina de sync deve ser idempotente.
10. Construir em etapas pequenas e executáveis.
11. Ao concluir uma etapa, executar lint, typecheck e testes.
12. Não avançar silenciosamente quando uma decisão alterar regra de negócio. Registrar a decisão no documento/ADR.
13. Criar migrations; nunca editar schema de produção manualmente.
14. Gerar dados mock para UI sem confundi-los com dados reais.
15. Evitar abstrações prematuras; favorecer código legível e domínio explícito.

19Prompt mestre para iniciar o projeto no Claude Code

Você atuará como engenheiro de software sênior e arquiteto deste projeto.

Leia este documento inteiro antes de gerar código. Trate-o como a especificação principal do produto.

OBJETIVO
Construir uma plataforma web multi-tenant de inteligência de gestão escolar integrada ao Sponte.
O Sponte é a fonte operacional. Nossa aplicação deve sincronizar dados para PostgreSQL, gerar
métricas e históricos e oferecer dashboards, alertas, tarefas, metas, automações e, posteriormente,
um copiloto de gestão com Claude.

PRINCÍPIOS
1. Começar pelo núcleo mínimo funcional.
2. Usar monólito modular.
3. Frontend: Next.js + TypeScript.
4. Backend: NestJS + TypeScript.
5. Banco: PostgreSQL + Prisma.
6. Jobs: BullMQ + Redis quando a etapa de sincronização exigir.
7. Docker para ambiente local reproduzível.
8. Todo dado deve ser isolado por tenant.
9. Não inventar schema do Sponte.
10. Nunca permitir SQL arbitrário de frontend ou IA.
11. Nunca consultar o Sponte diretamente a partir do browser.
12. Nunca usar Claude com acesso direto ao banco. IA usa tools internas autorizadas.
13. Criar testes unitários para regras importantes.
14. Manter documentação atualizada à medida que o projeto evoluir.

PRIMEIRA MISSÃO
Não implemente o produto inteiro de uma vez.
Comece pela ETAPA 0: Discovery/POC Sponte + fundação mínima.

Entregue:
A. árvore inicial do repositório;
B. decisões de arquitetura;
C. arquivos de configuração;
D. SponteClient;
E. types/interfaces da integração;
F. catálogo inicial de queries homologáveis;
G. tratamento de erros;
H. logs;
I. testes unitários do client;
J. .env.example;
K. README com comandos de execução.

Quando algum detalhe da API Sponte não estiver disponível, NÃO INVENTE. Crie interfaces e mocks
claramente identificados e registre exatamente qual informação falta para homologação.

Ao final:
- mostre os arquivos criados;
- diga o que funciona;
- mostre como instalar;
- mostre como executar;
- mostre como rodar testes;
- liste as pendências da próxima etapa.

20Decisões que precisam ser homologadas com o cliente / Sponte

• Credenciais, autenticação e ambiente de homologação do Sponte.
• Limites/rate limits da API.
• Tabelas e campos acessíveis via /api/query.
• Disponibilidade de parcelas, recebimentos e descontos.
• Disponibilidade de presença, notas e histórico acadêmico.
• Disponibilidade de leads e histórico comercial.
• Definição de aluno ativo, cancelado, evadido e rematriculado.
• Capacidade das turmas e fonte desse dado.
• Canal de comunicação oficial (WhatsApp, e-mail, ambos).
• Unidades/escolas que participarão do piloto.
• Usuários e papéis iniciais.
• Metas e limites que geram alertas.
• Política de retenção e tratamento LGPD.

21Roadmap de evolução

22Definition of Done por feature

• Código implementado e revisável.
• Types/DTOs definidos.
• Validações e tratamento de erro implementados.
• Permissão/RBAC definido quando aplicável.
• Isolamento tenant testado.
• Testes automatizados relevantes passando.
• Logs adicionados em operações críticas.
• Migration incluída quando houver alteração de banco.
• Documentação atualizada.
• UI com loading, empty state e error state.
• Critérios de aceite funcionais validados.

23Resultado esperado

O resultado final deve ser um produto que transforme o Sponte de fonte operacional em base para uma gestão proativa. A plataforma não deve apenas exibir dados: ela deve identificar desvios, priorizar casos, apoiar decisões, criar tarefas, executar automações e medir o resultado dessas ações.