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:
- Alteração de Conteúdo — conteúdo mudou sem impacto estrutural em Trilhas ou Planos
- Conflito com Trilha Pedagógica — item obrigatório removido/modificado que a Trilha referencia
- 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:
- Bloqueia nova publicação da Trilha — a validação da Trilha falha enquanto houver conflito aberto
- Registro não pode ser arquivado — fica ativo no Relatório
- Gestor resolve com uma das opções:
content_restored— conteúdo restaurado na Base de Conteúdotrail_adapted— Trilha editada para não exigir mais o itemdismissed— Gestor aceita a inconsistência (raro, requer justificativa)
- Ação “Verificar novamente” — sistema re-executa a checagem de consistência (não é resolution_type, é ação de UI que roda
detect()novamente) - 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:
- Não bloqueia nada — o estudo do aluno continua
- 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.
- Se não houver snapshot — comportamento padrão é “ignorar objeto perdido” (Codex-002c)
- 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ênciaplan_adapted— Gestor seleciona novo item para substituir o perdidocontent_restored— conteúdo restaurado na Base de Conteúdo
- 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ênciaCascata 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 → resolvedPseudocó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#118está implementado (ver02-content.md, “Implementação da primeira entrega” e “Do item aprovado ao Aluno”): aprovar registra a decisão, emitecontent_item_approvede as ações que consomem o sinal aplicam o item aos Snapshots, recalculam a nota quando o gabarito muda, atualizam o texto das atividades domod_assigne oferecem o tópico novo no Caderno. O aviso ao Aluno sobre a oferta ainda não foi construído; só o sinalnotebook_topic_update_offeredexiste.
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.
- 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,removidaouadicionada. - 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.
- Aprovar — registra autor, data, chave, hash anterior e novo, e emite
- Nenhuma ação automática: o Gestor sempre decide, e um item que muda de novo volta a ser pendente.
- 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:
gabaritorecalcula (por conteúdo da alternativa escolhida, então reordenar não muda nota);textoeremovidamantê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_validdisponí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_offeredexiste