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:
- Define a estrutura mínima compartilhada por todos os tipos da família.
- Usa
relations.regulatespara listar os tipos que implementam o contrato. - No PHP, materializa como interface que cada tipo implementa.
- 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 únicostatement: enunciadocategory: 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 impactadois_resolved(): estado de resoluçãoresolve(): 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:
- Existem 2+ tipos que precisam de tratamento uniforme.
- Há service, métrica ou view que opera sobre a família inteira.
- 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 umcontent_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).