📊 Refatoração do Sistema de Estatísticas do Formulário

[FernandoAlmeidaPinto]

🧠 Contexto

Atualmente, as estatísticas exibidas nas telas de Processo Seletivo e Turmas são baseadas em dados armazenados como JSON serializado em texto no PostgreSQL, contendo perguntas e respostas dos alunos.

Esse modelo surgiu quando:

• As perguntas eram hardcoded no frontend
• O sistema tinha controle total sobre:
  • quais perguntas existiam
  • quais respostas eram possíveis

Com a evolução do sistema:

• As perguntas passaram a ser gerenciadas dinamicamente via vcnafacul-form
• O frontend deixou de conhecer previamente a estrutura do formulário
• O modelo atual de estatísticas se tornou limitado, frágil e pouco escalável

---

🚨 Problemas Identificados

1. Falta de estrutura para análise

• Respostas armazenadas como JSON em texto
• Não existe uma visão agregada por pergunta
• Dificuldade de evoluir analytics

---

2. Acoplamento antigo com frontend

• Lógica de gráficos dependia de perguntas fixas
• Agora as perguntas são dinâmicas → quebra do modelo anterior

---

3. Responsabilidade mal distribuída

• Frontend tenta interpretar dados brutos
• Backend não fornece dados prontos para visualização

---

4. Baixa flexibilidade

• Não é possível:
  • configurar gráficos
  • adaptar visualização por formulário
  • reutilizar lógica entre Processo Seletivo e Turmas

---

🎯 Objetivo da Refatoração

Criar um sistema de estatísticas:

• baseado em perguntas dinâmicas
• com agregação padronizada no backend
• com configuração persistida por formulário snapshot (formfull)
• com suporte a diferentes tipos de visualização (gráficos)

---

🧱 Proposta de Solução

🔹 1. Centralizar analytics no vcnafacul-form

O serviço vcnafacul-form já é responsável por:

• perguntas
• respostas
• ranqueamento

👉 Portanto, ele também será responsável por:

• agregação dos dados
• storage de preferências

---

🔹 2. Introduzir configuração de analytics no formfull

Cada snapshot de formulário (formfull) terá sua própria configuração:

analyticsConfig: {
  questions: [
    {
      questionId: string
      chartType: "pie" | "bar" | "histogram"
    }
  ]
}

---

🔹 3. Criar endpoint de analytics

GET /formfull/:id/analytics

---

🔹 4. Padronizar contrato de resposta

type QuestionAnalyticsSchema = {
  questionId: string
  questionText: string
  answerType: "boolean" | "number" | "option"

  chartType: "pie" | "bar" | "histogram"

  data: {
    labels: string[]
    values: number[]
  }
}

---

🔹 5. Agregação por tipo de pergunta

Cada tipo de pergunta terá uma estratégia própria:

• boolean

  • contagem de true/false

• option (single)

  • contagem por alternativa

• option (multiple / collection)

  • contagem de ocorrências por alternativa

• number

  • distribuição (ex: histograma)

• text

  • (avaliar: ignorar ou implementar análise simples)

---

🎨 Frontend

Modo Visualização

• Consome apenas o endpoint /analytics
• Renderiza os gráficos com base no chartType

Modo Edição

• Usuário pode:
  • selecionar perguntas
  • escolher tipo de gráfico
• Salva configuração no formfull.analyticsConfig

---

📊 Definição de gráficos (Frontend)

ChartRegistry = {
  pie: {
    supportedAnswerTypes: ["boolean", "option"]
  },
  bar: {
    supportedAnswerTypes: ["boolean", "option"]
  },
  histogram: {
    supportedAnswerTypes: ["number"]
  }
}

---

⚙️ Cache

• O cache permanece na api-vcnafacul
• Cache baseado na resposta do endpoint /analytics
• Estratégia inicial simples (ex: TTL)

---

🚫 Fora do Escopo

• Builder estilo Excel
• Drag & drop
• Analytics cross-form

---

🚫 Fora do Escopo

A reutilização do sistema de estatísticas para Turmas não será abordada nesta refatoração.

A análise de Turmas envolve um domínio diferente, baseado em:

• desempenho em simulados
• evolução em redações
• presença e engajamento

Esses dados exigem um modelo próprio de analytics, que poderá ser tratado em uma futura iniciativa.

---

🚀 Evoluções Futuras

• Uso em Turmas
• Dashboards customizados
• Filtros por aluno
• Comparações entre processos

---

✅ Benefícios

• Backend centraliza lógica
• Frontend simplificado
• Sistema flexível
• Base para evolução

---

❓ Pontos em Aberto

• Como tratar texto?
• Versionamento de config?
• Cache ideal?
• Múltiplos gráficos por pergunta?

---

🧭 Próximos Passos

1. Validar com time
2. Definir MVP
3. Quebrar em tasks

---

💬 Considerações Finais

Refatoração estrutural, não só visual.