Skip to content

ADR-05: Contratos de interface para tipos polimórficos

ADR-05: Contratos de interface para tipos polimórficos

Status: Aceito Data: 2026-04-17

Contexto

O domínio content possui famílias de objetos que compartilham estrutura e comportamento mas variam por tipo: questões (VF, objetiva, escrita) e conflitos pedagógicos (com Plano do Aluno, com Trilha Pedagógica). Sem contrato formal, cada tipo evolui independentemente, impossibilitando métricas uniformizadas, composição polimórfica e tratamento genérico em services e views.

O mesmo padrão se aplica a outras famílias futuras do sistema (formatos de execução de atividades, tipos de avaliação, etc.), tornando esta decisão reutilizável.

Decisão

Princípio: contrato antes de polimorfismo

Toda família de tipos que precisa de tratamento uniforme deve declarar um contrato (type rule no catálogo de termos) com identifier {familia}_contract. O contrato:

  1. Define a estrutura mínima compartilhada por todos os tipos da família.
  2. Usa relations.regulates para listar os tipos que implementam o contrato.
  3. No PHP, materializa como interface que cada tipo implementa.
  4. Permite que services, métricas e views operem sobre a interface, não sobre tipos concretos.

Contratos definidos no domínio Content

1. Contrato de Questão (question_contract)

  • Subdomain: content.base
  • Regula: question_multiplechoice, question_truefalse, question_written
  • Propósito: Métricas de desempenho uniformizadas, seleção de questões polimórfica, composição de avaliações sem switch/if por tipo.
  • Estrutura mínima esperada:
    • id: identificador único
    • statement: enunciado
    • category: categorização da questão (Legislação/Doutrina/Jurisprudência)
    • difficulty: dificuldade (quando disponível)
    • to_array() / from_array(): serialização

2. Contrato de Conflito Pedagógico (conflict_contract)

  • Subdomain: content.change
  • Regula: Conflito com Plano do Aluno, Conflito com Trilha Pedagógica
  • Propósito: Detecção, exibição no Relatório de Alteração e Resolução operam de forma polimórfica, sem depender do tipo específico de conflito.
  • Estrutura mínima esperada:
    • type: tipo do conflito (enum)
    • severity: gravidade/impacto (low | medium | high | critical)
    • affected_entity: referência ao objeto impactado
    • is_resolved(): estado de resolução
    • resolve(): ação de resolução

Convenção de nomes

Artefato Padrão Exemplo
Term Contrato de {Família} “Contrato de Questão”
identifier {familia}_contract question_contract
PHP interface {familia}_contract_interface question_contract_interface
Type no catálogo rule Contrato como regra do domínio

Quando criar um novo contrato

Um contrato é necessário quando:

  1. Existem 2+ tipos que precisam de tratamento uniforme.
  2. Há service, métrica ou view que opera sobre a família inteira.
  3. Novos tipos podem ser adicionados sem alterar o código consumidor.

Um contrato não é necessário para:

  • Tipos únicos (sem família).
  • Variações que diferem apenas em dados (usar attribute/enum).
  • Agrupadores puramente conceituais (usar concept).

Entidades relacionadas

  • content_conflict: entidade de conflito pedagógico.
  • content_change: entidade de registro de alteração. Todo conflito pertence a exatamente um content_change.

Consequências

  • Famílias de tipos ganham interface formal antes de qualquer implementação.
  • Services e métricas podem operar genericamente sobre a interface.
  • Novos tipos (ex: questão de arrastar-e-soltar) implementam o contrato sem alterar consumidores.
  • Padrão reutilizável para outros domínios (atividades, produto, motor pedagógico).
  • Exige disciplina: todo novo tipo de uma família deve implementar o contrato.
  • Contratos muito restritivos podem limitar tipos futuros — manter estrutura mínima.
  • Overhead se aplicado a famílias com apenas 1 tipo (violaria o critério “2+ tipos”).

ADRs relacionados

  • ADR-03: Abstração seletiva — contratos são abstrações aplicadas em pontos de variação real.
  • ADR-03: Hierarquia Atividade-base + Formato de Execução — mesmo padrão de polimorfismo.
  • ADR-30: Materialização do domínio content — entity vs attribute, pipeline, conflitos.

Referência

  • ref/adr-203-contract-specifications.md — especificação detalhada de cada contrato (campos, métodos, invariantes).

Histórico

Renumerado de ADR-203. Severity atualizado para escala low/medium/high/critical (ADR-30).

Navigation

Type to search…

↑↓ navigate↵ selectEsc close