Skip to content

ADR-70: Domínio Metrics — Arquitetura e Aggregate Roots

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%)
  • Contexto obrigatório: aluno + unidade + disciplina + source (DI, SVD, Simulado Objetivo, etc.)
  • 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:

BÔNUS = (IMPORTÂNCIA + INCIDÊNCIA - 2.0) × 15
NA = min(NB + BÔNUS, 100)

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).


Domain Events (absorve D-44)

Events emitidos pelo metrics

Evento Trigger Consumidores
level_classified Classificação concluída (DI, SVD, Objetivo) Engine (adapta atividades), API (tela Desempenho)
level_changed Reclassificação com nível diferente do anterior Engine (reavalia dispensas e atividades)
report_generated Geração de relatório concluída API (disponibiliza para frontend)
report_invalidated Novos dados tornam relatório obsoleto Sistema (reagenda geração)

Events consumidos pelo metrics

Evento Produtor Efeito
activity_completed Activity Recalcula dimensões afetadas (event-driven, decisão A-10)
cda_cycle_completed Engine Processa classificação final do CDA (média DI + SVD)

Regras de Negócio (absorve D-45)

# Regra Tipo Escopo
1 Limiares de classificação configuráveis por Trilha (defaults globais) pedagógica trilha
2 Classificação imutável após criação; reclassificação cria novo registro consistência aluno
3 Apenas Resultados Elegíveis compõem métricas funcional aluno
4 Bônus de Relevância via ScoringRuleInterface — fórmula padrão fixa na metodologia funcional unidade
5 Relatório não pode ser gerado sem pelo menos uma classificação consistência aluno
6 Consolidação event-driven: recalcula dimensões afetadas a cada activity_completed funcional aluno
7 NB ponderada por tipo de simulado (VF=1, Escrito=2, Objetivo=3); divisor proporcional funcional unidade

Services (absorve D-44 + A-05)

Service Responsabilidade
ClassificationService Score + limiares → nível. Cria registro imutável de classificação
ReclassificationService Reavalia classificação event-driven; compara com anterior; cria novo registro
ScoreCalculationService NR → NB (pesos) → NA (bônus via ScoringRuleInterface)
ConsolidationEngine Agrega resultados por dimensão de análise (migrado de engine, decisão A-05)
ReportGenerationService Compõe relatório a partir de métricas, classificações e progressos

Interfaces Cross-Domain

Domínio externo Direção Contrato Dados trocados
Activity consome ActivityResultContract Scores, respostas, tipo de atividade
Engine publica ClassificationResultContract Nível por unidade, dispensas derivadas
Engine consome PlanProgressContract Progresso do Plano (denominador, atividades concluídas)
Product consome TrailParametersContract Limiares, Importância, Incidência por Unidade
API publica MetricsQueryContract Métricas consolidadas, gráficos, relatórios

Decisões abertas registradas (absorve D-46)

# Item Tipo Status
1 Nota Formal (gradebook Moodle) decisão adiada Não é prioridade. Quando necessário, Metrics publica evento e Moodle core grava
2 MetricsConsolidationEngine no domínio metrics decisão validada Confirmado (A-05/ADR-60). Engine emite; Metrics consolida
3 Consolidação event-driven por activity_completed decisão validada Confirmado (A-10). Sem batches, sem polling
4 Bônus de Relevância: fórmula fixa via ScoringRuleInterface decisão validada Confirmado (A-11). Interface permite novas regras futuras
5 Catálogo de 13 gráficos de desempenho decisão validada Documentado em arquitetura/08-metrics.md
6 Avaliação de Tutores: rubrica, periodicidade e visibilidade decisão validada Documentado em arquitetura/08-metrics.md

Consequências

  • Domínio metrics especificado com 2 ARs (classification, report) em tabela unificada helico_metrics
  • Tabela única com type — simplicidade de storage, campo JSON data por tipo
  • Consolidação event-driven — sem batches, recalcula dimensões afetadas por evento
  • ScoringRuleInterface permite extensibilidade sem alterar fórmula existente
  • MetricsConsolidationEngine migrado de engine (decisão A-05)
  • 4 domain events + 2 events consumidos
  • 7 regras de negócio consolidadas
  • 5 services com responsabilidades definidas
  • 5 interfaces cross-domain com contratos nomeados
  • 1 tabela dedicada (helico_metrics) a criar no install.xml quando implementação iniciar
  • metrics_consolidation_engine nos terms precisa migrar de engine.algorithm para metrics
  • Gradebook Moodle adiado — tratar quando necessário

ADRs relacionados

  • ADR-02 — Ciclo de vida pedagógico em 4 fases (fundação)
  • ADR-04 — Eventos para desacoplamento (consolidação event-driven)
  • ADR-10 — Persistência EAV (metrics não usa EAV — apenas tabelas próprias)
  • ADR-40 — Configuração por preset (limiares e fatores são parâmetros da Trilha)
  • ADR-50 — Domínio Product (publica limiares, Importância, Incidência)
  • ADR-60 — Domínio Engine (publica eventos de execução, consome classificações)
  • REF-70-A — Mapeamento de enums do Metrics

Histórico

Data Evento
2026-04-24 Criado — consolida decisões da sessão 15 + absorve BL-009 D-42..D-46
Navigation

Type to search…

↑↓ navigate↵ selectEsc close