Skip to content

Contrato — Desempenho (Performance)

Contrato — Desempenho (Performance)

Status: Implementado Termos: Desempenho (Visão), Métrica de Desempenho, Desempenho Geral, Desempenho por Disciplina, Desempenho por Módulo, Desempenho por Tipo de Simulado, Desempenho por Tipo de Fonte, Desempenho da Prática com Flashcards, Progresso do Plano de Estudo, Média Aritmética Simples Controller: performance_api_controller Service: performance_view_service → consolidation_engine_service (Motor de Consolidação de Métricas, ADR-70) UC: UC-007 — Desempenho

Endpoints

Método Path Função
GET /api/v1/platform/study/{enrolment_id}/performance Todas as dimensões de desempenho do Aluno em uma resposta

Auth: wstoken (ver autenticacao.md). Contexto = enrolment_id na rota.

O backend agrega todas as dimensões num único payload (REF-90-A §16): o frontend não faz N chamadas por dimensão.

GET /study/{enrolment_id}/performance

Response 200

{
  "enrolment_id": 123,

  "overall": {
    "score": 72.5,
    "trend": "up",
    "trend_delta": 3.1,
    "total_activities": 48,
    "total_time_minutes": 1260
  },

  "by_discipline": [
    {
      "discipline_id": 100,
      "name": "Direito Civil",
      "score": 70.0,
      "trend": "stable",
      "units_studied": 8,
      "units_total": 8
    }
  ],

  "by_module": [
    {
      "module_id": 1,
      "module_name": "Módulo 1",
      "score": 76.7,
      "units_studied": 12,
      "by_discipline": [
        { "discipline_id": 100, "name": "Direito Civil", "score": 70.0 },
        { "discipline_id": 200, "name": "Direito Penal", "score": 90.0 }
      ],
      "by_exam_type": [
        { "type": "exam_objective", "label": "Simulado Objetivo", "score": 80.0, "count": 1 },
        { "type": "exam_truefalse", "label": "Simulado VF", "score": 92.0, "count": 4 },
        { "type": "exam_written", "label": "Simulado Escrito", "score": null, "count": 0 }
      ]
    }
  ],

  "by_exam_type": [
    { "type": "exam_objective", "label": "Simulado Objetivo", "score": 80.0, "count": 5 },
    { "type": "exam_truefalse", "label": "Simulado VF",       "score": 74.0, "count": 9 },
    { "type": "exam_written",   "label": "Simulado Escrito",  "score": 68.0, "count": 3 }
  ],

  "by_source": [
    { "source": "legislation",   "total": 120, "correct": 90, "score": 75.0 },
    { "source": "doctrine",      "total": 40,  "correct": 28, "score": 70.0 },
    { "source": "jurisprudence", "total": 30,  "correct": 18, "score": 60.0 }
  ],

  "breakdown": [
    { "module_id": 3, "discipline_id": 10, "exam_type": "exam_truefalse", "source": "legislation", "score": 57.6, "count": 12 },
    { "module_id": 2, "discipline_id": 7, "exam_type": "exam_written_peca_pratica", "score": 55.0, "count": 1 }
  ],

  "flashcard_practice": {
    "sessions_total": 12,
    "cards_reviewed": 340,
    "cards_correct": 270,
    "cards_incorrect": 70,
    "accuracy": 79.4,
    "trend": "up"
  },

  "progress": {
    "percentage": 41.2,
    "units_studied": 33,
    "units_total": 80,
    "units_exempted": 4
  },

  "weekly": {
    "current":  { "week": "2026-22", "avg_score": 74.0, "avg_exam_time_min": 38, "units_completed": 6, "units_reviewed": 2 },
    "previous": { "week": "2026-21", "avg_score": 68.0, "avg_exam_time_min": 42, "units_completed": 4, "units_reviewed": 1 },
    "deltas":   { "avg_score": 6.0,  "avg_exam_time_min": -4, "units_completed": 2, "units_reviewed": 1 }
  }
}

overall — Desempenho Geral

Média Aritmética Simples das notas por Unidade (Nota Ajustada consolidada via classification).

Campo Tipo Semântica
score number (0–100) Média não ponderada das NAs por Unidade.
trend up | down | stable Direção vs. últimas N amostras (limiar 2.0).
trend_delta number Diferença da última amostra vs. média anterior.
total_activities integer Resultados de atividade registrados no Plano.
total_time_minutes integer Soma do tempo de execução (min).

by_discipline[] — Desempenho por Disciplina

Média das notas das Unidades classificadas de cada Disciplina. O vínculo Unidade → Disciplina vem do plan_topology_resolver (sequence.preview), não de unit.parent. Escopo: somente Disciplinas dos Módulos materializados; Unidades de Módulos futuros (ex.: Dispensa antecipada) ficam fora.

Campo Tipo Semântica
discipline_id integer ID da categoria/Disciplina.
module_id integer Número do Módulo (campo novo).
name string Nome da Disciplina.
score number (0–100) Média das NAs das Unidades estudadas.
trend up | down | stable Tendência (atualmente stable).
units_studied integer Unidades com classificação registrada.
units_total integer Total considerado na dimensão.

by_module[] — Desempenho por Módulo

Fonte = classification (nota consolidada por Unidade), mapeada ao Módulo home pelo plan_topology_resolver (sequence.preview × Fluxos de Módulo). A Classificação é a verdade por-Unidade — Simulados agregados (DI/SVD/Objetivo) não carregam unit_id. Agregação em camadas: nota por Unidade → média por Disciplina → média do Módulo (Média Aritmética Simples). Escopo: somente Módulos materializados. Ordenado por module_id.

by_exam_type[] aninhado é a Projeção de Desempenho por Simulado e Módulo (exam_modperf): sempre os três tipos de Simulado (Objetivo/VF/Escrito) por Módulo, com score/count quando realizado ou score=null/count=0 como placeholder — a UI exibe a progressão de Simulados por Módulo de forma estável. O Módulo do Resultado vem de slot.flowref → study_flow. Simulado VF agrega os questionários V/F do Módulo — DI + SVD + VF avulso (espelha a Revisão V/F, que combina DI/SVD por Módulo); Objetivo = exam_objective; Escrito = exam_written.

Campo Tipo Semântica
module_id integer Número do Módulo (module_number do Fluxo).
module_name string Rótulo amigável (Módulo N).
score number (0–100) Média das notas de Unidade do Módulo.
units_studied integer Unidades distintas com Classificação no Módulo.
by_discipline[] object[] Quebra por Disciplina dentro do Módulo.
by_discipline[].discipline_id integer ID da Disciplina.
by_discipline[].name string Nome da Disciplina.
by_discipline[].score number (0–100) Média das Unidades da Disciplina no Módulo.
by_exam_type[] object[] Até 6 itens: Objetivo, VF, Escrito (Geral) e subtipos (Discursiva, Dissertação, Peça Prática).
by_exam_type[].type string exam_objective | exam_truefalse | exam_written | exam_written_discursiva | exam_written_dissertacao | exam_written_peca_pratica.
by_exam_type[].label string Rótulo (Simulado Objetivo/VF/Escrito, Discursiva, Dissertação, Peça Prática).
by_exam_type[].score null|number Média nota_real no Módulo; null se não realizado.
by_exam_type[].count integer Simulados do tipo realizados no Módulo (0 = placeholder para os 3 principais).

by_exam_type[] — Desempenho por Tipo de Simulado

Média de nota_real agrupada por slot_type. Atividades sem nota (flashcard, guided) são excluídas.

Esta dimensão do topo não quebra o Simulado Escrito por subtipo: os subtipos (exam_written_discursiva/_dissertacao/_peca_pratica) aparecem apenas em by_module[].by_exam_type[] e em breakdown[].

Campo Tipo Semântica
type string diagnostic_initial|diagnostic_verify|exam_objective|exam_truefalse|exam_written|general_review.
label string Rótulo amigável (DI, SVD, Simulado Objetivo…).
score number (0–100) Média das nota_real do tipo.
count integer Resultados considerados.

by_source[] — Desempenho por Tipo de Fonte

Média Aritmética Simples de acertos por categoria da Questão, lendo a category congelada em cada response (legislation/doctrine/jurisprudence). Conta toda Resposta elegível (Módulo + RGs, sem dedupe). Acerto = correct=1 e não marcado “não sei” (notsure=0). Categorias sem nenhuma resposta são omitidas.

Campo Tipo Semântica
source string legislation (Lei) | doctrine (Doutrina) | jurisprudence (Jurisprudência).
total integer Respostas elegíveis da fonte.
correct integer Acertos (excluindo “não sei”).
score number (0–100) correct / total * 100.

breakdown[] — cruzamento de dimensões

Tabela de fatos plana — cada linha é uma combinação (Módulo, Disciplina, Tipo de Simulado, Fonte) com nota e contagem agregadas. Permite cruzamentos arbitrários no frontend sem necessidade de novos campos no contrato. Combinações sem dado são omitidas (nunca score: null).

Campo Tipo Semântica
module_id integer Número do Módulo (module_number, igual a by_module[].module_id).
discipline_id integer ID da Disciplina/Matéria (mesmo campo, nomes diferentes por prova).
exam_type string diagnostic_initial|diagnostic_verify|exam_objective|exam_truefalse|exam_written|exam_written_discursiva|exam_written_dissertacao|exam_written_peca_pratica. Valores brutos — o front funde DI+SVD+VF em “V/F” como já faz hoje.
source string | omitido legislation|doctrine|jurisprudence. Ausente nas linhas de Simulado Escrito (qualquer exam_type que comece com exam_written) — não existe fonte pra prova redigida.
score number (0–100) Média das notas elegíveis da combinação.
count integer Quantidade de resultados/respostas elegíveis na combinação.

Origem das linhas:

  • V/F, Objetivo, DI, SVD: granularidade de response — module_id/discipline_id via response.unit_id → plan_topology_resolver; source via response.category; exam_type via result.slot_type.
  • Simulado Escrito (Geral + subtipos): granularidade de result — exam_type via slot.ctx_subtype (default discursiva se ausente); module_id via slot.flowref; discipline_id via o JSON legado em slot.scope, resolvendo cada discipline_idnumber pelo mesmo mapa que by_discipline[]/resolve_by_unit() já usam (plan_topology_resolver::resolve_discipline_id_by_idnumber(), lido do student_plan.sequence.preview) — garante que todo discipline_id da breakdown[] esteja no mesmo espaço de id (id de categoria do Moodle), e não no PK interno do item discipline. Idnumber sem entrada na topologia do Plano é ignorado. (A tabela normalizada slot_scope_ref_entity existe no código mas não é populada em produção.) Cada resultado gera também uma linha agregada com exam_type: "exam_written" (Geral) além da linha do subtipo específico.

breakdown[] não é comparável com by_module/by_source

O score das linhas de questão fechada da breakdown[] é acurácia por resposta (100 ou 0 por response, depois a média) — métrica diferente de by_module[].by_exam_type[].score, que é a média de result.nota_real (podendo incluir bônus/fatores de ajuste), e de by_source[].score, que é acurácia sobre todas as sessões elegíveis (inclusive general_review, sem exigir unit_id resolvível na topologia).

Somar ou tirar média das linhas da breakdown[] não reproduz os números de by_module/by_source. São visões deliberadamente diferentes do desempenho, não duas representações do mesmo número: a breakdown[] exige unit_id resolvível na topologia e exclui general_review; as outras duas não.

flashcard_practice — Desempenho da Prática com Flashcards

Estatísticas Gerais de Flashcards acumuladas (sem nota_real).

Campo Tipo Semântica
sessions_total integer Sessões de prática.
cards_reviewed integer Cartões revisados (total).
cards_correct integer Acertos acumulados.
cards_incorrect integer Erros acumulados.
accuracy number (0–100) cards_correct / cards_reviewed.
trend up | down | stable Tendência da acurácia.

progress — Progresso do Plano de Estudo

Campo Tipo Semântica
percentage number (0–100) units_studied / units_total.
units_studied integer Unidades distintas com Classificação no Plano inteiro (inclui Dispensa — a Unidade dispensada já avançou). Fonte: Classificação (não result.unit_id, que é nulo em Simulado agregado).
units_total integer Total de Unidades do Plano (todos os Módulos do sequence.preview, materializados ou não; exclui Fluxos Revisionais).
units_exempted integer Unidades Economizadas: decidido pela Disciplina, tudo-ou-nada. Quando o DI da Disciplina (no Módulo) é Avançado e o SVD dela é Avançado ou Intermediário, todas as Unidades dela economizam; senão, nenhuma. Subconjunto de units_studied.

weekly — Semana calendário (atual vs. anterior)

Bucketiza result.completed_at por semana ISO (Segunda–Domingo, date('o-W')). Compara a semana corrente com a anterior + deltas.

Campo Tipo Semântica
current / previous object Métricas da semana atual / anterior.
*.week string Chave ISO ano-semana (ex.: 2026-22).
*.avg_score number (0–100) Média das nota_real das avaliações ocorridas na semana. Distinto de overall.score (que usa NA consolidada).
*.avg_exam_time_min integer Tempo médio (min) em Simulados (exam_objective/exam_truefalse/exam_written) da semana.
*.units_completed integer Unidades distintas cujo Resultado terminou (completed) na semana.
*.units_reviewed integer Unidades distintas revisadas (general_review) na semana.
deltas.* number/integer current - previous por métrica.

Unidades Economizadas por semana

Não há recorte semanal de Dispensa: a Dispensa é estado de Classificação (sem timestamp por evento). O total cumulativo permanece em progress.units_exempted.

Erros

HTTP error Causa
401 unauthorized wstoken ausente/inválido.
404 enrolment_not_found Matrícula não pertence ao usuário.

Sem Plano do Aluno (pré-onboarding), o payload retorna a forma vazia (overall.score=0, arrays vazios, progress zerado).

Invariantes / Cache

  • Resultado Elegível: médias só consideram resultados confiáveis da dimensão; acerto autorreportado de Flashcard não entra nas dimensões com nota_real.
  • Média Aritmética Simples: todas as dimensões agregadas usam média não ponderada do conjunto elegível.
  • Cache (ADR-70): snapshot consolidado persistido em report (scope overall). Estratégia invalidate-on-write: activity_completed marca o snapshot como inválido (async, adhoc task) → o próximo GET /performance recomputa lazy e regrava. Leituras seguintes = SELECT do JSON.
  • Frescor por semana: o snapshot também é considerado stale quando sua semana ISO (date('o-W') de generated_at) difere da semana atual — garante que weekly.current não congele ao virar a semana, mesmo dentro do TTL de 24h.

Referências

  • Source: classes/extensions/platform/controller/performance_api_controller.php
  • Calculators: classes/extensions/metrics/consolidation/service/{overall_performance,discipline_performance,by_module,by_exam_type,by_source,breakdown,flashcard_practice,weekly_trends}_calculator_service.php
  • Engine: classes/extensions/metrics/consolidation/service/consolidation_engine_service.php
  • Termos: glossário de Métricas
Navigation

Type to search…

↑↓ navigate↵ selectEsc close