Skip to content

Desempenho — filtros cruzados (Simulado, Fonte, Disciplina) + subtipos de Simulado Escrito

Desempenho — filtros cruzados (Simulado, Fonte, Disciplina) + subtipos de Simulado Escrito

  • Data: 2026-08-28
  • Escopo: local_helico (backend, contrato /performance) + app-helico (frontend, componentes de Desempenho)
  • Tipo: spec de design validada via brainstorming estruturado
  • Status: Implementado
  • Componentes alvo: ExamPerformanceSection (Desempenho por Simulado), PerformanceEfficiencySection (Desempenho por Tipo de Fonte), DisciplinePerformanceSection (Desempenho por Disciplina) — todos renderizados em /desempenho e em /area-do-aluno (mesmos componentes, uma correção cobre os dois).

1. Objetivo

Hoje três seções da tela de Desempenho têm pílulas de filtro secundário (Disciplina, Matéria, Fonte, Módulo) desenhadas na interface mas desabilitadas, porque o payload de GET /performance entrega cada dimensão numa gaveta separada, sem cruzamento (ver app-helico/docs/api-gaps-platform.md §8). Este documento especifica:

  1. Um novo campo breakdown[] no /performance — tabela de fatos plana que permite cruzar Módulo × Disciplina × Tipo de Simulado × Fonte sob demanda no frontend, sem precisar redesenhar o contrato a cada novo cruzamento pedido.
  2. A separação do Simulado Escrito (exam_written) em subtipos reais — hoje um balde único, mistura Discursiva/Dissertação/Peça Prática e atribui a nota de qualquer um deles a “Discursiva”.
  3. Habilitar as pílulas de filtro nos 3 componentes acima usando esse novo dado.

Não-objetivos: não altera overall, flashcard_practice, progress, weekly; não remove nenhum campo existente (mudança aditiva); não migra by_exam_type[]/by_source[] do topo para o novo formato — eles continuam servindo a visão sem filtro.

2. Decisões travadas

2.1 Contrato: tabela de fatos breakdown[], não aninhamento por tipo

Considerado aninhar (by_module[].by_exam_type[].by_discipline[]/by_source[]), mas com 4 dimensões cruzáveis (Módulo, Disciplina/Matéria, Fonte, Tipo de Simulado) espalhadas em 3 componentes, o aninhamento cresce a cada novo pedido e cada componente acaba com um formato diferente. breakdown[] — uma linha por combinação, .filter() no frontend — resolve os cruzamentos pedidos agora e qualquer um futuro sem novo contrato.

2.2 Vocabulário de subtipo do Simulado Escrito

discursiva | dissertacao | peca_pratica — o enum já aprovado em .vigim/ddd/linkml/enums/exam_type.linkml.yaml (ADR-60), já implementado na camada de execução (slot_context_exam_written::$subtype, persistido em ctx_subtype na metadata do slot). Não usa o vocabulário do cadastro de questão (WrittenStep.vue: dissertative|petition|opinion|sentence) — esse é um vocabulário de formato de questão individual, domínio diferente, fora de escopo aqui.

from_metadata() já faz 'ctx_subtype' ?? 'discursiva' — slots antigos (antes deste campo existir) resolvem como discursiva automaticamente. Sem necessidade de backfill ou migração de dado.

2.3 Simulado Escrito “Geral” cruza com Matéria também

exam_type = exam_written continua existindo como agregado das 3 subdivisões (média/contagem combinadas). Ele também recebe linhas de by_discipline no breakdown[] (mesmo mecanismo dos subtipos específicos) — comportamento uniforme com V/F e Objetivo, que sempre têm Matéria/Disciplina disponível.

2.4 Escopo: 3 componentes, Desempenho por Disciplina fica fora do breakdown[]

Desempenho por Simulado, Desempenho por Tipo de Fonte e Desempenho por Disciplina entram nesta entrega. Os dois primeiros usam breakdown[] (fonte: result/response de Simulados). O terceiro usa uma fonte de dado diferente — classification por Unidade estudada, não resultado de Simulado — e não tem exam_type/source naturais; ganha só um campo module_id a mais no by_discipline[] já existente (§5.3), sem entrar na tabela de fatos.

3. Contrato de API — GET /platform/study/{enrolment_id}/performance

3.1 Novo campo: breakdown[]

{
  "breakdown": [
    { "module_id": 3, "discipline_id": 10, "exam_type": "exam_truefalse", "source": "legislation", "score": 57.6, "count": 12 },
    { "module_id": 3, "discipline_id": 10, "exam_type": "exam_objective", "source": "doctrine", "score": 64.0, "count": 5 },
    { "module_id": 2, "discipline_id": 7,  "exam_type": "exam_written", "score": 61.0, "count": 3 },
    { "module_id": 2, "discipline_id": 7,  "exam_type": "exam_written_peca_pratica", "score": 55.0, "count": 1 },
    { "module_id": 2, "discipline_id": 9,  "exam_type": "exam_written_peca_pratica", "score": 55.0, "count": 1 }
  ]
}
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 — ver §2.4 do gap doc).
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 via EXAM_TYPE_BY_PLATFORM_TYPE.
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.

Combinações sem dado são omitidas — nunca score: null. Sem paginação/querystring de recorte nesta primeira versão: volume estimado (poucos módulos × poucas disciplinas × 8 exam_type, maioria vazia) fica bem abaixo do que justificaria recorte. Reavaliar se a verificação da matrícula 225 (§7) mostrar payload desproporcional.

3.2 Origem de cada linha

V/F, Objetivo, DI, SVD — granularidade de response (mesma tabela de origem do by_source[] do topo, mas conjunto elegível diferente: a breakdown[] exclui general_review e exige unit_id resolvível na topologia do Plano; o by_source[] do topo não exige nenhum dos dois. Os dois números não coincidem por construção — ver o aviso na seção breakdown[] de performance.md): para cada response elegível de uma sessão de Simulado fechado,

  • module_id/discipline_id vêm de response.unit_id → plan_topology_resolver (mesmo join do discipline_performance_calculator_service).
  • source vem de response.category (já usado no by_source_calculator_service).
  • exam_type vem do slot_type do result dono da sessão (join já existente em by_source_calculator_service: result → session_id → response[]).

Simulado Escrito (Geral + 3 subtipos) — granularidade de result (prova escrita não gera response por questão; correção é holística, ver exam_written_handler_service):

  • exam_type (subtipo) vem de slot.ctx_subtype, resolvido via result.slot_id → slot_service->find_by_id() — mesma chamada que by_module_calculator_service::exam_scores_by_module() já faz pra achar o módulo via flowref, sem query extra.
  • module_id vem do mesmo slot->get_flowref() → study_flow → module_number.
  • discipline_id vem do JSON legado em slot.scope ({"disciplines":[{"discipline_idnumber": "...", ...}]} — escrito por slot_generator_service; a tabela normalizada slot_scope_ref_entity existe no código mas nunca é populada em produção, achado durante a verificação da matrícula 225, ver §7 Achado 1), resolvendo cada discipline_idnumber para um ID numérico via o mesmo mapa do plan_topology_resolver que resolve_by_unit()/by_discipline[] já usam (resolve_discipline_id_by_idnumber(), lido do próprio student_plan.sequence.preview) — garante por construção o mesmo espaço de id em toda a breakdown[] (id de categoria do Moodle), não por coincidência (ver §7 Achado 4). Se o escopo cobrir mais de uma disciplina, a nota inteira da prova gera uma linha por disciplina (fan-out) — é mais grosso que o cruzamento por resposta do V/F/Objetivo (não decompõe uma nota única em pedaços por disciplina), mas reflete a realidade: a correção de uma prova escrita é holística, não há como saber quanto da nota veio de cada matéria.
  • Cada resultado de Simulado Escrito gera também uma linha agregada com exam_type: "exam_written" (Geral) além da linha do subtipo específico.
  • Sem source.

3.3 by_module[].by_exam_type[] — split de subtipo (independente do breakdown[])

A pílula de tipo em “Desempenho por Simulado” lê de by_module[].by_exam_type[], não do breakdown[]. Pra pílula oferecer Geral/Discursiva/Dissertação/Peça Prática como opções, esse campo — hoje sempre com 3 itens fixos (Objetivo/VF/Escrito) — passa a ter até 6 itens por Módulo:

"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": 58.0, "count": 3 },
  { "type": "exam_written_discursiva", "label": "Discursiva", "score": 60.0, "count": 1 },
  { "type": "exam_written_dissertacao", "label": "Dissertação", "score": 55.0, "count": 1 },
  { "type": "exam_written_peca_pratica", "label": "Peça Prática", "score": 59.0, "count": 1 }
]

Placeholder (score: null, count: 0) só para os 3 tipos “pai” que já existem hoje (Objetivo/VF/Escrito), mantendo compat com quem já lê esse campo assim; os 3 subtipos só aparecem quando count > 0 (evita 3 placeholders extras vazios em todo módulo).

3.4 by_discipline[] (topo) — module_id novo

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

Uma linha por (disciplina, módulo) em vez de uma por disciplina agregando todos os módulos — o frontend agrega ele mesmo quando nenhum módulo estiver selecionado (groupBy(discipline_id)), igual já faz hoje implicitamente ao consumir uma lista sem esse eixo.

4. Backend — serviços tocados

Serviço Mudança
by_module_calculator_service.php exam_scores_by_module() passa a ler ctx_subtype do $slot já carregado; build_exam_types() emite os subtipos + Geral quando houver dado.
by_discipline_calculator_service.php (discipline_performance_calculator_service.php) Expõe module_id por linha (já disponível na $topology via plan_topology_resolver) em vez de agregar direto.
novo breakdown_calculator_service.php Implementa dimension_key() === 'breakdown'. Constrói as linhas de V/F/Objetivo/DI/SVD (via response_service::find_by_session_ids(), igual by_source_calculator_service) e as de Simulado Escrito (via result_service::find_by_student_plan() + slot_service::find_by_id(), igual by_module_calculator_service). Registrado em consolidation_engine_service como mais uma dimensão do payload consolidado.
by_exam_type_calculator_service.php, by_source_calculator_service.php (topo) Sem mudança — continuam alimentando quem já lê by_exam_type[]/by_source[] sem filtro.

5. Frontend — app-helico

  • lib/moodle.ts: PlatformPerformanceResponse ganha breakdown: PlatformPerformanceBreakdownRow[]; PlatformPerformanceByExamType/PlatformPerformanceByDiscipline ganham os campos novos (module_id); PlatformPerformanceExamType ganha os 3 subtipos + exam_written continua existindo (Geral).
  • types/helico/area-do-aluno/type.ts: ExamType ganha um 6º valor pra “Simulado Escrito Geral”: 'escrito'.
  • lib/helico/platform-adapters.ts: EXAM_TYPE_BY_PLATFORM_TYPE corrige o mapeamento (hoje todo exam_written cai em 'discursivo', bug real — ver §7); mapeia os 4 valores (Geral + 3 subtipos) pros 4 valores de UI correspondentes.
  • ExamPerformanceFilters.tsx: TYPE_LABELS/FILTERS_BY_TYPE ganham a entrada escrito (Geral) com [MATERIA] (sem Fonte, igual às outras 3 escritas); pílulas de Disciplina/Matéria/Fonte deixam de ser disabled.
  • ExamPerformanceSection.tsx e PerformanceEfficiencySection.tsx: passam a filtrar performance.breakdown pelas pílulas selecionadas (tipo + disciplina/matéria + fonte + módulo), em vez de só ler o array simples.
  • DisciplinePerformanceSection (não lida em detalhe ainda — mapear no plano de implementação): ganha pílula de Módulo, filtrando by_discipline[].module_id.

6. Testes

  • Novo tests/extensions/metrics/consolidation/service/breakdown_calculator_service_test.php — seguindo o padrão de mocks de by_source_calculator_service_test.php: split de subtipo, default discursiva sem ctx_subtype, fan-out de disciplina em escrito multi-disciplina, fonte ausente em linhas de escrito, omissão de combinações vazias.
  • Novo teste (ou extensão) pra by_module_calculator_service cobrindo o split de subtipo em by_exam_type[].
  • Extensão de discipline_performance_calculator_service_test.php cobrindo module_id por linha.

7. Verificação de dados — matrícula 225

Verificação realizada em Task 11 (2026-08-28). Resultados:

Achado 1: Bug corrigido em breakdown_calculator_service.php

O serviço originalmente usava slot_scope_service / slot_scope_ref_entity para resolver a disciplina de Simulados Escritos. Essa tabela nunca é populada pelo slot_generator_service.php neste codebase (confirmado via grep e verificação de banco). Corrigido para ler o campo de metadata herdado slot->get_scope() diretamente, resolvendo discipline_idnumber para IDs numéricos (a resolução em si foi corrigida de novo depois — ver Achado 4).

Commit: 0bc0f76b (no histórico da branch feat/desempenho-filtros-cruzados).

Achado 2: Bug pré-existente — notas de prova escrita não populadas em result.nota_real

Matrícula 225, student_plan_id 3247: único resultado exam_written encontrado é result_id 5149 (slot_id 5120). O slot mostra written_correction_state: corrected e written_overall_score: 72.78, porém seu result.nota_real está nulo. Isso significa que o pipeline de correção de provas escritas não copia o score corrigido para o item result que todos os calculadores (Desempenho — incluindo o novo breakdown) leem.

Consequência: provas escritas podem não aparecer em Desempenho por Simulado hoje, independentemente desta entrega. Escopo fora: é uma correção no pipeline de redação/correção, domínio separado.

Ação requerida: flagear para o time de backend/produto investigar o pipeline de correção de provas escritas.

Achado 3: Tamanho do breakdown[]

Para a matrícula 225, o breakdown[] gerou ~40 linhas (distribuição normal: 8 módulos × poucas disciplinas × alguns tipos × 3 fontes, maioria vazia). Sem necessidade de recorte por querystring nesta primeira versão — o volume está dentro do esperado.

Achado 4: discipline_id do Simulado Escrito estava em outro espaço de id (revisão final da branch)

A revisão final de branch inteira (2026-08-28, pós-Task 12) pegou que a correção do Achado 1 resolvia discipline_idnumber via discipline_service_interface::find_by_idnumber()->getId() — a PK do item discipline do middag. Todo o resto do payload (by_discipline[], plan_topology_resolver::resolve_by_unit() e a metade de questão fechada da própria breakdown[]) usa o discipline_id do student_plan.sequence.preview, que é um id de categoria de curso do Moodle. São dois espaços de id sem relação.

Na matrícula 225 (student_plan_id 3247), “Direito Constitucional” (EH_DIREITO_CONSTITUCIONAL_V1) é categoria 4 no preview e item 46 no cadastro de Disciplina. Consequências: (a) o filtro cruzado por Matéria em Simulado Escrito nunca casava — as opções de pílula do frontend só contêm ids de categoria; (b) risco de colisão numérica silenciosa entre as duas faixas, atribuindo a nota de uma prova escrita à disciplina errada.

Correção: discipline_service saiu do breakdown_calculator_service. Novo método plan_topology_resolver_service::resolve_discipline_id_by_idnumber() monta o mapa discipline_idnumber → discipline_id lendo o mesmo sequence.preview que resolve_by_unit() lê, garantindo espaços de id idênticos por construção, não por coincidência. Idnumber sem entrada na topologia do Plano é ignorado silenciosamente.

8. Documentação a atualizar após implementar

  • Este arquivo → Status: Implementado.
  • docs/plataforma/api-integracoes/contratos/performance.md — seções by_module[], by_discipline[], novo breakdown[].
  • docs/operacao/uc-007-desempenho.md — exemplo de resposta.
  • app-helico/docs/api-gaps-platform.md §8 — marcar como resolvido, linkar este arquivo.

Referências

  • Gap original: app-helico/docs/api-gaps-platform.md §8 (+ adendo 2026-08-18).
  • Contrato atual: docs/plataforma/api-integracoes/contratos/performance.md.
  • Vocabulário de subtipo: .vigim/ddd/linkml/enums/exam_type.linkml.yaml (ADR-60).
  • slot_context_exam_written.php, by_module_calculator_service.php, by_source_calculator_service.php, discipline_performance_calculator_service.php.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close