REF-30-E: Especificação dos contratos de interface
Companion file de ADR-30 (originalmente ADR-05). Atualizado em 2026-04-23.
Atualizar quando novos contratos forem adicionados ou existentes forem revisados.
1. question_contract — Contrato de Questão
Contexto
Três tipos de questão (VF, objetiva, escrita) precisam ser tratados uniformemente por:
Composição de avaliações (seleção de questões por critérios)
Métricas de desempenho (taxa de acerto, distribuição por categoria)
Balanceamento de questões (evitar repetição, equilibrar dificuldade)
Tipos regulados
identifier
Term
PHP class
question_multiplechoice
Questão Objetiva
question_multiplechoice
question_truefalse
Questão VF
question_truefalse
question_written
Questão Escrita
question_written
Interface mínima
interface question_contract_interface{ public function get_id(): ?int; public function get_statement(): string; public function get_category(): question_category; public function to_array(): array; public static function from_array(array $data): static;}
Todo tipo DEVE implementar question_contract_interface.
get_statement() nunca retorna string vazia.
to_array() e from_array() são simétricos: from_array(x.to_array()) == x.
Novos tipos de questão devem implementar a interface sem alterar consumers.
2. content_conflict_contract — Contrato de Conflito Pedagógico
Contexto
Dois tipos de conflito (com Plano do Aluno, com Trilha Pedagógica) precisam ser tratados
uniformemente por:
Relatório de Alteração Pedagógica (listagem unificada)
Resolução de Conflito (command genérico)
Detecção automática (análise de impacto pós-sync)
Tipos regulados
event_group
Term
Escopo do impacto
Conflito com Plano do Aluno
Alteração gera inconsistência com Planos já iniciados
Execução individual
Conflito com Trilha Pedagógica
Unidade deixa de atender requisitos da Trilha
Configuração/publicação
Interface mínima
interface content_conflict_contract_interface{ public function get_conflict_type(): conflict_type; public function get_section(): content_section; public function get_severity(): string; public function get_target_type(): string; public function get_target_id(): int; public function is_resolved(): bool; public function get_description(): string;}
Campos compartilhados
Campo
Tipo
Obrigatório
Descrição
conflict_type
conflict_type (enum)
Sim
Tipo do conflito (trail, plan)
section
content_section
Sim
Seção afetada (topic, question_truefalse, etc.)
severity
string
Sim
Gravidade: low, medium, high, critical
target_type
string
Sim
Tipo do objeto impactado (trail, plan)
target_id
int
Sim
ID do objeto impactado (Trilha ou Plano)
is_resolved
bool
Sim
Se o conflito foi resolvido
description
string
Sim
Descrição legível do conflito
Diferenças por tipo
Tipo
Comportamento de resolução
Conflito com Plano do Aluno
Preservar continuidade: ignorar objeto perdido, dispensar exigência ou recalcular avanço
Conflito com Trilha Pedagógica
Bloquear publicação até restabelecer compatibilidade (editorial ou resolução do Gestor)
Invariantes
Conflito com Trilha bloqueia publicação — is_resolved() deve ser true antes de publicar.
Conflito com Plano não bloqueia — sistema preserva continuidade automaticamente.
severity: high ou critical implica que uma ação humana é necessária.
severity: low ou medium permite continuidade automática com registro.
Todo conflito pertence a exatamente um content_change.
3. Padrões futuros (reservados)
Famílias identificadas que poderão precisar de contratos em outros domínios: