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.