Sistema de Atividades

As atividades do sistema são divididas em duas categorias, provas por PDF e provas por banco de questão, primeiro vamos analisar as páginas que envolvem a criação de provas por banco de questão

Questões

Para entrar no sistema de questões o usuário primeiro visualiza a página do banco de questões

Nomeclatura especial:

• Questão Coringa: É uma questão admnistrativa da plataforma que será usada em casos de provas com várias tentativas

Página do Banco de Questões

• Rota: /questions/models
• Permissões de visualização: >= Professores

Essa página tem como objetivo listar todas as questões da plataforma e possui vários filtros para ajudar o usuário a localizar as melhores questões para colocar em sua página. Dela podemos acessar as shows/edit/delete de cada questão e criar uma nova questão na plataforma.

Página de Criar Questões

• Rota: /questions/models/new
• Permissão: >= Professores

Na página de criar questão existem os seguintes campos: Título, Banco de Questão, Matéria, Nível, Habilidades, Texto da Questão, Dica, Interveção, Motivo do Error, É uma questão coringa (Só para admin) e uma última parte com a configuração para alternativa, ou seja selecionar se a questão é discursiva ou múltipla escolha, juntamente com os enunciados das alternativas e o tipo

Página de Editar Questão

• Rota: /questions/models/edit
• Permissão: Criador e admin

Mesmos campos do criar

Show das Questão (Somente para questões do banco)

• Rota: /questions/models/:id
• Permissão: Se a questão for global todos menos estudantes e pais, se não for global somente o dono da questão ou o admin Responsiva: Sim

Essa página é dividade em 2 seções:

• 1 Seção com informações gerais como criador, habilidade, nível, quantidade de alternativas
• 2 Seção: Com o enunciado e as alternativas

Criar atividades

Página de criar atividades com banco de questões

• Rota: /question_repos/new
• Permissão: >= Professor

Depois de criadas as questões é a hora de criar uma atividade do banco de questões. Essa é uma das melhores páginas da plataforma na qual o usuário pode arrastar as questões que deseja inserir na atividade e com um layout bem bacana com filtros é possível criar a atividade.

Página de criar ativiades com pdf

• Rota: exams/models/new
• Permissão: >= Professor
• Responsiva: Não

Nessa página é possível criar atividades por pdf, sendo necessário colocar o nome da atividade, o documento e o gabarito da atividade

Envio de ativiades

Página de envio de ativiades

• Rota: /exams/permissions/:id
• Permissão: Admin ou Company Manager
• Responsiva: Sim

Nessa página é possível enviar o acesso de determinada atividade os munícipios

Outras páginas

Show da atividade

• Rota: /exams/models/:id
• Permissão: Admin/Quem Criou a Atividade/Ou quem recebeu o acesso
• Responsiva: Sim

Essa página é divida em 4 seções:

• 1 Seção com informações gerais com o nome, tipo e criador da atividade
• 2 Seção com o gabarito
• 3 Seção com as atividades marcadas
• 4 Seção Atividades Concedidas (Só aparece para admin ou company manager)

---

Tipos Especiais de Atividades

Além das atividades tradicionais (banco de questões e PDF), a plataforma possui três tipos especiais de atividades implementadas desde 2024:

1. Fluência Leitora (Reading Fluency)

As atividades de Fluência Leitora foram implementadas para avaliar a capacidade de leitura dos alunos do Ensino Fundamental I, com questões específicas para cada ano escolar.

Modelo de Dados

Exams::ReadingFluencyExam

class Exams::ReadingFluencyExam < Exams::Model
  include ReadingFluencyQuestions

  belongs_to :school_subject  # Sempre "Fluência Leitora"

  # Callbacks
  before_validation :ensure_user_is_set
  before_validation :ensure_reading_fluency_subject
  after_create :create_default_questions
end

Características principais:

• Herda de Exams::Model com STI (Single Table Inheritance)
• Define automaticamente a disciplina como "Fluência Leitora"
• Cria automaticamente 5 questões padrão após a criação
• Usa 4 alternativas fixas (A, B, C, D)

ReadingFluencyQuestions (Concern)

Módulo que define as questões específicas para cada ano escolar:

• fundamental1: Anos iniciais (1º e 2º ano)
• fundamental2: 3º ano
• fundamental3: 4º ano
• fundamental4: 5º ano
• fundamental5: 6º ao 9º ano

Exemplo de questão (fundamental1):

{
  title: "Compreensão por ilustrações",
  description: "O aluno é capaz de compreender a ideia geral de uma história apenas pelas ilustrações ou pela escuta da leitura?",
  weight: 1
}

Fluxo de Criação

1. Criação da atividade: Professor seleciona "Atividade de fluência leitora" e o ano escolar
2. Geração automática: O sistema cria 5 questões específicas para o ano selecionado
3. Edição opcional: Professor pode editar os textos das questões via AVO (Admin)
4. Agendamento: Atividade pode ser agendada para turmas virtuais

Alternativas de Avaliação

Todas as questões de Fluência Leitora usam 4 alternativas fixas com pesos específicos:

• Alternativa A: Melhor desempenho (peso positivo alto: 0.8 a 1.4)
• Alternativa B: Desempenho bom (peso positivo baixo: 0.04 a 0.93)
• Alternativa C: Desempenho regular (peso negativo baixo: -0.72 a 0.46)
• Alternativa D: Pior desempenho (peso negativo alto: -1.5 a 0)

Nota pedagógica: As alternativas representam graus de desenvolvimento da fluência leitora, onde:

• A indica domínio consolidado da habilidade
• B indica desenvolvimento adequado
• C indica desenvolvimento inicial
• D indica não desenvolvido ou ausência da habilidade

Mudanças Recentes (2024-2026)

• Adição da 4ª alternativa: Antes eram apenas 3 alternativas, agora são 4 (A, B, C, D)
• Remoção do nível intermediário: Simplificação do sistema de níveis de 4 para 3 níveis (junho 2026)
  • Removido: "Leitor avançado" e nível intermediário
  • Mantido: Pré-leitor, Leitor iniciante, Leitor fluente
• Edição via AVO: Possibilidade de editar textos das questões pelo painel administrativo
• Alteração de pesos: Reajuste completa da matriz de pesos (maio 2026)
  • Questões 1-2: Amplitude 2.3 (ano anterior)
  • Questões 3-4: Amplitude 2.0 (ano atual)
  • Questão 5: Amplitude 1.4 (ano seguinte)
• Alteração de nomenclaturas:
  • Labels de relatórios mudados para "a, b, c, d" ao invés de nomes completos
  • Remoção de todas as referências ao "intermediário" do código
  • Mapeamento simplificado: apenas "advanced" → "fluent"
  • Labels dos resultados padronizados

Controllers Principais

• VirtualClassrooms::ReadingFluencyController: Questionário e visualização de exames
• ScheduledExams::ReadingFluencyResponsesController: Respostas dos alunos
• Reports::ReadingFluencyReportsController: Relatórios pedagógicos
• Avo::ReadingFluencyQuestionsController: Edição administrativa

Componentes Frontend

Localizados em app/components/reading_fluency/:

• cards/: Componentes de cartões (answer_table_card, fluency_level_card, etc.)
• graphs/: Gráficos de desempenho
• tables/: Tabelas de resultados
• badge_button/: Botões com badges

Services

• ReadingFluencyReportService: Gera relatórios completos de fluência
• ReadingFluencyCalculator: Cálculos estatísticos

Sistema de Pontuação e Pesos

ReadingFluencyCalculator

O cálculo do nível de fluência usa uma matriz de pesos específica para cada questão:

WEIGHT_MATRIX = {
  # Questões 1 e 2 (ano anterior)
  # Amplitude total: 2.3 | Step: ~0.76
  q1: {
    "Alternativa A" => 0.8,
    "Alternativa B" => 0.04,
    "Alternativa C" => -0.72,
    "Alternativa D" => -1.5,
  },
  # Questões 3 e 4 (ano atual)
  # Amplitude total: 2.0 | Step: ~0.66
  q3: {
    "Alternativa A" => 1.0,
    "Alternativa B" => 0.33,
    "Alternativa C" => -0.33,
    "Alternativa D" => -1.0,
  },
  # Questão 5 (ano seguinte)
  # Amplitude total: 1.4 | Step: ~0.46
  q5: {
    "Alternativa A" => 1.4,
    "Alternativa B" => 0.93,
    "Alternativa C" => 0.46,
    "Alternativa D" => 0,
  },
}

Níveis de Fluência (Mudança em 2026)

ANTES (até maio 2026):

• 4 níveis: Pré-leitor, Leitor iniciante, Leitor fluente, Leitor avançado
• Faixas: -5.0 a -3.5, -3.5 a 0.0, 0.0 a 3.5, 3.5 a 5.0

DEPOIS (junho 2026):

• 3 níveis: Pré-leitor, Leitor iniciante, Leitor fluente
• Faixas: -5.0 a -1.0, -1.0 a 1.0, 1.0 a 5.0

FLUENCY_LEVELS = [
  { level: :pre_readers, name: "Pré-leitor", min: -5.0, max: -1.0 },
  { level: :beginners, name: "Leitor iniciante", min: -1.0, max: 1.0 },
  { level: :fluent, name: "Leitor fluente", min: 1.0, max: 5.0 },
]

Casos especiais:

• Aluno que erra as 2 primeiras questões (Alternativa D em ambas) → Forçado para "Pré-leitor"
• Aluno estrela (todas Alternativa A) → Marcado como star_student
• Aluno em alerta (todas Alternativa D) → Marcado como alert_student

Relatórios Pedagógicos

Os relatórios de Fluência Leitora incluem:

• Estatísticas gerais: Total de alunos, percentuais por nível
• Dados por questão: Desempenho em cada habilidade avaliada
• Gráficos: Visualização do progresso da turma
• PDF export: Relatórios em PDF para impressão

Integração com Biblioteca de Conteúdos

Textos de fluência podem ser integrados com a biblioteca de conteúdos (eduq-library) para enriquecer as avaliações.

---

2. Ficha Avaliativa (Educação Infantil)

As Fichas Avaliativas foram desenvolvidas especificamente para a Educação Infantil, com critérios de avaliação diferenciados que se adequam às necessidades pedagógicas deste segmento.

Modelo de Dados

Exams::ChildEducationExam

class Exams::ChildEducationExam < Exams::Model
  # Child education exams don't need a school subject
  belongs_to :school_subject, optional: true

  def child_education?
    true
  end
end

Características principais:

• Não possui disciplina obrigatória (diferente das outras atividades)
• Usa 4 alternativas específicas para Educação Infantil
• Focada em desenvolvimento e habilidades infantis

Alternativas de Avaliação

As fichas avaliativas usam 4 níveis de desenvolvimento:

CHILD_EDUCATION_ALTERNATIVES = {
  1 => "Não realiza mesmo com intervenção",
  2 => "Necessita de intervenção",
  3 => "Em desenvolvimento",
  4 => "Realiza com Autonomia"
}

Fluxo de Criação e Aplicação

1. Criação da atividade: Professor seleciona "Ficha Avaliativa" (requer feature flag child_education)
2. Definição das questões: Professor adiciona questões específicas para Educação Infantil
3. Agendamento: Atividade pode ser agendada para turmas de Educação Infantil
4. Aplicação pelo professor: Professor responde as questões para cada aluno (não é autoavaliação)
5. Navegação entre questões: Interface com navegação por questão (anterior/próxima)
6. Finalização: Professor marca a avaliação como concluída
7. Feedback opcional: Professor pode adicionar feedback individualizado por questão

Controller: ScheduledExams::ChildEducationResponsesController

Rotas principais:

• edit: Formulário de avaliação (navegação por questão)
• update: Salvar respostas (permite edição incremental)
• finish: Marcar avaliação como concluída
• show: Visualizar respostas do aluno

Características da aplicação:

• Respostas são feitas pelo professor, não pelo aluno
• Navegação sequencial entre questões
• Suporte a múltipla escolha e questões discursivas
• Feedback por alternativa/response
• Redirecionamento inteligente (virtual classroom ↔ show page)

Diferenças em Relação às Atividades Tradicionais

• Sem disciplina: Atividades não estão vinculadas a disciplinas específicas (school_subject opcional)
• Avaliação descritiva: Foco em desenvolvimento de habilidades ao invés de notas numéricas
• Critérios específicos: Avaliação baseada em milestones de desenvolvimento infantil
• Aplicação pelo professor: Professor responde as questões observando o aluno (não é prova)
• Flexibilidade pedagógica: Permite acompanhamento individualizado contínuo
• Feature flag: Requer Flipper.enabled?(:child_education, user)

Critérios de Avaliação Específicos

As fichas avaliativas utilizam critérios baseados em milestones de desenvolvimento infantil:

Áreas de desenvolvimento avaliadas:

• Desenvolvimento motor (fine e gross): Coordenação, motricidade, destreza
• Desenvolvimento socioemocional: Interação social, emoções, autonomia
• Desenvolvimento da linguagem: Comunicação, expressão, vocabulário
• Desenvolvimento cognitivo: Pensamento, resolução de problemas, memória
• Habilidades de socialização: Trabalho em grupo, colaboração, empatia

Sistema de 4 níveis progressivos:

CHILD_EDUCATION_ALTERNATIVES = {
  1 => "Não realiza mesmo com intervenção",    # Necessita atenção individualizada
  2 => "Necessita de intervenção",            # Requer suporte frequente
  3 => "Em desenvolvimento",                   # Em progresso com suporte ocasional
  4 => "Realiza com Autonomia"                # Independente, consolidado
}

Progressão esperada:

• Alunos iniciam nos níveis 1-2 e progridem para 3-4 ao longo do ano
• O foco é mostrar evolução, não performance absoluta
• Avaliação contínua e formativa, não somativa

Controllers Principais

ScheduledExams::ChildEducationResponsesController

Responsável: Aplicação e correção das fichas avaliativas

Ações principais:

• show: Visualizar respostas de um aluno
• edit: Formulário de avaliação (navegação por questão)
• update: Salvar respostas incrementalmente
• finish: Finalizar avaliação do aluno

Características:

• Navegação entre questões (anterior/próxima)
• Suporte a questões de múltipla escolha e discursivas
• Feedback por alternativa/response individual
• Validação de permissões via ScheduledExams::ModelPolicy
• Redirecionamento inteligente após finalização

Permissões:

• Requer grading_child_exam? na policy
• Acesso controlado por feature flag child_education
• Professor da turma tem acesso automático

Services

ChildEducationReports::StatisticsService

Responsável: Cálculos estatísticos das fichas avaliativas

Métodos públicos:

def complete_statistics
  {
    total_alternatives: [alt1, alt2, alt3, alt4],  # Contagem absoluta
    questions_statistics: [...]                       # Dados por questão
  }
end

def chart_data
  {
    total_alternatives: [100, 75, 50, 25],  # Percentuais [autonomia, desenv, necessita, não_realiza]
    questions_data: [...]                     # Para gráficos
  }
end

Processamento:

• Conta respostas por alternativa (1-4)
• Calcula percentuais por questão
• Identifica alunos avaliados vs não avaliados
• Ordena do melhor para o pior desempenho

Dados por questão:

{
  question_id: 123,
  question: "Coordenação motora fina",
  description: "O aluno consegue segurar objetos...",
  values: [40, 30, 20, 10]  # [autonomia%, desenv%, necessita%, não_realiza%]
}

Services

ChildEducationReports::StatisticsService: Serviço especializado para cálculos estatísticos:

def complete_statistics
  {
    total_alternatives: total_alternatives_count,
    questions_statistics: questions_statistics
  }
end

def chart_data
  {
    total_alternatives: total_alternatives_values,
    questions_data: questions_chart_data
  }
end

Componentes Frontend

Localizados em app/components/reading_fluency/ (reutilizáveis):

• cards/: Componentes de visualização
• graphs/: Gráficos de desenvolvimento
• tables/: Tabelas de progresso

Relatórios Especializados

Os relatórios de Educação Infantil fornecem uma visão completa do desenvolvimento da turma:

Estatísticas Completas

• Totais por alternativa: Quantidade de alunos em cada nível
• Percentuais: Distribuição percentual por nível
• Alunos avaliados vs não avaliados: Identificação de pendências
• Dados por questão: Desempenho específico em cada habilidade

Gráficos de Desenvolvimento

Gráfico de barras por alternativa:

• Visualização da distribuição dos 4 níveis
• Ordenado do melhor (autonomia) para o pior (não realiza)
• Percentuais calculados automaticamente

Gráfico por questão:

• Desempenho da turma em cada habilidade específica
• Identificação de pontos fortes e fracos
• Comparativo entre diferentes áreas de desenvolvimento

Acompanhamento Evolutivo

• Progresso individual: Evolução do aluno ao longo do tempo
• Identificação de necessidades: Alunos que requerem mais intervenção
• Planejamento pedagógico: Base para intervenções futuras
• Comunicação com famílias: Dados concretos para reuniões

Componentes de Visualização

Localizados em app/components/reading_fluency/ (reutilizáveis):

• cards/badge_button: Botões com badges de status
• cards/: Vários tipos de cards de visualização
• graphs/: Gráficos de desempenho
• tables/: Tabelas de progresso detalhadas

Integração com Child Education Reports

As fichas avaliativas se integram com o sistema de relatórios pedagógicos da Educação Infantil, permitindo:

• Acompanhamento individual: Monitoring de cada aluno ao longo do ano letivo
• Identificação de intervenções: Alunos que necessitam de atenção pedagógica específica
• Comunicação familiar: Dados objetivos para reuniões com pais/responsáveis
• Planejamento pedagógico: Base para intervenções e adaptações curriculares
• Relatórios consolidados: Visão geral da turma e da escola

Mudanças Recentes (2024-2025)

Baseado no histórico de commits:

• Correções de relatórios: Fixes em cálculos estatísticos e visualizações
• Melhorias de responsividade: Ajustes de layout para diferentes dispositivos
• Cards de visualização: Adição de cards de atividade, turma e aluno
• Redirecionamento inteligente: Melhoria na UX de navegação
  • Se apenas uma turma disponível → redireciona para show page
  • Se múltiplas turmas → mantém na seleção
• Estilização consistente: Padronização visual com outros componentes

As fichas avaliativas se integram com o sistema de relatórios pedagógicos da Educação Infantil, permitindo:

• Acompanhamento individual do aluno
• Identificação de necessidades de intervenção
• Comunicação com famílias
• Planejamento pedagógico

---

3. Projeto de Redação (Essay Writing)

O projeto de Redação é uma funcionalidade major implementada em 2025 que integra correção automática por IA, correção manual, e relatórios especializados para avaliação de redações.

Modelo de Dados

Exams::EssayExam

class Exams::EssayExam < Exams::Model
  has_one :essay,
          class_name: "Essay",
          foreign_key: "exams_model_id",
          inverse_of: :exam,
          dependent: :destroy,
          autosave: true

  accepts_nested_attributes_for :essay, allow_destroy: true

  validates :essay, presence: true
  validate :essay_must_be_valid

  # Atividades de redação são sempre de Língua Portuguesa
  before_validation :assign_default_school_subject
end

Essay (Redação)

class Essay < ApplicationRecord
  belongs_to :exam, class_name: "Exams::EssayExam"
  belongs_to :genre  # Gênero textual
  has_many :essay_responses, dependent: :destroy

  validates :genre, presence: true
  validates :theme, presence: true

  def skills
    self.genre&.skills
  end
end

EssayResponse (Resposta do Aluno)

class EssayResponse < ApplicationRecord
  belongs_to :scheduled_exams_response
  belongs_to :essay
  has_many :skill_grades, class_name: "EssaySkillGrade", dependent: :destroy

  def corrected?
    skill_grades.any?
  end
end

EssaySkillGrade (Nota por Competência)

class EssaySkillGrade < ApplicationRecord
  belongs_to :essay_response
  belongs_to :skill
  after_commit :update_parent_grade

  private

  def update_parent_grade
    essay_response.scheduled_exams_response&.update_essay_exam_cached_grade
  end
end

Gêneros Textuais e Competências

Genre (Gênero Textual)

class Genre < ApplicationRecord
  has_many :genre_skills, dependent: :destroy
  has_many :skills, through: :genre_skills
  has_many :essays, dependent: :destroy

  validate :must_have_exactly_four_skills

  private

  def must_have_exactly_four_skills
    ids = skill_ids.reject(&:blank?)
    errors.add(:base, "Um gênero deve conter exatamente 4 habilidades") unless ids.count == 4
  end
end

Características:

• Cada gênero textual deve ter exatamente 4 competências (skills)
• Exemplos: Carta argumentativa, Artigo de opinião, Narrativa, etc.
• As competências são associadas via GenreSkill

Skill (Competência/Habilidade)

class Skill < ApplicationRecord
  has_many :genre_skills, dependent: :destroy
  has_many :genres, through: :genre_skills
  has_many :skill_standards, dependent: :destroy

  validates :name, presence: true
  validates :description, presence: true
end

Edição de Critérios e Competências

Gerenciamento de Gêneros Textuais

Controller: Essays::GenresController

Rotas disponíveis:

• index: Lista todos os gêneros textuais cadastrados
• show: Visualiza gênero e suas 4 competências associadas
• new: Formulário de criação de novo gênero
• edit: Editar gênero (nome e competências)
• create: Criar novo gênero
• update: Atualizar gênero existente
• destroy: Deletar gênero (com confirmação)

Interface:

• Table listing com busca por nome
• Modal de criação de skills inline
• Options menu com Editar/Deletar
• Validação: gênero deve ter exatamente 4 skills

Validação automática (junho 2026):

class Genre < ApplicationRecord
  validate :must_have_exactly_four_skills

  def must_have_exactly_four_skills
    ids = skill_ids.reject(&:blank?)
    errors.add(:base, "Um gênero deve conter exatamente 4 habilidades") unless ids.count == 4
  end
end

Gerenciamento de Competências (Skills)

Controller: Essays::SkillsController

Funcionalidades:

• Criar novas competências (skills)
• Editar competências existentes
• Reutilizar competências entre gêneros diferentes

Atributos da competência:

• name: Nome da competência (ex: "Coerência Textual")
• description: Descrição detalhada do que é avaliado

Compartilhamento de critérios:

• Skills podem ser associadas a múltiplos gêneros via GenreSkill
• Permite padronização de critérios em toda a plataforma
• Exemplo: "Coerência" pode ser usada em Carta, Artigo, Narrativa, etc.

Benefícios do compartilhamento:

• Consistência na avaliação
• Manutenção simplificada (alterar em um lugar, reflete em todos)
• Comparação justa entre diferentes gêneros textuais
• Acúmulo de dados históricos por competência

Integração com AVO

Painel administrativo para gerenciamento:

• Avo::SkillsController: CRUD de skills
• Avo::GenresController: CRUD de gêneros textuais
• Avo::EssaySkillGradesController: Gestão de notas

Sistema de Notas

Pontuação por Competência (Mudança em Junho 2026)

ANTES (até junho 2026):

• Cada critério valia: 0, 25, 50, 75, 100 pontos
• Total: 400 pontos (4 critérios × 100)
• Labels: "Em branco", "Insatisfatório", "Razoável", "Bom", "Ótimo"

DEPOIS (junho 2026):

• Cada critério vale: 0, 10, 15, 20, 25 pontos
• Total: 100 pontos (4 critérios × 25)
• Labels: "Em branco/Fuga do tema", "Insatisfatório", "Razoável", "Bom", "Ótimo"

Mudança técnica:

# Helper de labels (antes)
when 25: "😞 Insatisfatório"
when 50: "😐 Razoável"
when 75: "😊 Bom"
when 100: "😍 Ótimo"

# Helper de labels (depois)
when 10: "😞 Insatisfatório"
when 15: "😐 Razoável"
when 20: "😊 Bom"
when 25: "😍 Ótimo"

Cálculo da nota final:

• Soma das 4 competências (máximo 100 pontos)
• Convertido para escala 0-10 para exibição
• Badge colors: 😞 Insatisfatório (vermelho), 😐 Razoável (amarelo), 😊 Bom (verde), 😍 Ótimo (azul)

Fluxo de Criação

1. Criação da atividade: Professor seleciona "Atividade de redação"
2. Definição do tema: Define o tema da redação (ex: "A importância do meio ambiente")
3. Seleção do gênero: Escolhe o gênero textual (carta, artigo, narrativa, etc.)
4. Competências automáticas: As 4 competências do gênero são automaticamente associadas
5. Agendamento: Atividade pode ser agendada para turmas

Fluxo de Correção

Correção Manual

Controller: Essays::EssayResponsesController

Rotas principais:

• grade_essay_response: Formulário de correção
• grade_essay_response_skills: Salvar notas das competências

Processo:

def grade_essay_response_skills
  ActiveRecord::Base.transaction do
    essay_response = @response.essay_response || @response.build_essay_response(essay: @response.scheduled_exam.exam.essay)
    essay_response.save! if essay_response.new_record?

    save_skill_grades(essay_response, @response)
  end

  redirect_to scheduled_exams_model_path(@response.scheduled_exam),
              notice: "Correção realizada com sucesso!"
end

Correção com IA

Job: Ai::GradeDiscursiveJob

Integração com Ruby LLM:

def perform(response_id, chat_id, input_value, metadata)
  response = Questions::DiscursiveResponse.find(response_id)
  chat = Chat.find(chat_id)

  chat.with_schema(AiDiscursiveGradingSchema)
  ai_response = chat.ask(input_value)

  # Extrai feedback, nota sugerida e estruturas detectadas
  content_data = JSON.parse(ai_response.content, symbolize_names: true)

  # Broadcast em tempo real via Turbo Streams
  broadcast_success(response, structured_response)
end

Schema de resposta da IA:

• is_valid_response: Se a resposta é válida
• feedback: Feedback textual gerado pela IA
• suggested_grade: Nota sugerida (0-1000)
• structures_detected: Estruturas textuais detectadas

Turbo Streams em tempo real:

Turbo::StreamsChannel.broadcast_replace_to(
  "discursive_analysis_#{response.id}",
  target: "discursive_analysis_result_#{response.id}",
  html: result_html
)

Componentes de Avaliação

EssayPaper::Component

Componente para exibição e edição de redações:

class EssayPaper::Component < ApplicationViewComponent
  extend Dry::Initializer

  option :form, optional: true
  option :attribute, optional: true
  option :value, optional: true
  option :placeholder, Types::String, default: proc { "Inicie sua redação aqui" }
  option :line_count, Types::Integer, default: proc { 30 }
  option :disabled, Types::Bool, default: proc { false
end

Características:

• Folha de redação com linhas pontilhadas
• Área de texto com contador de linhas
• Estilização com bordas arredondadas
• Integração com formulários Rails

Controllers Principais

• Essays::EssayResponsesController: Correção manual e IA
• Exams::EssayModelsController: Criação e edição de redações
• Avo::EssaysController: Gestão administrativa
• Avo::EssaySkillGradesController: Gestão de notas

Services

ExamReports::EssayReports: Serviço especializado para relatórios de redação:

def self.generate(scheduled_exam)
  {
    total_students: total_students,
    grade_distribution: grade_distribution,
    skill_data: calculate_skill_performance(scheduled_exam),
    average_grade: calculate_average_grade(scheduled_exam)
  }
end

Distribuição de Notas

Classificação dos alunos em faixas de desempenho:

• Abaixo do Básico: 0-24.9 pontos
• Básico: 25.0-49.9 pontos
• Adequado: 50.0-74.9 pontos
• Avançado: 75.0-100 pontos

Relatórios Específicos

Relatório de Redação com PDF

Controller: Reports::EssayReportsController

Funcionalidades:

• Estatísticas gerais: Média da turma, distribuição de notas
• Dados por competência: Desempenho em cada habilidade
• Gráficos: Visualização comparativa
• PDF export: Relatórios em PDF com logo da EduQ

Gráficos e Estatísticas

Distribuição de notas:

• Gráfico de barras com 4 faixas (Abaixo do básico, Básico, Adequado, Avançado)
• Contagem de alunos em cada faixa
• Percentuais calculados automaticamente
• Identificação de alunos não avaliados

Desempenho por competência:

{
  skill_name: "Coerência Textual",
  skill_description: "Organização lógica das ideias...",
  chart_data: {
    labels: ["😊 Ótimo", "🙂 Bom", "😐 Razoável", "😟 Insatisfatório", "😓 Não avaliado"],
    values: [5, 8, 3, 2, 1],  # Número de alunos em cada nível
    colors: ["#73C0DD", "#32D583", "#FEC84B", "#F97066", "#D0D5DD"]
  }
}

Comparativos

Comparativo entre turmas:

• Médias de diferentes turmas no mesmo gênero textual
• Identificação de turmas com melhor/pior desempenho
• Análise de evolução ao longo do ano

Comparativo temporal:

• Evolução dos alunos ao longo do semestre/ano
• Identificação de alunos que mais melhoraram
• Acompanhamento de alunos persistentes em níveis baixos

Comparativo por competência:

• Identificação de competências com maior dificuldade
• Foco pedagógico em habilidades específicas
• Análise da correlação entre diferentes competências

Remoção de componentes (2026):

• Removido: school_class_essay_performance partial
• Motivo: Simplificação e melhoria de performance
• Substituído por: Relatórios mais eficientes via ExamReports::EssayReports

Integração com Biblioteca de Conteúdos

Redações podem ser integradas com a biblioteca de conteúdos (eduq-library) para:

• Seleção de temas predefinidos
• Templates de gêneros textuais
• Exemplos de redações modelo

Mudanças Recentes (2025-2026)

Troca na Ordenação do Cabeçalho (2025)

• ANTES: Tema à direita
• DEPOIS: Tema à esquerda (melhor UX)

Marcação Visual de Hover (2025)

• Adicionado feedback visual nas opções com hover effects
• Melhora na usabilidade da interface

Divisão das Notas (Junho 2026)

• ANTES: 0, 25, 50, 75, 100 pontos por critério (total 400)
• DEPOIS: 0, 10, 15, 20, 25 pontos por critério (total 100)
• Motivo: Padronização com outras atividades e melhor granularidade

Correção da Nota Final (2026)

• Bug corrigido no cálculo da nota final
• Implementação de update_essay_exam_cached_grade
• Job: UpdateEssayExamGradeCacheJob

Adição da Logo da EduQ no PDF (2025)

• Relatórios PDF agora incluem logo oficial da EduQ
• Padronização de identidade visual

Melhorias de Validação (Junho 2026)

• Refactor de validação de gênero skills
• Movido do controller para o model Genre
• Mensagens de erro mais claras
• Validação: exatamente 4 skills por gênero

Melhorias de Layout (Junho 2026)

• Responsividade aprimorada em views de gênero
• Layout melhorado em index e show de genres
• Componentes mais consistentes

Compartilhamento de Critérios (2025)

• Possibilidade de compartilhar competências entre redações
• Edição de critérios em lote via AVO
• Padronização de avaliação

Correções de Bug (2026)

• Fix em correção presencial de redações
• Fix em agendamento em lote de redações
• Melhoria no cálculo de médias em relatórios

Serviços de Relatórios

ExamReports::EssayReports

module ExamReports::EssayReports
  def self.generate(scheduled_exam)
    total_students = scheduled_exam.scheduled_exam_students.count
    grade_distribution = calculate_grade_distribution(scheduled_exam)
    skill_data = calculate_skill_performance(scheduled_exam)

    {
      total_students: total_students,
      grade_distribution: grade_distribution,
      skill_data: skill_data,
      average_grade: calculate_average_grade(scheduled_exam)
    }
  end

  def self.calculate_skill_performance(scheduled_exam)
    skills = scheduled_exam.exam.essay.skills
    all_responses = scheduled_exam.responses.includes(essay_response: :skill_grades)

    skill_performance = {}

    skills.each do |skill|
      # Calcula distribuição de notas para cada competência
      # (😊 Ótimo, 🙂 Bom, 😐 Razoável, 😟 Insatisfatório, 😓 Não avaliado)
    end

    skill_performance
  end
end

Integração com IA

Ai::GradeDiscursiveJob

Features:

• Correção automática usando Claude API
• Geração de feedback personalizado
• Detecção de estruturas textuais
• Cálculo automático de notas por competência
• Processamento assíncrono com Sidekiq

Controle de custos:

• Controle de créditos por município
• Registro de transações (AdminTransaction)
• Cálculo de custos em microcents (USD)
• Acompanhamento de tokens de input/output

Ruby LLM Integration:

chat.with_schema(AiDiscursiveGradingSchema)
ai_response = chat.ask(input_value)

# Custos são calculados e registrados
cost_microcents = LlmCostCalculator.calculate_cost(ai_result)
transaction.update(usd_microcents_cost: cost_microcents)

---

Comparativo entre Tipos de Atividades

Característica	Fluência Leitora	Ficha Avaliativa	Redação
Disciplina	Fluência Leitora	Não aplicável	Língua Portuguesa
Alternativas	4 fixas (A-D)	4 níveis de desenvolvimento	Não se aplica
Anos escolares	Fundamental I (1-9)	Educação Infantil	Fundamental II e Médio
Modelo de dados	Exams::ReadingFluencyExam	Exams::ChildEducationExam	Exams::EssayExam
Integração IA	Não	Não	Sim (correção automática)
Relatórios	ReadingFluencyReportService	ChildEducationReports	ExamReports::EssayReports
Edição via AVO	Sim	Não	Sim
Pontuação	Por alternativa	Por nível de desenvolvimento	Por competência (0-2.5)
Implementação	2024	2024	2025

Considerações Finais

Os três tipos especiais de atividades representam um avanço significativo na plataforma, permitindo:

1. Avaliação especializada: Cada tipo de atividade tem critérios específicos para seu público-alvo
2. Integração com IA: Redações utilizam IA para correção automática com feedback personalizado
3. Relatórios pedagógicos: Serviços especializados para cada tipo de atividade
4. Flexibilidade pedagógica: Professores podem adaptar avaliações conforme necessário
5. Acompanhamento evolutivo: Identificação de necessidades de intervenção pedagógica

Estas funcionalidades estão em constante evolução, com melhorias contínuas baseadas no feedback de professores e gestores pedagógicos.