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_idviaresponse.unit_id→plan_topology_resolver;sourceviaresponse.category;exam_typeviaresult.slot_type. - Simulado Escrito (Geral + subtipos): granularidade de
result—exam_typeviaslot.ctx_subtype(defaultdiscursivase ausente);module_idviaslot.flowref;discipline_idvia o JSON legado emslot.scope, resolvendo cadadiscipline_idnumberpelo mesmo mapa queby_discipline[]/resolve_by_unit()já usam (plan_topology_resolver::resolve_discipline_id_by_idnumber(), lido dostudent_plan.sequence.preview) — garante que tododiscipline_iddabreakdown[]esteja no mesmo espaço de id (id de categoria do Moodle), e não no PK interno do itemdiscipline. Idnumber sem entrada na topologia do Plano é ignorado. (A tabela normalizadaslot_scope_ref_entityexiste no código mas não é populada em produção.) Cada resultado gera também uma linha agregada comexam_type: "exam_written"(Geral) além da linha do subtipo específico.
breakdown[]não é comparável comby_module/by_sourceO
scoredas linhas de questão fechada dabreakdown[]é acurácia por resposta (100 ou 0 porresponse, depois a média) — métrica diferente deby_module[].by_exam_type[].score, que é a média deresult.nota_real(podendo incluir bônus/fatores de ajuste), e deby_source[].score, que é acurácia sobre todas as sessões elegíveis (inclusivegeneral_review, sem exigirunit_idresolvível na topologia).Somar ou tirar média das linhas da
breakdown[]não reproduz os números deby_module/by_source. São visões deliberadamente diferentes do desempenho, não duas representações do mesmo número: abreakdown[]exigeunit_idresolvível na topologia e excluigeneral_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(scopeoverall). Estratégia invalidate-on-write:activity_completedmarca o snapshot como inválido (async, adhoc task) → o próximoGET /performancerecomputa lazy e regrava. Leituras seguintes = SELECT do JSON. - Frescor por semana: o snapshot também é considerado stale quando sua semana ISO (
date('o-W')degenerated_at) difere da semana atual — garante queweekly.currentnã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