Skip to content

REF-30-E: Especificação dos contratos de interface

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;
}

Campos compartilhados

Campo Tipo Obrigatório Descrição
id ?int Sim Identificador único da questão na Unidade
statement string Sim Enunciado da questão
category question_category Não Categorização: Legislação, Doutrina, Jurisprudência
comment string Não Comentário pedagógico / justificativa

Campos específicos por tipo

Tipo Campos extras
question_multiplechoice alternatives: string[], correct_answer: string
question_truefalse correct_answer: bool (implícito no enunciado VF)
question_written correction_mirror: string, video: string, correction_params: question_written_criteria_param[]

Invariantes

  1. Todo tipo DEVE implementar question_contract_interface.
  2. get_statement() nunca retorna string vazia.
  3. to_array() e from_array() são simétricos: from_array(x.to_array()) == x.
  4. 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

  1. Conflito com Trilha bloqueia publicação — is_resolved() deve ser true antes de publicar.
  2. Conflito com Plano não bloqueia — sistema preserva continuidade automaticamente.
  3. severity: high ou critical implica que uma ação humana é necessária.
  4. severity: low ou medium permite continuidade automática com registro.
  5. 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:

Família Domínio Tipos esperados Quando criar
Formato de Execução atividades Padrão, DI, SVD, Spaced Repetition, Timed Ao implementar domínio atividades
Tipo de Avaliação atividades VF, Objetivo, Escrito, Misto Ao implementar avaliações
Tipo de Bloco do CDA motor-pedagogico Estudo, Revisão Módulo, Revisão Geral, Simulado Ao implementar motor
Tipo de Métrica metricas Desempenho, Progressão, Classificação Ao implementar métricas
Navigation

Type to search…

↑↓ navigate↵ selectEsc close