Skip to content

REF-30-B: Algoritmo de Detecção de Conflitos Pedagógicos

REF-30-B: Algoritmo de Detecção de Conflitos Pedagógicos

Status: Aceito Data: 2026-04-23 ADR: ADR-30 — Domínio Content: Arquitetura e Materialização Validação: Codex-002c-snapshot.md (2026-03-07) Autor: Michael Meneses (Arquiteto)

Propósito

Especificação do algoritmo de detecção de conflitos pedagógicos executado durante o content_revision (2º+ processamento de file_word). Define quando e como conflitos são criados, e as regras de resolução e cascata de status.

Contexto

Quando uma Unidade é reprocessada e seu conteúdo muda, três cenários podem ocorrer:

  1. Alteração de Conteúdo — conteúdo mudou sem impacto estrutural em Trilhas ou Planos
  2. Conflito com Trilha Pedagógica — item obrigatório removido/modificado que a Trilha referencia
  3. Conflito com Plano do Aluno — item específico selecionado na Trilha/Plano de Estudo que não existe mais no unit_content

Validado com Codex-002c-snapshot.md: a lógica de conflitos segue as premissas definidas em março/2026.


Tipos de mudança por seção

Ao comparar unit_content version N-1 com version N, o diff é computado por seção:

Seção Hash field Tipo de diff Impacto potencial
info info_hash overview, legislation, jurisprudence alterados Baixo — editorial
topic topic_hash Tópico adicionado, removido ou modificado Médio — impacta Leitura, Resumo, Estudo Dirigido
flashcard flashcard_hash Flashcard adicionado, removido ou modificado Baixo — formativo, sem progressão
video video_hash Vídeo adicionado, removido ou modificado Médio — impacta aulas e práticas
audio audio_hash Áudio adicionado, removido ou modificado Baixo — complementar
question_truefalse question_truefalse_hash Questão VF adicionada, removida ou modificada Alto — impacta CDA, DI, SVD
question_multichoice question_multichoice_hash Questão objetiva adicionada, removida ou modificada Alto — impacta Simulados
question_essay question_essay_hash Questão escrita adicionada, removida ou modificada Alto — impacta Simulado Escrito
relations relations_hash Vínculos entre items alterados Baixo — estrutural

Algoritmo de detecção

Entrada

content_change: {
    unit_id: int,
    unit_content_old_id: int,  // version N-1
    unit_content_new_id: int,  // version N
    changed_sections: string[] // ex: ["topic", "question_truefalse"]
}

Pseudocódigo

// conflict_detection_service.php
public function detect(content_change $change): array {
    $conflicts = [];

    // 1. Busca Trilhas que referenciam esta unit
    $trail_references = $this->trail_service->find_references_to_unit($change->unit_id);

    foreach ($trail_references as $trail_ref) {
        // Verifica se algum item removido/modificado era selecionado na Trilha
        $required_items = $this->trail_service->get_required_items(
            trail_id: $trail_ref->trail_id,
            unit_id: $change->unit_id,
        );

        foreach ($change->removed_items as $removed_item) {
            if (in_array($removed_item->id, $required_items)) {
                $conflicts[] = new content_conflict(
                    content_change_id: $change->id,
                    conflict_type: 'trail',
                    section: $removed_item->section,
                    reference_id: $removed_item->id,
                    reason: 'item_removed',
                    severity: $this->compute_severity($removed_item->section),
                    target_type: 'trail',
                    target_id: $trail_ref->trail_id,
                    target_context: $this->build_context($trail_ref),
                    status: 'open',
                );
            }
        }

        foreach ($change->modified_items as $modified_item) {
            if (in_array($modified_item->id, $required_items)) {
                // Item modificado mas não removido — registra se a Trilha
                // selecionava especificamente este item (não apenas a unit)
                if ($trail_ref->references_specific_item($modified_item->id)) {
                    $conflicts[] = new content_conflict(
                        content_change_id: $change->id,
                        conflict_type: 'trail',
                        section: $modified_item->section,
                        reference_id: $modified_item->id,
                        reason: 'item_modified',
                        severity: $this->compute_severity($modified_item->section),
                        target_type: 'trail',
                        target_id: $trail_ref->trail_id,
                        target_context: $this->build_context($trail_ref),
                        status: 'open',
                    );
                }
            }
        }
    }

    // 2. Busca Planos do Aluno ativos que usam esta unit
    $active_plans = $this->student_plan_service->find_active_plans_using_unit($change->unit_id);

    foreach ($active_plans as $plan) {
        // Plano do Aluno só tem conflito se item ESPECÍFICO selecionado não existe mais
        // Item atualizado NÃO gera conflito com Plano (conteúdo novo é aceito)
        $selected_items = $this->student_plan_service->get_selected_items(
            plan_id: $plan->id,
            unit_id: $change->unit_id,
        );

        foreach ($change->removed_items as $removed_item) {
            if (in_array($removed_item->id, $selected_items)) {
                // Verifica se o acionamento do Plano do Aluno está vinculado a um snapshot
                // da versão e da configuração efetivamente usadas. Existir outro snapshot
                // da mesma Unidade, de versão ou configuração diferente, NÃO protege.
                $is_protected = $this->snapshot_service->is_activation_protected(
                    plan_id: $plan->id,
                    unit_id: $change->unit_id,
                );

                if (!$is_protected) {
                    $conflicts[] = new content_conflict(
                        content_change_id: $change->id,
                        conflict_type: 'plan',
                        section: $removed_item->section,
                        reference_id: $removed_item->id,
                        reason: 'item_removed',
                        severity: $this->compute_severity($removed_item->section),
                        target_type: 'plan',
                        target_id: $plan->id,
                        target_context: $this->build_plan_context($plan, $removed_item),
                        status: 'open',
                    );
                }
                // Se o acionamento está protegido → aluno protegido, sem conflito
            }
        }
    }

    // 3. Alterações de item sem conflito não são tratadas aqui
    // Não é conflito — é alteração que o Gestor decide por item no Relatório de Alterações
    // (aprovar ou arquivar). Ver "Alteração de Conteúdo (sem conflito) — Aprovação por item".

    // Persiste conflitos
    foreach ($conflicts as $content_conflict) {
        $content_conflict->save();
        $this->signal->emit('content_conflict_detected', [
            'conflict_id' => $content_conflict->id,
            'conflict_type' => $content_conflict->conflict_type,
            'severity' => $content_conflict->severity,
        ]);
    }

    return $conflicts;
}

Regras de severity

Seção Severity base Justificativa
question_truefalse, question_multichoice, question_essay high Impacta avaliações (CDA, DI, SVD, Simulados)
topic medium Impacta Leitura, Resumo, Estudo Dirigido
video medium Impacta aulas e práticas vinculadas
flashcard low Formativo, sem impacto na Progressão
audio low Complementar
info low Editorial
relations low Estrutural

Severity pode ser promovida a critical se:

  • Conflito com Trilha E com Plano do Aluno simultaneamente
  • Seção question com > 50% dos items removidos

Conflito com Trilha — Consequências

Quando um content_conflict do tipo trail está open:

  1. Bloqueia nova publicação da Trilha — a validação da Trilha falha enquanto houver conflito aberto
  2. Registro não pode ser arquivado — fica ativo no Relatório
  3. Gestor resolve com uma das opções:
    • content_restored — conteúdo restaurado na Base de Conteúdo
    • trail_adapted — Trilha editada para não exigir mais o item
    • dismissed — Gestor aceita a inconsistência (raro, requer justificativa)
  4. Ação “Verificar novamente” — sistema re-executa a checagem de consistência (não é resolution_type, é ação de UI que roda detect() novamente)
  5. Auto-arquivamento — quando o sistema detecta que a inconsistência foi resolvida (re-check passa), o conflito é arquivado automaticamente

Conflito com Plano do Aluno — Consequências

Quando um content_conflict do tipo plan está open:

  1. Não bloqueia nada — o estudo do aluno continua
  2. Snapshot protege — se o acionamento do Plano do Aluno estiver vinculado ao Snapshot da versão/configuração efetivamente usada, não gera conflito. Um Snapshot da mesma Unidade com outra versão ou configuração não protege esse acionamento.
  3. Se não houver snapshot — comportamento padrão é “ignorar objeto perdido” (Codex-002c)
  4. Gestor resolve com uma das opções:
    • dismissed — ignora objeto perdido (padrão)
    • use_last_valid — sistema usa última versão válida do item como referência
    • plan_adapted — Gestor seleciona novo item para substituir o perdido
    • content_restored — conteúdo restaurado na Base de Conteúdo
  5. Atividade Dispensada — quando item é ignorado, atividades que dependiam dele podem ser dispensadas automaticamente

Enum conflict_resolution_type (atualizado)

content_restored   — conteúdo restaurado na Base
trail_adapted      — Trilha editada para aceitar nova realidade
plan_adapted       — Gestor selecionou substituto no Plano
use_last_valid     — sistema usa última referência válida (GAP identificado na validação Codex)
dismissed          — Gestor aceita inconsistência

Cascata de status

content_conflict.status → resolved/dismissed
  └── Se TODOS os conflicts do content_change estão resolved/dismissed:
        └── content_change.status → resolved
              └── Se TODOS os changes do content_revision estão resolved:
                    └── content_revision.status → resolved

Pseudocódigo da cascata

// Listener de content_conflict_resolved
public function on_conflict_resolved(int $conflict_id): void {
    $content_conflict = $this->content_conflict_service->get($conflict_id);
    $content_change = $this->content_change_service->get($content_conflict->content_change_id);

    // Verifica se todos os conflitos do change estão resolvidos
    $pending = $this->content_conflict_service->count_open($content_change->id);
    if ($pending === 0) {
        $content_change->status = 'resolved';
        $content_change->save();

        // Verifica se todos os changes da revision estão resolvidos
        $revision = $this->revision_service->get($content_change->content_revision_id);
        $pending_changes = $this->content_change_service->count_open($revision->id);
        if ($pending_changes === 0) {
            $revision->status = 'resolved';
            $revision->save();
            $this->signal->emit('content_revision_resolved', ['revision_id' => $revision->id]);
        }
    }
}

Alteração de Conteúdo (sem conflito) — Aprovação por item

Estado de implementação

O epic moodle-local_helico#118 está implementado (ver 02-content.md, “Implementação da primeira entrega” e “Do item aprovado ao Aluno”): aprovar registra a decisão, emite content_item_approved e as ações que consomem o sinal aplicam o item aos Snapshots, recalculam a nota quando o gabarito muda, atualizam o texto das atividades do mod_assign e oferecem o tópico novo no Caderno. O aviso ao Aluno sobre a oferta ainda não foi construído; só o sinal notebook_topic_update_offered existe.

Esta seção substitui o fluxo anterior, em que o Gestor decidia, por content_change, entre “Notificar Caderno do Aluno” (content_change_notification_requested) e “Arquivar”. A decisão passa a ser por item (tópico, questão, informações gerais, vídeo) e o relatório compara o Snapshot em uso com o conteúdo mais recente da Unidade.

  1. A alteração fica visível no Relatório de Alterações, por item, com estado (alterado, adicionado, removido no Word) e, nas questões, com a classificação gabarito, texto, removida ou adicionada.
  2. O Gestor decide, por item ou em lote por Disciplina ou Unidade:
    • Aprovar — registra autor, data, chave, hash anterior e novo, e emite content_item_approved.
    • Arquivar — mantém o item sem ação; pode ser aprovado depois.
  3. Nenhuma ação automática: o Gestor sempre decide, e um item que muda de novo volta a ser pendente.
  4. Flashcards e áudios não fazem parte do relatório.

Signal content_item_approved

content_item_approved
  payload: {
      unit_id: int,
      item_key: string,          // chave do Word (ex.: UXXX_TYY, VF_QZZ, OBJ_QZZ)
      item_type: string,         // topic, question_truefalse, question_multichoice, question_essay, info, video
      previous_hash: string,
      new_hash: string,
      question_change_kind: ?string,  // answer_key, text, removed, added (só questões)
      approved_by: int,
      approved_at: datetime,
      summary: ?string,          // texto opcional do Gestor para o Aluno
  }

Consumidores do sinal (implementados)

content_item_approved é consumido por content_item_apply_listener_service, que aplica o item a todos os Snapshots da Unidade e emite content_item_applied. Esse segundo sinal aciona, cada um com tabela de auditoria ou registro próprio:

  • Nota: gabarito recalcula (por conteúdo da alternativa escolhida, então reordenar não muda nota); texto e removida mantêm; questão escrita nunca recalcula.
  • mod_assign: o texto da questão escrita é atualizado nas atividades de correção, sem tocar em notas, submissões nem vínculos.
  • Caderno Online: oferta ao Aluno que tem artefato do tópico (sinal notebook_topic_update_offered); aceitar grava nova versão do artefato, recusar mantém. O aviso ao Aluno ainda não foi construído; quando for, segue sendo via API → NextJS (não via Moodle direto).

A descrição completa, as regras e o que ficou de fora estão em 02-content.md, seção “Do item aprovado ao Aluno”.


Critérios de aceitação

Detecção

  • Conflito com Trilha criado quando item obrigatório removido/modificado
  • Conflito com Plano criado quando item selecionado não existe mais E não há snapshot
  • Snapshot vinculado à versão/configuração efetivamente usada protege o aluno — sem conflito gerado
  • Item atualizado (não removido) NÃO gera conflito com Plano do Aluno
  • Severity computada automaticamente por seção
  • Signal emitido para cada conflito detectado

Resolução

  • Conflito com Trilha bloqueia publicação até resolução
  • “Verificar novamente” re-executa detect() e auto-arquiva se OK
  • use_last_valid disponível como opção para conflitos de Plano
  • Cascata de status funciona (content_conflict → content_change → content_revision)
  • Resolução de conflito emite signal para observabilidade

Aprovação por item

  • Gestor decide por item a partir do Relatório de Alterações (nunca automático)
  • Aprovar registra autor, data, chave, hash anterior e novo e emite content_item_approved, sem executar ação
  • Arquivar mantém o item sem ação e permite aprovar depois
  • Item que muda de novo depois da decisão volta a ser pendente

Do item aprovado ao Aluno

  • Aprovar aplica o item a todos os Snapshots da Unidade que o contêm, preservando o id inteiro de cada um, com auditoria
  • Questão removida no Word permanece; Snapshot com recorte de escopo que exclui o item não é alterado
  • Gabarito alterado recalcula a nota por conteúdo da alternativa escolhida; texto e remoção mantêm; escrita nunca recalcula
  • Revisão de simulado lê do Snapshot ativo do Aluno
  • Texto da questão escrita atualizado nas atividades do mod_assign
  • Oferta ao Aluno no Caderno Online para tópico aprovado; aceite grava nova versão do artefato e preserva a anterior
  • Notificação ao Aluno via API → NextJS (não via Moodle direto); só o sinal notebook_topic_update_offered existe
Navigation

Type to search…

↑↓ navigate↵ selectEsc close