Skip to content

ADR-03: Abstração seletiva e hierarquia de atividades

ADR-03: Abstração seletiva e hierarquia de atividades

Status: Aceito Data: 2026-04-17

Contexto

O domínio da HÉLICO possui pontos com variação real: políticas de progressão, critérios de classificação, tipos de atividade e seus formatos de execução. Ao mesmo tempo, grande parte do sistema é estável e não se beneficia de abstração prematura.

Sem modelagem explícita para os eixos de variação — o tipo de atividade (flashcard, questionário, simulado escrito, estudo dirigido) e a forma como cada tipo é executado (formato “DI”, “SVD”, “padrão”, etc.) — essa variação tende a ser resolvida com if/switch internos, degradando legibilidade e dificultando a adição de novos formatos.

O projeto não define padrões obrigatórios como strategy ou policy. A decisão sobre quando abstrair deve vir da necessidade concreta, não de formalismo.

Decisão

Princípio: abstração seletiva

Abstrações (interfaces, contracts, implementações intercambiáveis) devem ser introduzidas apenas onde houver variação pedagógica real ou concretamente previsível.

Critério prático para abstrair:

  • Existe mais de um comportamento para a mesma intenção funcional?
  • A variação tende a crescer com a evolução do produto?
  • O branching interno (if/switch) está degradando legibilidade?

Se sim, extrair. Se não, manter implementação direta. Fora dos pontos de variação, o projeto deve preferir código simples e direto.

Exemplo canônico: hierarquia Atividade-base + Formato de Execução

A hierarquia de atividades é o ponto de variação pedagógica mais expressivo do domínio, modelado em dois níveis:

Atividade-base — cada tipo de atividade tem identidade própria:

  • Flashcard
  • Questionário (VF, múltipla escolha, etc.)
  • Simulado Escrito
  • Estudo Dirigido

Formato de Execução — cada Atividade-base pode ter múltiplos formatos:

Atividade-base Formatos de Execução
Questionário VF Padrão, DI (Estudo Dirigido), SVD (Simulado VF Dirigido)
Flashcard Padrão, Revisão Espaçada
Simulado Escrito Padrão, Cronometrado

Modelo extensível

  • Novo formato = nova classe que implementa a interface do formato. Não é if/switch.
  • Cada Formato de Execução encapsula suas regras de apresentação, interação, correção e pontuação.
  • Atividades são configuráveis por Trilha via Configuração das Atividades (Fase 1 do ADR-02).
  • O Motor Pedagógico orquestra atividades sem conhecer detalhes internos de cada tipo ou formato — interage via interface da Atividade-base.

Consequências

  • Extensibilidade proporcional ao problema real.
  • Menor risco de inflar o domínio com abstrações sem uso.
  • Novos formatos de execução são adicionados via nova classe, sem alterar código existente (OCP).
  • Motor Pedagógico desacoplado dos detalhes de cada tipo de atividade.
  • Configuração por Trilha permite variação pedagógica sem mudança de código.
  • Exige julgamento técnico para identificar pontos reais de variação.
  • Parte das abstrações pode surgir apenas com a evolução do produto — e isso é aceitável.
  • Exige convenção clara de interface entre Atividade-base e Motor Pedagógico.
  • Formatos devem ser autodescritivos para permitir configuração administrativa.

ADRs relacionados

  • Depende de ADR-01 (separação de responsabilidades e fronteira com middag).
  • Relaciona-se com ADR-02 (Fase 1 — Configuração) para parametrização por Trilha.
  • Usa ADR-04 (eventos) para comunicar conclusão e submissão de atividades.
  • Mesmo padrão de polimorfismo aplicado em ADR-05 (contratos de interface).

Histórico

Consolida ADR-102 e ADR-107.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close