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/desempenhoe 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:
- 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. - 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”. - 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_idvêm deresponse.unit_id→plan_topology_resolver(mesmo join dodiscipline_performance_calculator_service).sourcevem deresponse.category(já usado noby_source_calculator_service).exam_typevem doslot_typedoresultdono da sessão (join já existente emby_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 deslot.ctx_subtype, resolvido viaresult.slot_id → slot_service->find_by_id()— mesma chamada queby_module_calculator_service::exam_scores_by_module()já faz pra achar o módulo viaflowref, sem query extra.module_idvem do mesmoslot->get_flowref() → study_flow → module_number.discipline_idvem do JSON legado emslot.scope({"disciplines":[{"discipline_idnumber": "...", ...}]}— escrito porslot_generator_service; a tabela normalizadaslot_scope_ref_entityexiste no código mas nunca é populada em produção, achado durante a verificação da matrícula 225, ver §7 Achado 1), resolvendo cadadiscipline_idnumberpara um ID numérico via o mesmo mapa doplan_topology_resolverqueresolve_by_unit()/by_discipline[]já usam (resolve_discipline_id_by_idnumber(), lido do própriostudent_plan.sequence.preview) — garante por construção o mesmo espaço de id em toda abreakdown[](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:PlatformPerformanceResponseganhabreakdown: PlatformPerformanceBreakdownRow[];PlatformPerformanceByExamType/PlatformPerformanceByDisciplineganham os campos novos (module_id);PlatformPerformanceExamTypeganha os 3 subtipos +exam_writtencontinua existindo (Geral).types/helico/area-do-aluno/type.ts:ExamTypeganha um 6º valor pra “Simulado Escrito Geral”:'escrito'.lib/helico/platform-adapters.ts:EXAM_TYPE_BY_PLATFORM_TYPEcorrige o mapeamento (hoje todoexam_writtencai 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_TYPEganham a entradaescrito(Geral) com[MATERIA](sem Fonte, igual às outras 3 escritas); pílulas de Disciplina/Matéria/Fonte deixam de serdisabled.ExamPerformanceSection.tsxePerformanceEfficiencySection.tsx: passam a filtrarperformance.breakdownpelas 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, filtrandoby_discipline[].module_id.
6. Testes
- Novo
tests/extensions/metrics/consolidation/service/breakdown_calculator_service_test.php— seguindo o padrão de mocks deby_source_calculator_service_test.php: split de subtipo, defaultdiscursivasemctx_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_servicecobrindo o split de subtipo emby_exam_type[]. - Extensão de
discipline_performance_calculator_service_test.phpcobrindomodule_idpor 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çõesby_module[],by_discipline[], novobreakdown[].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.