Modelos de Dados e Cálculo de Score
Modelos centrais
Arquivo base: `Untitled-1.js`
`Estudante`
Campos relevantes usados no risco:
- Identificação: `id`, `nome`, `curso`, `turma`, `campus`, `turno`.
- Acadêmico: `nota`, `disciplinas`, `semestre`, `semestreCurso`.
- Engajamento: `ava.acessos`, `ava.ultimoAcesso`, `interacoes`.
- Frequência: `presenca.total`, `presenca.faltas`.
- Financeiro: `mensalidade.situacao`, `mensalidade.valorEmAberto`.
- Histórico de ação: `intervencoes[]`.
`Intervenção`
Campos típicos:
- `id`, `tipoAlerta`, `acao`, `responsavel`, `data`.
- `resultadoAcao` (ex.: `melhora`, `semmudanca`, `piorou`).
- `acertoFinanceiro` (quando há regularização).
Regras contextuais de limiar (`pesaRegrasContexto`)
Formato:
```json
{
"nome": "Regra opcional",
"curso": "Opcional",
"turno": "Opcional",
"campus": "Opcional",
"limiarCritico": 70,
"limiarAlto": 50,
"limiarMedio": 36,
"deltaMudancaMin": 5
}
```
Regra mais específica vence (prioridade: campus > turno > curso).
Classificação de faixa por score
Função: `classificarFaixaRiscoScore(score, L)`
- `score >= limiarCritico` => `critica`
- `score >= limiarAlto` => `alta`
- `score >= limiarMedio` => `media`
- caso contrário => `baixa`
Limiar padrão institucional (quando não há regra contextual):
- `limiarCritico: 70`
- `limiarAlto: 50`
- `limiarMedio: 36` (baixo risco: score ≤ 35)
Regras de nível no Centro de Alertas
Função: `gerarAlertasComNivel(...)` em `Untitled-1.js`
Gatilhos primários
- **Engajamento:** último acesso > 10 dias.
- **Financeiro:** mensalidade atrasada com valor em aberto >= `valorMinimoAtraso`.
- **Frequência:** faltas elevadas/críticas.
- **N1 em andamento:** N1 baixa em disciplina não concluída.
Regras de nível
- **Crítica** quando, por exemplo:
- `engajamentoPct <= 40`
- atraso financeiro + engajamento muito baixo
- faltas críticas
- N1 crítica (`< 2`)
- **Alta** quando, por exemplo:
- `engajamentoPct <= 50`
- atraso financeiro
- faltas altas
- N1 alta (`< 3`)
- **Risco inicial (`media`)** para alertas restantes sem condição de alta/crítica.
- **Baixo risco (`baixa`)** quando:
- não há gatilhos clássicos
- score cai na faixa baixa conforme limiares contextuais.
Papel do score (`scoreBase`)
- Sem gatilhos clássicos:
- score alto pode gerar alerta preditivo crítico.
- score baixo/contextual pode manter em `baixa`.
- Com gatilhos:
- score pode escalar `media` para `alta` e `alta` para `critica`.
Score de rematrícula — especificação v0.1 (proposta)
APROVADO v0.1 (gestão acadêmica + TI). Gate P1-001/P1-002 fechado.
Endpoints de score e fila liberados na Sprint S2 (remat_v0.1 heurístico). O período de
rematrícula continua configurável pela IES (§3.1).
1. Objetivo e distinção do score atual
- O score de risco/permanência atual (`calcularScoreRiscoPreditivo` em `Untitled-1.js`)
é uma heurística de risco no período corrente, usada no Centro de Alertas e na Predição.
- O score de rematrícula é um objeto novo e distinto: estima a probabilidade de o
estudante não se matricular no semestre seguinte, para priorizar contato preventivo.
- Os dois coexistem; o de rematrícula não substitui a heurística de alerta.
2. Glossário institucional de referência
Alinhado ao que o Atlas já usa em `index.html`:
- Abandono — estudante que não se matricula de um semestre para o outro (sem disciplina ativa).
- Evasão — estudante que não cursa nenhuma disciplina ao longo de três semestres letivos.
- Permanência — coorte com matrícula no semestre seguinte e vínculo ao anterior.
3. Label de não rematrícula (v0.1)
- População elegível: estudantes com matrícula ativa no semestre de referência
S
(ao menos uma disciplina ativa em S), exceto concluintes previstos para o fim de S.
- Evento positivo (label = 1, "não rematriculou"): ausência de matrícula / de disciplina
ativa em
S+1 dentro da janela de observação.
- Evento negativo (label = 0, "rematriculou"): ao menos uma disciplina ativa em
S+1
dentro da janela.
- Censura / exclusão da base de treino (não contam como abandono): trancamento formal,
conclusão/colação de grau, transferência externa documentada, óbito. Aplicável somente onde o campo existir —
ver gaps de dados.
3.1 Período de rematrícula configurável pela universidade
A IES pode (e deve) informar o período oficial de rematrícula por semestre.
Sem essa configuração, o sistema usa apenas o fallback.
Chave sugerida: localStorage.pesaPeriodoRematricula (espelhada no blob institucional quando houver
endpoint de config). Formato:
{
"semestreAlvo": "2026/2",
"inicio": "2026-07-01",
"fim": "2026-07-31",
"diasGracaAposFim": 15,
"inicioLetivoS1": "2026-08-04"
}
semestreAlvo — recomendado; semestre S+1 ao qual o período se aplica.inicio / fim — opcionais, preenchidos pela IES; janela oficial de rematrícula.diasGracaAposFim — opcional (padrão 15); dias após fim em que ainda se observa o label.inicioLetivoS1 — opcional; usado só no fallback quando fim não foi informado.
Cálculo da janela de observação (ordem de prioridade):
- Se a universidade informou
fim → data-limite = fim + diasGracaAposFim (padrão 15).
Fonte: configurado.
- Senão, se informou
inicioLetivoS1 → data-limite = inicioLetivoS1 + 45 dias.
Fonte: fallback_inicio_letivo.
- Senão → data-limite indefinida; o label não deve ser fechado automaticamente até a IES
completar o período. Fonte:
pendente_config.
Nota: o calendário acadêmico institucional (/api/config/calendario-academico) é conceito
separado de periodo_rematricula. Nas páginas analíticas, o semestre de referência vem do
resolver do calendário (ou fallback explícito à base), nunca da regra civil jan–jun / jul–dez.
Marcos analíticos (pontos de corte): diagnostico_inicial, acompanhamento_1,
acompanhamento_2, fechamento — datas dentro do período, em ordem. Detalhes e importação CRM:
ver documentacao-api (Calendário acadêmico).
4. Metadados exigidos do score
Toda predição de rematrícula deve carregar (para auditoria e monitoramento):
- `score` (0–100, risco de não rematrícula).
- `versao_modelo` (ex.: `remat_v0.1`).
- `calculado_em` (ISO 8601).
- `confianca` (cobertura de dados do estudante, 0–1).
- `label_janela` (objeto com os parâmetros efetivamente usados — ver contrato de API).
- `metodo`: `heuristica` (S2; não é ML treinado).
4.1 Pesos heurísticos `remat_v0.1`
- Financeiro: 25
- Engajamento/AVA: 25
- Frequência: 20
- Notas: 20
- Intervenções (resultado ruim): 10
5. Dataset base mínimo (P1-002)
Fonte canônica: blob `GET`/`PUT /api/estudantes-data` + `localStorage.pesaEstudantes`.
Chave de deduplicação: `PesaEstudantesMerge.chaveEstudante` (`uc:` ou `id:`).
Colunas do modelo CSV: `pesa-modelo-estudantes-csv.js`.
5.1 Features mínimas por eixo
- Identificação: `uc` / `id`, `nome`, `curso`, `nivel`, `campus`, `formatoCurso`,
`semestre`, `semestreCurso`, `turno`.
- Notas: `N1`/`N2`/`PI`/`N3` por disciplina; `nota` (agregada).
- Frequência: `presenca.total`, `presenca.faltas`.
- AVA / engajamento: `ava.acessos`, `ava.ultimoAcesso`, `interacoes.forum`,
`interacoes.materiais`, `interacoes.atividades`.
- Financeiro: `mensalidade.situacao`, `mensalidade.valorEmAberto`,
`mensalidade.mesesEmAtraso`, `tipoFinanceiro`.
- Intervenções: `intervencoes[]` (via fonte unificada `pesa-intervencoes-fonte.js` /
tabela `app_intervencao_registro`): tipo, resultado, data.
- Contexto de vulnerabilidade (opcional): `genero`, `etniaRaca`, `pcd`,
`primeiraGeracao`, `assistenciaEstudantil` — uso condicionado a política LGPD/antiviés.
5.2 Regras de qualidade do dataset
- Deduplicação: sem duplicidade crítica por `chaveEstudante`; semestre letivo
normalizado (`PesaEstudantesMerge.normalizarSemestreLetivo`).
- Cobertura mínima (proposto): identificação + curso em 100% das linhas;
notas, frequência, AVA e financeiro com preenchimento >= 70% na base de treino.
- Consistência temporal: features de `S` não podem usar dados posteriores ao início de
`S+1` (evitar vazamento do futuro).
- Gaps de dados conhecidos: não há hoje campo formal para trancamento/transferência/óbito;
até existir, esses casos entram como incerteza e devem ser sinalizados, não tratados como abandono.
5.3 Checklist de validação (manual nesta fase)
- Exportar/obter a base de estudantes (JSON de `pesaEstudantes` ou `/api/estudantes-data`).
- Conferir unicidade por `chaveEstudante` (sem duplicatas críticas).
- Medir cobertura por eixo e comparar aos limiares propostos (5.2).
- Validar normalização de `semestre`/`semestreCurso`.
- Registrar gaps (campos ausentes, censura indisponível) no aceite do gate.
6. Definition of Done do gate (S1)
- Spec de label e janela revisada e assinada por gestão acadêmica + TI.
- Dicionário de features e critérios de qualidade aceitos.
- Gaps de dados registrados com plano de mitigação.
- Só então liberar `P1-003` (endpoint de score) e `P1-004` (fila priorizada).
