ADR-70: Domínio Metrics — Arquitetura e Aggregate Roots
Status: Aceito
Data: 2026-04-24
Autor: Michael Meneses (Arquiteto)
Contexto
O domínio metrics é responsável por transformar resultados de atividades em notas, classificações, métricas consolidadas e relatórios analíticos. É um domínio de leitura e derivação — não gera dados primários, mas consome resultados do domínio activity e produz análises.
A página arquitetura/08-metrics.md (Passo 9) já detalha fórmulas e dimensões. Este ADR consolida a arquitetura formal do domínio: aggregate roots, storage, events, interfaces e regras de cálculo.
A decisão A-05 (ADR-60) migrou o MetricsConsolidationEngine de engine.algorithm para este domínio. As decisões aqui formalizadas absorvem D-42 a D-46 do BL-009 (Metrics Discovery Review, 2026-03-31).
Subdomínios
O domínio metrics opera como domínio único, sem subdivisões formais. Toda a lógica de cálculo, classificação, consolidação e relatórios vive sob o namespace metrics.
Aggregate Roots
AR
Conceito
Tabela
Natureza
classification
Classificação de Nível
helico_classification
AR acumulativo, imutável
report
Relatório
helico_report
AR com lifecycle (gerado → invalidado)
Relação entre aggregate roots
activity_completed (evento do domínio activity) │ └── classification (Classificação de Nível — imutável, 1 por avaliação/unidade) │ └── report (Relatório — consolidado, gerado sob demanda ou por evento)
classification é um registro imutável criado quando uma avaliação (DI, SVD, Simulado Objetivo, etc.) é processada. Cada registro contém score, nível e contexto (aluno + unidade + disciplina). Reclassificação cria novo registro, não edita o anterior.
report é um artefato consolidado com lifecycle: gerado a partir de classificações e métricas, pode ser invalidado quando novos dados entram. Referencia pelo menos uma classificação.
Storage
Tabela unificada
Tabela
Entidades
Justificativa
helico_metrics
Classification + Report (via type)
Tabela única com campo type que distingue classificações de relatórios. Classificações são append-only; relatórios têm lifecycle (generated → invalidated). Índices por student_id, type, unit_id, scope.
Sem EAV para metrics. A tabela helico_metrics é a única persistência do domínio. O campo type (classification ou report) determina o schema de dados no campo JSON data.
Invariantes dos Aggregate Roots (absorve D-42)
classification
Imutável após criação — registros nunca editados
Nível respeita limiares configurados na Trilha (defaults: Básico < 50%, Intermediário 50-79%, Avançado ≥ 80%)
Reclassificação cria novo registro com referência ao anterior
Apenas Resultados Elegíveis geram classificação (treino/cancelados/incompletos excluídos)
report
Referencia pelo menos uma classificação
Dados consolidados coerentes com período e escopo declarados
Pode ser invalidado quando novos dados entram (status → invalidated)
Não pode ser gerado sem pelo menos uma classificação
Cadeia de cálculo
Notas
Resultado da Atividade (domínio activity) └── Nota Real (NR) — desempenho bruto (acertos/total × 100, ou nota do Tutor) └── Nota Bruta (NB) — ponderada por tipo de simulado (pesos VF=1, Escrito=2, Objetivo=3) └── Nota Ajustada (NA) — NB + Bônus de Relevância └── Classificação de Nível — NA comparada contra limiares
Bônus de Relevância
A fórmula é regra da metodologia HÉLICO, acessada via ScoringRuleInterface:
A implementação padrão (RelevanceBonusScoringRule) aplica a fórmula acima. Novas regras de scoring podem ser adicionadas implementando a mesma interface, sem alterar a fórmula existente.
Inputs (Importância e Incidência) são configurados por Unidade na Trilha. A escala de fatores é fixa na metodologia:
Classificação
Fator
Baixa
1.0
Média
1.1
Alta
1.3
Altíssima
1.5
Consolidação por dimensão
Dimensão
Cálculo
Desempenho por Unidade
NA da Unidade (ou NB quando NA não se aplica)
Desempenho por Disciplina
Média aritmética simples das NAs das Unidades da Disciplina
Desempenho por Módulo
Média aritmética simples das NAs das Unidades do Módulo
Desempenho Geral
Média aritmética simples das médias de todas as Disciplinas
Todas as médias são aritméticas simples (não ponderadas).