Skip to content

Domínio Content

Especificação técnica — como o conteúdo pedagógico entra, é estruturado e evolui no sistema

Domínio Content

O domínio content é o primeiro domínio completamente especificado da plataforma HÉLICO. Ele responde a uma pergunta central: como o conteúdo pedagógico — escrito por Conteudistas em documentos Word — se transforma em uma Base de Conteúdo estruturada, versionada e consumível por todos os outros domínios do sistema?

A resposta se desdobra em três atos. Primeiro, o conteúdo entra no sistema via sincronização com o SharePoint. Depois, o Gestor Pedagógico processa esse conteúdo e o sistema materializa Unidades, Tópicos, Questões e demais componentes. Por fim, quando o conteúdo muda, o sistema detecta o impacto dessas mudanças em Trilhas Pedagógicas e Planos do Aluno — e o Gestor resolve cada conflito individualmente.

Esses três atos correspondem aos três subdomains do content:

Subdomain Slug Escopo
Gestão e Publicação content.management Operação: sync SharePoint, file_word, pré-processamento, commands, jobs
Base de Conteúdo content.base Modelagem: Disciplina, Unidade, unit_content, tópicos, questões, VOs
Alteração Pedagógica content.change Impacto: revisão de conteúdo, diff, detecção e resolução de conflitos

O fluxo é unidirecional: content.management alimenta content.base e dispara content.change. O subdomain content.change consulta content.base mas não o modifica — quem resolve é o Gestor, via commands de content.management.


Ato 1 — O conteúdo entra no sistema

O documento Word

Tudo começa com o Conteudista. Para cada Disciplina, o Conteudista redige um documento Word seguindo o Contrato Estrutural — um conjunto de regras que define como o conteúdo deve ser organizado dentro do arquivo. Esse Word é depositado em uma pasta do SharePoint, identificado pelo IDNUMBER da Disciplina no nome do arquivo.

O sistema não interpreta documentos livres. Se o nome do arquivo não segue o padrão esperado, ele é ignorado silenciosamente (com log).

Contrato Estrutural do Arquivo Word

O Contrato Estrutural define como o Conteudista deve organizar o documento Word para que o sistema consiga interpretar e extrair o conteúdo automaticamente.

Padrão de naming do arquivo

O nome do arquivo segue o padrão [IDNUMBER] Nome da Disciplina, onde IDNUMBER é o identificador único da Disciplina. Esse IDNUMBER se torna o idnumber da subcategoria no Moodle.

Exemplos válidos:

  • [DIREITO_CONSTITUCIONAL_V1] Direito Constitucional
  • [PROCESSO_PENAL_I_V1] Processo Penal I

Versionamento da Disciplina

A Disciplina é identificada exclusivamente pelo IDNUMBER no nome do arquivo. Um novo IDNUMBER = uma nova Disciplina, sem vínculo com a anterior. Se o Conteudista quiser versionar, deve criar um novo IDNUMBER:

  • MINHADISCIPLINA_V1, MINHADISCIPLINA_V2
  • MINHADISCIPLINA_2026, MINHADISCIPLINA_2026_REVISADA
  • MINHADISCIPLINA_CONCURSO_MPSP

Cada IDNUMBER gera uma subcategoria independente no Moodle. Não existe “migração automática” entre versões de Disciplina.

Estrutura interna do documento

O Word utiliza estilos e marcadores convencionais:

Elemento Marcação no Word Padrão de naming
Página de Informações Primeira página — campos de metadados (Disciplina, Livro, Autor, Edição, Ano, Páginas, IDNUMBER, Conteudista) —
Unidade Heading 1 (# UNIDADE Nº XX) UXXX (ex: U001, U002)
Tópico de Conteúdo Heading 2 (## Título do Tópico) UXXX_TYY (ex: U001_T01)
Subtítulo Heading 3 (opcional) —
Conteúdo do Tópico Texto entre a tag do tópico e a próxima Tag-Colchete —

Catálogo de Tag-Colchetes

As seções especiais são delimitadas por tags entre colchetes:

Tag-Colchete Nível Conteúdo esperado
[CONTEUDISTA] Disciplina Nome do conteudista responsável
[QUADRO GERAL DE INFORMAÇÕES] Unidade Resumo dos tópicos abordados (texto rico)
[[JURISPRUDÊNCIA]] Unidade Decisões judiciais e precedentes (texto rico)
[LEGISLAÇÃO] Unidade Textos legais relacionados (texto rico)
[VÍDEO DA UNIDADE] Unidade URL do vídeo de apoio
[UXXX_TYY] Tópico Marcador de início do Tópico de Conteúdo
[[OBSERVAÇÕES OU COMENTÁRIO]] Tópico Comentários do professor sobre o tópico
[VF_QZZ] Questão VF Questão de Verdadeiro/Falso (numeração sequencial)
[OBJ_QZZ] Questão Objetiva Questão de múltipla escolha (numeração sequencial)
[ESC_QZZ] Questão Escrita Questão discursiva/dissertação/peça (numeração sequencial)

Padrões de naming na persistência

Ao processar o Word, o sistema gera identificadores compostos para cada componente:

Componente Padrão no Word Padrão no Moodle (persistido) Exemplo
Disciplina IDNUMBER (nome do arquivo) IDNUMBER (subcategoria) PROCESSO_PENAL_I_V1
Unidade UXXX IDNUMBER_UXXX PROCESSO_PENAL_I_V1_U016
Tópico UXXX_TYY IDNUMBER_UXXX_TYY PROCESSO_PENAL_I_V1_U016_T03
Questão VF VF_QZZ IDNUMBER_UXXX_VFZZ PROCESSO_PENAL_I_V1_U016_VF05
Questão Objetiva OBJ_QZZ IDNUMBER_UXXX_OBJZZ PROCESSO_PENAL_I_V1_U016_OBJ02

Esses identificadores são estáveis — o reprocessamento do mesmo arquivo mantém os mesmos IDs. A numeração é sequencial dentro de cada Unidade.

Reprocessamento e versionamento da Unidade

Quando um arquivo já processado é editado e reenviado:

  1. Todo o conteúdo é reprocessado — o novo manifest sobrescreve integralmente o anterior.
  2. Adição de conteúdo é transparente — novos componentes aparecem normalmente.
  3. Edição gera um content_change com diff por seção (ver Ato 3). O Gestor avalia se a alteração é pedagógica (requer notificação ao Aluno) ou editorial (pode ser arquivada).
  4. Remoção faz o componente deixar de existir. Recomenda-se não remover conteúdo já processado — a remoção pode quebrar referências futuras em Trilhas e Planos.

Conteúdo nunca é excluído

Mesmo em remoção, o unit_content anterior permanece no histórico (soft-delete). Se a Unidade inteira desaparece do manifest, ela é arquivada — não deletada.

Um modelo completo do formato Word está disponível em docs/assets/modelo-arquivo-word.md.

Sincronização

A entrada do conteúdo no sistema acontece por dois caminhos:

  1. CRON automático — o command file_word_autosync executa duas vezes ao dia (7h30 e 18h30) e varre a pasta completa do SharePoint.
  2. Sync manual — o Gestor aciona a sincronização de uma Disciplina específica, que entra em fila e é processada pelo CRON file_word_manualsync a cada minuto.

Em ambos os casos, o serviço sharepoint_sync faz o trabalho:

  1. Lista os arquivos via Microsoft Graph adapter (autenticação por certificado ou client secret; ver Credenciais do Moodle no Microsoft Graph).
  2. Para cada arquivo com nome válido, extrai o IDNUMBER e localiza (ou cria) a discipline correspondente.
  3. Compara o hash do arquivo remoto com o último file_word registrado. Se o hash é igual, não há alteração — o arquivo é ignorado.
  4. Se o hash difere, o Word é baixado para o file_storage do Moodle e um novo registro file_word é criado com status created.
  5. O signal file_word_created é emitido.

Um sync_job registra o resultado da operação: quantos arquivos foram verificados, quantas alterações detectadas, timestamps de início e conclusão.

Lock por Disciplina

A sincronização adquire lock por Disciplina para evitar processamento concorrente. Se outra sync já está em andamento para a mesma Disciplina, a nova aguarda.

Pré-processamento

O signal file_word_created dispara automaticamente uma ad_hoc task (pattern outbox, [ADR-707]) que executa o pré-processamento:

  1. O serviço file_word_process lê o Word do file_storage.
  2. Aplica o Contrato Estrutural e o Catálogo de Tags — etapa interna file_word_validation. Se o Word é inválido, o status transiciona para failed com log detalhado.
  3. Extrai as Unidades e gera um JSON manifest — um inventário estruturado de todas as Unidades da Disciplina, com seus componentes. Esse manifest é salvo como file_storage vinculado ao file_word (não em coluna, para suportar documentos grandes).
  4. Gera o Markdown de Tópicos — uma versão textual dos tópicos que será usada posteriormente para geração de flashcards. O hash desse Markdown é computado e armazenado.
  5. O file_word transiciona para status preprocessed.
  6. O signal file_word_preprocessed é emitido.

A partir desse ponto, o file_word está disponível para o Gestor na interface. Nenhuma ação automática acontece — o Gestor decide quando processar.

Entidades envolvidas

Entidade Tipo Subdomain Papel
discipline entity_root content.base A Disciplina — aggregate root do conteúdo
file_word entity_root content.management Registro do arquivo Word (o arquivo em si é attribute)
sync_job entity_child content.management Registro de execução da sincronização

Signals emitidos neste ato

Signal Quando
file_word_created Novo file_word registrado após sync
file_word_preprocessed Pré-processamento concluído com sucesso

Ato 2 — O conteúdo vira Base de Conteúdo

O Gestor processa

O Gestor acessa a Disciplina no backend Moodle e vê a lista de versões do file_word. Somente a versão mais recente pode ser processada — versões anteriores aparecem desabilitadas. A tela mostra uma prévia: as Unidades do manifest e um diff visual comparando com a versão anterior (se houver).

O Gestor pode preencher motivação e contexto (opcionais — o sistema gera fallback automático: “Reprocessamento de version N”). Ao clicar “Processar”, o serviço publication assume:

  1. Guards: verifica lock por Disciplina, confirma que é o file_word mais recente, checa idempotência (se o hash já foi processado, retorna already_processed).
  2. Lock: adquire lock exclusivo por Disciplina.
  3. Manifest: lê o JSON manifest do file_storage.

Criação e atualização de Unidades

Para cada Unidade no manifest:

  1. O sistema localiza ou cria o registro unit (entity_root, EAV). Se a Unidade é nova, um curso-unidade Moodle é criado atomicamente, com o mesmo IDNUMBER. O signal unit_created é emitido.
  2. Computa hashes por seção: info_hash, topic_hash, flashcard_hash, video_hash, audio_hash, hashes de questões e relations_hash.
  3. Compara o hash consolidado com unit.current_content_hash. Se igual, a Unidade não mudou — skip.
  4. Se diferente, cria um novo unit_content (entity_child, version N+1). O unit_content é o coração da Base de Conteúdo — contém todas as seções do conteúdo pedagógico da Unidade.

Estrutura do unit_content

O unit_content é composto por seções, cada uma representada por Value Objects imutáveis:

unit_content (version N)
  ├── info        → unit_info (overview, legislation, jurisprudence, doctrine)
  ├── topics      → topic[] (cada um com subtitle, observations, synthesis)
  ├── flashcards  → flashcards (seção embarcada, não EAV)
  ├── videos      → video[]
  ├── questions   → question_multiplechoice[] | question_truefalse[] | question_written[]
  └── relations   → grafo de vínculos entre items

Cada VO é uma readonly class com métodos from_array e to_array — imutável, sem identidade própria, sem persistência EAV separada. Os três tipos de questão implementam o contrato polimórfico question_contract (interface PHP manual com get_statement(), get_difficulty(), etc.).

Estrutura detalhada dos Materiais Didáticos

Cada Unidade contém Informações Gerais e 5 tipos de Materiais Didáticos. Os campos abaixo correspondem aos contratos JSON em .vigim/ddd/json-schema/contract/.

Informações Gerais (unit_info)

Conjunto de informações de contexto e apoio associadas à Unidade:

Campo Tipo Obrigatório Descrição
overview texto rico Sim Resumo dos tópicos abordados (equivale ao “Quadro Geral de Informações” do Word)
legislation texto rico Não Textos legais relacionados à Unidade
jurisprudence texto rico Não Decisões judiciais e precedentes
video_url URL Não Vídeo de apoio da Unidade
audios arquivo[] Não Material de áudio complementar (utiliza o mais recente)
conteudistas string[] Não Lista de autores responsáveis pela criação do conteúdo

Tópico de Conteúdo (topic)

Textos diretos e comentados elaborados pelos professores:

Campo Tipo Obrigatório Descrição
title texto plano Sim Título do tópico
subtitle texto plano Não Subtítulo (Heading 3 no Word)
synthesis texto rico Sim Conteúdo do tópico — corpo principal
observations texto rico Não Observações ou comentários do professor

Questão VF (question_truefalse)

As Questões VF compartilham um vídeo explicativo único por Unidade:

Campo Tipo Obrigatório Descrição
video_url URL Não Vídeo explicativo (único para todas as VF da Unidade)
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
correct_answer boolean Sim Verdadeiro ou Falso
feedback texto rico Sim Comentário/explicação da questão

Questão Objetiva (question_multichoice)

As Questões Objetivas compartilham um vídeo explicativo único por Unidade:

Campo Tipo Obrigatório Descrição
video_url URL Não Vídeo explicativo (único para todas as Objetivas da Unidade)
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
alternatives texto rico[] Sim Até 6 alternativas (mínimo 2)
correct_answer texto rico Sim Resposta correta (texto)
feedback texto rico Sim Comentário/explicação da questão

Questão Escrita (question_essay)

Campo Tipo Obrigatório Descrição
format enum essay_format Sim Tipo: dissertativa, petição, opinião, sentença
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
answer_key texto rico Sim Espelho de correção (padrão de resposta esperado)
correction_criteria texto rico Sim Critérios de avaliação
reference_answer texto rico Não Autorresposta elaborada pelo professor
max_score número Sim Pontuação máxima da questão
video_url URL Não Vídeo explicativo (um por questão escrita, não compartilhado)

Flashcard (flashcard)

Campo Tipo Obrigatório Descrição
assertion texto rico Sim Conceito ou pergunta apresentada (frente)
answer texto rico Sim Explicação ou resposta (verso)
position número Sim Ordem dentro da lista
generated_at datetime Sim Registro de quando o flashcard foi criado (pela API)

Flashcards são gerados por IA

Os flashcards não vêm do Word — são gerados pela API externa (Law School) a partir do Markdown dos Tópicos. O Conteudista não os escreve manualmente. Ver seção “Flashcards — fluxo desacoplado” abaixo.

Campos internos, não VOs

doctrine, jurisprudence e legislation são campos textuais do unit_info — não geram classes próprias. synthesis é campo do topic, não VO independente.

Unidades que desaparecem

Se uma Unidade existia na versão anterior mas não está no manifest atual, o sistema:

  • Transiciona o unit para status archived.
  • Bloqueia o curso-unidade Moodle correspondente.
  • Emite signal unit_archived.

Se a Unidade reaparecer em processamento futuro, um novo unit_content é sempre criado (não restaura o anterior).

Flashcards — fluxo desacoplado

A geração de flashcards é deliberadamente separada do processamento principal. O motivo é prático: a API externa (Law School) leva 5 a 20 minutos para responder, e bloquear o Gestor durante esse tempo seria inaceitável.

O fluxo funciona assim:

  1. O Gestor aciona “Gerar Flashcards”. O botão só está ativo se o hash do Markdown de Tópicos mudou desde a última geração.
  2. Um flashcard_job é criado com status generating. O Markdown é enviado para a API externa.
  3. Se a API falha por rede/timeout, o job transiciona para failed_retryable (retry automático com backoff). Se a falha é de negócio, transiciona para failed (Gestor notificado).
  4. Quando a resposta chega, o flashcard_raw é salvo no file_storage. O signal flashcard_job_generated dispara uma ad_hoc task de persistência.
  5. A persistência distribui os flashcards para os unit_content existentes por match de topic_ref (título do tópico). Flashcards que não casam com nenhum tópico ficam como “não alocados”, visíveis no dashboard do Gestor.

Pseudocódigo completo do fluxo de flashcards em [REF-30-A], Step 4.

Entidades e VOs envolvidos

Componente Tipo Subdomain Papel
unit entity_root content.base A Unidade — vinculada a uma Disciplina
unit_content entity_child content.base Versão do conteúdo (N versões por unit)
unit_info value_object content.base Seção info (overview, legislação, jurisprudência, doutrina)
topic value_object content.base Tópico com subtitle, observations e synthesis
flashcards value_object content.base Seção embarcada no unit_content
video value_object content.base Asset de vídeo no content_bank
question_multiplechoice value_object content.base.bank_question Questão objetiva
question_truefalse value_object content.base.bank_question Questão verdadeiro/falso
question_written value_object content.base.bank_question Questão escrita
process_job entity_child content.management Registro de execução do processamento
flashcard_job entity_child content.management Registro de execução da geração de flashcards

Signals emitidos neste ato

Signal Quando
unit_created Nova Unidade registrada
unit_content_published Nova versão do conteúdo criada
unit_archived Unidade desapareceu do manifest
file_word_processed Processamento concluído
flashcard_job_generated Flashcards retornados da API
flashcard_job_persisted Flashcards distribuídos nos unit_content

Ato 3 — O conteúdo muda e conflitos são tratados

Content revision

A partir do segundo processamento de uma Disciplina, quando hashes diferem, o sistema entra no fluxo de alteração pedagógica. O serviço publication, após criar as novas versões de unit_content, delega ao serviço content_revision:

  1. Um content_revision é criado com status open, vinculado ao file_word e à Disciplina. A motivação e o contexto preenchidos pelo Gestor (ou fallback automático) ficam registrados.
  2. Para cada Unidade cujo hash mudou, um content_change é criado. Esse registro contém o diff item a item, separado por seção (diff_info, diff_topic, diff_flashcard, etc.), além das versões anterior e nova do unit_content.

A hierarquia é clara e estável:

content_revision (1 por reprocessamento — o evento)
  └── content_change (N por Unidade alterada — contém diff)
        └── content_conflict (M por referência quebrada)

Detecção de conflitos

Para cada content_change, o serviço conflict_detection executa o algoritmo de detecção (especificado em [REF-30-B]):

Conflito com Trilha Pedagógica — o sistema busca Trilhas que referenciam a Unidade alterada. Para cada item removido ou modificado que a Trilha selecionava especificamente, um content_conflict do tipo trail é criado.

Conflito com Plano do Aluno — o sistema busca Planos do Aluno ativos que usam a Unidade. Para cada item removido que o Aluno tinha selecionado, verifica se o acionamento daquele Plano do Aluno está vinculado a um Snapshot que contém a versão/configuração efetivamente usada. A mera existência de outro Snapshot para a Unidade, mas com versão ou configuração diferente, não protege esse acionamento. Se não houver Snapshot correspondente, um content_conflict do tipo plan é criado. Item atualizado (não removido) não gera conflito com Plano.

Snapshot protege o Aluno

Se o acionamento do Plano do Aluno está vinculado a um Snapshot da versão/configuração que ele usa, o Aluno está protegido — nenhum conflito é gerado, e o estudo continua com aquele conteúdo. Snapshots de outra versão ou configuração não substituem esse vínculo.

Regras de severity

A severity de cada conflito é determinada pela seção afetada:

Severity Seções
high question_truefalse, question_multichoice, question_essay — impacta avaliações
medium topic, video — impacta Leitura, Resumo, Estudo Dirigido, aulas
low flashcard, audio, info, relations — formativo, complementar ou editorial

A severity pode ser promovida a critical se houver conflito simultâneo com Trilha e Plano, ou se mais de 50% dos items de uma seção de questões forem removidos.

Consequências por tipo de conflito

Conflito com Trilha (trail):

  • Bloqueia nova publicação da Trilha até resolução.
  • Opções de resolução: content_restored (conteúdo restaurado), trail_adapted (Trilha editada), dismissed (Gestor aceita inconsistência — raro, requer justificativa).
  • Ação “Verificar novamente” na UI re-executa a checagem; se a inconsistência foi resolvida, o conflito é auto-arquivado.

Conflito com Plano do Aluno (plan):

  • Não bloqueia nada — o estudo do Aluno continua.
  • Opções de resolução: dismissed (ignora item perdido — padrão), use_last_valid (usa última versão válida), plan_adapted (Gestor seleciona substituto), content_restored.

Cascata de status

A resolução dos conflitos segue uma cascata determinística:

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

Pseudocódigo completo da cascata e do algoritmo de detecção em [REF-30-B].

Relatório de Alterações e aprovação por item

O Relatório de Alterações é a visão do Gestor Pedagógico sobre o que mudou no conteúdo vindo do Word. Ele compara o conteúdo base em uso (o Snapshot) com o conteúdo mais recente da Unidade (unit_content), item a item, sem criar um log paralelo: parte das versões e dos Snapshots que já existem. Continua sendo uma view/query; o que se persiste é a decisão do Gestor sobre cada item.

Estado de implementação

O epic moodle-local_helico#118 está implementado em duas entregas. A primeira: chave e hash por item, comparação item a item, markdown determinístico, registro da decisão do Gestor com o sinal assíncrono content_item_approved, painel no Moodle e backfill do legado. A segunda, que consome esse sinal: aplicação do item aprovado aos Snapshots, revisão de simulado lendo do Snapshot, recálculo de nota por gabarito alterado, atualização do texto das atividades de correção da questão escrita e oferta de atualização de tópico no Caderno. O aviso ao Aluno sobre a oferta não foi construído: existe apenas o sinal assíncrono notebook_topic_update_offered, e o portal não foi alterado.

Chave por item

Cada item do Word que o Gestor pode decidir tem uma chave canônica, gerada pelo parser com o prefixo do IDNUMBER da Disciplina (ver a tabela de identificadores nesta página). A chave é gravada junto do item no unit_content e herdada pelo Snapshot, ao lado de um id inteiro estável: alocado uma vez por chave, nunca reusado e não mais derivado da posição do item. Cada item guarda também o hash do próprio conteúdo e, nas questões, o hash do gabarito (resposta correta e alternativas; na questão escrita, o espelho e os critérios). Esses campos não entram no content_hash do Snapshot, para não invalidar Snapshots existentes.

Item Chave no Word Granularidade da decisão
Tópico UXXX_TYY Tópico inteiro
Questão VF VF_QZZ Questão inteira
Questão objetiva OBJ_QZZ Questão inteira
Questão escrita DISC_QZZ, DISSERT_QZZ, PP_QZZ Questão inteira
Informações gerais subchaves overview, legislation, jurisprudence Por subchave
Vídeo campo video (url, title) Item inteiro

A chave é gravada exatamente como o parser a emite (IDNUMBER_U001_T01, IDNUMBER_VF_Q01…); a ausência ou a repetição da chave dentro de uma Unidade é erro de validação do conteúdo e bloqueia o processamento do arquivo. O id inteiro estável fica na tabela helico_unit_item_key (Unidade, tipo, chave, id), alocado como max + 1 dentro do tipo; inserir, remover ou reordenar itens no Word não muda o id dos demais. Conteúdo e Snapshots anteriores à chave são levados ao padrão pelo backfill: a chave de cada versão é recuperada do JSON bruto da própria versão (por isso o JSON de um arquivo arquivado é retido), conferida pelo texto do item; o que não casa de forma inequívoca fica sem chave, aparece no relatório e não pode ser decidido por item.

Dentro de um item não há merge: ou o item novo substitui o item em uso, ou não. Flashcards e áudios ficam fora do relatório: continuam sendo decisão do Gestor pelo botão de gerar na versão do arquivo da Disciplina. Ao lado de cada tópico alterado, o relatório apenas informa “áudio e flashcards ainda não regenerados”, sem bloquear nada.

Estados e classificação

Cada item aparece como alterado, adicionado ou removido no Word. As questões recebem ainda uma classificação do tipo de mudança, calculada pela comparação dos hashes:

Classificação Critério Efeito previsto na nota (fase seguinte)
gabarito hash do gabarito diferente Nota recalculada, com registro do antes e do depois
texto só o hash do item muda Nota mantida
removida a chave deixou de existir no Word A questão permanece no Snapshot; nota mantida
adicionada chave nova Não se aplica

Questão escrita nunca recalcula nota: a correção do professor permanece, e o texto atualizado também deve aparecer na tela de correção do mod_assign.

Ações do Gestor

O Gestor decide por item (ou em lote, por Disciplina ou por Unidade) entre:

  • Aprovar — registra a decisão (autor, data, chave, hash anterior e novo) e emite o sinal assíncrono content_item_approved. Nesta entrega não há consumidor do sinal.
  • Arquivar — mantém o item sem ação; fica no histórico e pode ser aprovado depois.

Um item que muda de novo depois de decidido volta a ser pendente. Esse fluxo substitui o antigo “Notificar o Aluno / Arquivar registro” por content_change: a decisão passa a ser por item, e a comunicação ao Aluno deixa de ser um aviso avulso e passa a fazer parte da fase seguinte. A decisão continua sendo do Gestor — nunca do sistema.

Painel

O painel vive no Moodle, em página administrativa:

  • lista só as Unidades com mudança pendente (Unidade sem mudança não aparece), com filtros por Disciplina e Unidade;
  • abas Pendentes, Arquivados e Histórico;
  • diff em markdown, “em uso” contra “novo”, alternável entre visão em linha e lado a lado, com destaque por palavra;
  • impacto antes de aprovar: alunos que usam o Snapshot e, para gabarito alterado, quantas notas seriam recalculadas;
  • ações Aprovar e Arquivar por item e em lote; o lote que inclui gabarito alterado pede confirmação com a contagem de notas afetadas.

O acesso é por capability própria, e não por is_siteadmin(). O Gestor Pedagógico é o papel responsável; o termo “coordenador” usado pela HÉLICO ainda precisa de confirmação.

Implementação da primeira entrega

Peça Onde
Origem do JSON da versão unit_content_source_service: dado um unit_content, devolve o JSON bruto do file_word que o originou ou o motivo de estar indisponível; cli/diagnose_unit_content_source.php lista os vínculos quebrados
Chave e id estável unit_item_id_allocator_service e tabela helico_unit_item_key; key, hash e answer_hash nos VOs topic e question_*
Comparação item a item unit_item_diff_service: lado “em uso” (último Snapshot da Unidade) contra o conteúdo mais recente; reordenar não é mudança; item fora do escopo do Snapshot não conta como adicionado; content_change.snapshot_id e o diff por item são gravados ao abrir a revisão
Markdown item_markdown_service: um bloco por item, ancorado pela chave (## IDNUMBER_U001_T01) ou, no legado, pela posição (“sem chave”); os hashes não entram no markdown
Decisão content_item_decision_service e tabela helico_content_item_decision (uma linha por Unidade, tipo, chave e hash novo; item com hash novo não tem linha e volta a pendente; guarda o resumo para o aluno e o item em markdown, antes e depois, como o Gestor o viu, porque depois de aplicado o Snapshot não tem mais o texto antigo); sinais content_item_approved e content_item_archived. A aba Histórico mostra cada decisão com esse diff (GET .../change-report/history/{id}); o aprovar em lote vale também para os arquivados (scope: archived)
Leitura do painel change_report_service; API em helico/admin/api/v1/change-report e página /admin/change-report (rota helico_admin_change_report)
Acesso capabilities local/helico:viewchangereport (ler) e local/helico:managechangereport (aprovar e arquivar), concedidas por padrão ao papel manager; atribua-as ao papel do Gestor Pedagógico. O link do menu Hélico só aparece para quem tem a de leitura
Backfill do legado migration migration_2026101503_unit_item_key_backfill e cli/backfill_unit_item_keys.php (--dry-run só lista); idempotente, não altera ids, content_hash, config_hash nem ativações

O impacto mostrado antes de aprovar é a contagem de alunos que estudam do Snapshot e, para gabarito alterado de questão V/F ou objetiva, o número de sessões com resposta à questão. Como a resposta guarda o id da questão mas não o tipo, e V/F, objetiva e escrita numeram a partir de 1, essa contagem é um limite superior.

Do item aprovado ao Aluno (segunda entrega)

Aprovar um item emite content_item_approved. Daí em diante tudo é assíncrono, com tentativa repetida em caso de falha, e idempotente:

content_item_approved
  └─ content_item_apply_listener_service  →  content_item_application_service
        escreve o item em todos os Snapshots da Unidade e emite content_item_applied
              ├─ question_regrade_listener_service        recálculo de nota (gabarito alterado)
              ├─ written_question_assign_listener_service texto das atividades do mod_assign
              └─ notebook_topic_offer_listener_service    oferta no Caderno (tópico)
Peça Regra
Aplicar ao Snapshot (content_item_application_service, tabela de auditoria helico_content_item_application) O item é achado em cada Snapshot da Unidade pela chave do Word; no Snapshot anterior às chaves, pelo id inteiro com que a chave foi semeada. O conteúdo mais recente substitui o item mantendo o id inteiro que aquele Snapshot deu a ele. Só o item muda: o resto do Snapshot, o áudio e os hashes de identidade ficam como estão. Item adicionado no Word entra só em Snapshot que carrega a Unidade inteira (sem recorte de escopo). Questão ou tópico removido no Word permanece no Snapshot. Se o item mudou de novo depois da aprovação, nada é aplicado. Cada aplicação grava Unidade, Snapshot, chave, hash anterior e novo, desfecho e autor. Roda sob o mesmo bloqueio por Unidade da ativação.
Consistência do Snapshot O content_hash com que o Snapshot nasceu é proveniência. is_consistent considera o Snapshot consistente se esse hash ainda bate com o conteúdo vivo ou se o conteúdo que o Snapshot carrega hoje, depois dos itens aplicados, bate com o vivo (só vale para Snapshot sem recorte de escopo). A ativação de um Aluno novo reaproveita um Snapshot nessa situação em vez de criar outro.
Resposta com identidade (answered_question_resolver_service, colunas questionkey, questionhash, answerhash em helico_response) Nos simulados objetivo e V/F, cada resposta grava a chave da questão, o hash da questão e o hash do conteúdo da alternativa escolhida (V/F: do valor). O hash do texto ignora a marcação que a conversão do Word embaralha. Resposta sem chave recuperável fica de fora do recálculo. A questão escrita não grava nada disso.
Recálculo de nota (question_regrade_service, auditoria helico_response_regrade) Só quando o gabarito de uma questão objetiva ou V/F mudou. Compara o hash da alternativa que o Aluno escolheu com o hash do conteúdo da correta hoje: reordenar as alternativas não muda nota, e texto sem mudar o gabarito mantém a nota. Atualiza helico_response.correct e as contagens e nota_real do resultado, em transação, e registra a nota antes e depois. Questão escrita nunca recalcula. Não propaga ao gradebook do Moodle (a decisão com a HÉLICO continua em aberto), não recalcula a classificação nem nota_bruta/nota_ajustada; os relatórios do Aluno são invalidados pelo sinal session_regraded.
Revisão de simulado Enunciado, alternativas, gabarito e comentário da objetiva vêm do Snapshot ativo do Aluno, achando a questão pela chave gravada com a resposta ou pelo id. O contexto congelado do slot só entra quando o Snapshot não tem a questão. O acerto mostrado é o gravado com a resposta (o mesmo da nota); resposta antiga, sem a identidade, é comparada com o gabarito. A letra mostrada como escolhida é a da alternativa que o Aluno escolheu no Snapshot de hoje, achada pelo hash. Na revisão V/F o enunciado também vem do Snapshot.
Questão escrita no mod_assign (exam_assign_text_sync_service) Atualiza só name, intro e activity das atividades da questão, em qualquer curso e bloco, achadas pelo idnumber do módulo (helico_exam_<curso>_<bloco>_u<unidade>_q<questão>; o id da questão é o que o Snapshot do plano que criou a atividade deu a ela, por isso a atualização vai Snapshot a Snapshot). Notas, submissões, arquivos e vínculos não são tocados, nem em atividade já corrigida. O reconcile passa a informar divergência de texto e resync_texts a corrige sob demanda. A IA de correção continua lendo o Snapshot do plano.
Oferta no Caderno (notebook_topic_offer_service, tabela helico_notebook_topic_offer) Cada Aluno com artefato do tópico, e cujo Snapshot já traz o texto aprovado, recebe uma oferta (offered, accepted, declined) e o sinal notebook_topic_update_offered. Quem não tem artefato não recebe oferta. API do Aluno em api/v1/platform/notebook/topic-offers (listar, aceitar, recusar; oferta de outro Aluno responde como inexistente). Aceitar guarda o HTML anterior em helico_notebook_version e grava o texto novo; se o Aluno tinha editado, a versão dele fica logo abaixo do texto novo, sob o título “Sua versão anterior”, com os nós intactos, então as anotações continuam presas às marcas. Se nunca editou, o texto novo substitui. Recusar não altera nada. Aceitar uma oferta cujo tópico mudou de novo é recusado (409).
Backfill das respostas Migration migration_2026101507_response_identity_backfill e cli/backfill_response_identity.php (--dry-run): preenchem chave e hashes das respostas de simulados antigos lendo o Snapshot de hoje; o que o Snapshot não traz com chave, sem Unidade conhecida ou fora de simulado fica como está.

O que não foi feito: o aviso ao Aluno (badge e entrega pelo portal), reverter uma aprovação (o hash anterior fica na auditoria, mas não há ação), propagar o recálculo ao gradebook, recalcular a classificação do Aluno e atualizar a revisão dos diagnósticos (DI e SVD), que não entram no recálculo de nota e continuam comparando a resposta com o gabarito do Snapshot; o acerto mostrado ali só fica igual ao gravado enquanto o gabarito da questão V/F não mudar.

Conflitos com Trilha e com Plano do Aluno, descritos nas seções anteriores, continuam como estão e fora desta frente.

Entidades envolvidas

Entidade Tipo Subdomain Papel
discipline entity_root content.base A Disciplina — aggregate root do conteúdo
file_word entity_root content.management Registro do arquivo Word (o arquivo em si é attribute)
sync_job entity_child content.management Registro de execução da sincronização

Signals emitidos neste ato

Signal Quando
file_word_created Novo file_word registrado após sync
file_word_preprocessed Pré-processamento concluído com sucesso

Ato 2 — O conteúdo vira Base de Conteúdo

O Gestor processa

O Gestor acessa a Disciplina no backend Moodle e vê a lista de versões do file_word. Somente a versão mais recente pode ser processada — versões anteriores aparecem desabilitadas. A tela mostra uma prévia: as Unidades do manifest e um diff visual comparando com a versão anterior (se houver).

O Gestor pode preencher motivação e contexto (opcionais — o sistema gera fallback automático: “Reprocessamento de version N”). Ao clicar “Processar”, o serviço publication assume:

  1. Guards: verifica lock por Disciplina, confirma que é o file_word mais recente, checa idempotência (se o hash já foi processado, retorna already_processed).
  2. Lock: adquire lock exclusivo por Disciplina.
  3. Manifest: lê o JSON manifest do file_storage.

Criação e atualização de Unidades

Para cada Unidade no manifest:

  1. O sistema localiza ou cria o registro unit (entity_root, EAV). Se a Unidade é nova, um curso-unidade Moodle é criado atomicamente, com o mesmo IDNUMBER. O signal unit_created é emitido.
  2. Computa hashes por seção: info_hash, topic_hash, flashcard_hash, video_hash, audio_hash, hashes de questões e relations_hash.
  3. Compara o hash consolidado com unit.current_content_hash. Se igual, a Unidade não mudou — skip.
  4. Se diferente, cria um novo unit_content (entity_child, version N+1). O unit_content é o coração da Base de Conteúdo — contém todas as seções do conteúdo pedagógico da Unidade.

Estrutura do unit_content

O unit_content é composto por seções, cada uma representada por Value Objects imutáveis:

unit_content (version N)
  ├── info        → unit_info (overview, legislation, jurisprudence, doctrine)
  ├── topics      → topic[] (cada um com subtitle, observations, synthesis)
  ├── flashcards  → flashcards (seção embarcada, não EAV)
  ├── videos      → video[]
  ├── questions   → question_multiplechoice[] | question_truefalse[] | question_written[]
  └── relations   → grafo de vínculos entre items

Cada VO é uma readonly class com métodos from_array e to_array — imutável, sem identidade própria, sem persistência EAV separada. Os três tipos de questão implementam o contrato polimórfico question_contract (interface PHP manual com get_statement(), get_difficulty(), etc.).

Estrutura detalhada dos Materiais Didáticos

Cada Unidade contém Informações Gerais e 5 tipos de Materiais Didáticos. Os campos abaixo correspondem aos contratos JSON em .vigim/ddd/json-schema/contract/.

Informações Gerais (unit_info)

Conjunto de informações de contexto e apoio associadas à Unidade:

Campo Tipo Obrigatório Descrição
overview texto rico Sim Resumo dos tópicos abordados (equivale ao “Quadro Geral de Informações” do Word)
legislation texto rico Não Textos legais relacionados à Unidade
jurisprudence texto rico Não Decisões judiciais e precedentes
video_url URL Não Vídeo de apoio da Unidade
audios arquivo[] Não Material de áudio complementar (utiliza o mais recente)
conteudistas string[] Não Lista de autores responsáveis pela criação do conteúdo

Tópico de Conteúdo (topic)

Textos diretos e comentados elaborados pelos professores:

Campo Tipo Obrigatório Descrição
title texto plano Sim Título do tópico
subtitle texto plano Não Subtítulo (Heading 3 no Word)
synthesis texto rico Sim Conteúdo do tópico — corpo principal
observations texto rico Não Observações ou comentários do professor

Questão VF (question_truefalse)

As Questões VF compartilham um vídeo explicativo único por Unidade:

Campo Tipo Obrigatório Descrição
video_url URL Não Vídeo explicativo (único para todas as VF da Unidade)
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
correct_answer boolean Sim Verdadeiro ou Falso
feedback texto rico Sim Comentário/explicação da questão

Questão Objetiva (question_multichoice)

As Questões Objetivas compartilham um vídeo explicativo único por Unidade:

Campo Tipo Obrigatório Descrição
video_url URL Não Vídeo explicativo (único para todas as Objetivas da Unidade)
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
alternatives texto rico[] Sim Até 6 alternativas (mínimo 2)
correct_answer texto rico Sim Resposta correta (texto)
feedback texto rico Sim Comentário/explicação da questão

Questão Escrita (question_essay)

Campo Tipo Obrigatório Descrição
format enum essay_format Sim Tipo: dissertativa, petição, opinião, sentença
category enum question_category Sim Lei, Doutrina ou Jurisprudência
statement texto rico Sim Enunciado da questão
answer_key texto rico Sim Espelho de correção (padrão de resposta esperado)
correction_criteria texto rico Sim Critérios de avaliação
reference_answer texto rico Não Autorresposta elaborada pelo professor
max_score número Sim Pontuação máxima da questão
video_url URL Não Vídeo explicativo (um por questão escrita, não compartilhado)

Flashcard (flashcard)

Campo Tipo Obrigatório Descrição
assertion texto rico Sim Conceito ou pergunta apresentada (frente)
answer texto rico Sim Explicação ou resposta (verso)
position número Sim Ordem dentro da lista
generated_at datetime Sim Registro de quando o flashcard foi criado (pela API)

Flashcards são gerados por IA

Os flashcards não vêm do Word — são gerados pela API externa (Law School) a partir do Markdown dos Tópicos. O Conteudista não os escreve manualmente. Ver seção “Flashcards — fluxo desacoplado” abaixo.

Campos internos, não VOs

doctrine, jurisprudence e legislation são campos textuais do unit_info — não geram classes próprias. synthesis é campo do topic, não VO independente.

Unidades que desaparecem

Se uma Unidade existia na versão anterior mas não está no manifest atual, o sistema:

  • Transiciona o unit para status archived.
  • Bloqueia o curso-unidade Moodle correspondente.
  • Emite signal unit_archived.

Se a Unidade reaparecer em processamento futuro, um novo unit_content é sempre criado (não restaura o anterior).

Flashcards — fluxo desacoplado

A geração de flashcards é deliberadamente separada do processamento principal. O motivo é prático: a API externa (Law School) leva 5 a 20 minutos para responder, e bloquear o Gestor durante esse tempo seria inaceitável.

O fluxo funciona assim:

  1. O Gestor aciona “Gerar Flashcards”. O botão só está ativo se o hash do Markdown de Tópicos mudou desde a última geração.
  2. Um flashcard_job é criado com status generating. O Markdown é enviado para a API externa.
  3. Se a API falha por rede/timeout, o job transiciona para failed_retryable (retry automático com backoff). Se a falha é de negócio, transiciona para failed (Gestor notificado).
  4. Quando a resposta chega, o flashcard_raw é salvo no file_storage. O signal flashcard_job_generated dispara uma ad_hoc task de persistência.
  5. A persistência distribui os flashcards para os unit_content existentes por match de topic_ref (título do tópico). Flashcards que não casam com nenhum tópico ficam como “não alocados”, visíveis no dashboard do Gestor.

Pseudocódigo completo do fluxo de flashcards em [REF-30-A], Step 4.

Entidades e VOs envolvidos

Componente Tipo Subdomain Papel
unit entity_root content.base A Unidade — vinculada a uma Disciplina
unit_content entity_child content.base Versão do conteúdo (N versões por unit)
unit_info value_object content.base Seção info (overview, legislação, jurisprudência, doutrina)
topic value_object content.base Tópico com subtitle, observations e synthesis
flashcards value_object content.base Seção embarcada no unit_content
video value_object content.base Asset de vídeo no content_bank
question_multiplechoice value_object content.base.bank_question Questão objetiva
question_truefalse value_object content.base.bank_question Questão verdadeiro/falso
question_written value_object content.base.bank_question Questão escrita
process_job entity_child content.management Registro de execução do processamento
flashcard_job entity_child content.management Registro de execução da geração de flashcards

Signals emitidos neste ato

Signal Quando
unit_created Nova Unidade registrada
unit_content_published Nova versão do conteúdo criada
unit_archived Unidade desapareceu do manifest
file_word_processed Processamento concluído
flashcard_job_generated Flashcards retornados da API
flashcard_job_persisted Flashcards distribuídos nos unit_content

Ato 3 — O conteúdo muda e conflitos são tratados

Content revision

A partir do segundo processamento de uma Disciplina, quando hashes diferem, o sistema entra no fluxo de alteração pedagógica. O serviço publication, após criar as novas versões de unit_content, delega ao serviço content_revision:

  1. Um content_revision é criado com status open, vinculado ao file_word e à Disciplina. A motivação e o contexto preenchidos pelo Gestor (ou fallback automático) ficam registrados.
  2. Para cada Unidade cujo hash mudou, um content_change é criado. Esse registro contém o diff item a item, separado por seção (diff_info, diff_topic, diff_flashcard, etc.), além das versões anterior e nova do unit_content.

A hierarquia é clara e estável:

content_revision (1 por reprocessamento — o evento)
  └── content_change (N por Unidade alterada — contém diff)
        └── content_conflict (M por referência quebrada)

Detecção de conflitos

Para cada content_change, o serviço conflict_detection executa o algoritmo de detecção (especificado em [REF-30-B]):

Conflito com Trilha Pedagógica — o sistema busca Trilhas que referenciam a Unidade alterada. Para cada item removido ou modificado que a Trilha selecionava especificamente, um content_conflict do tipo trail é criado.

Conflito com Plano do Aluno — o sistema busca Planos do Aluno ativos que usam a Unidade. Para cada item removido que o Aluno tinha selecionado, verifica se o acionamento daquele Plano do Aluno está vinculado a um Snapshot que contém a versão/configuração efetivamente usada. A mera existência de outro Snapshot para a Unidade, mas com versão ou configuração diferente, não protege esse acionamento. Se não houver Snapshot correspondente, um content_conflict do tipo plan é criado. Item atualizado (não removido) não gera conflito com Plano.

Snapshot protege o Aluno

Se o acionamento do Plano do Aluno está vinculado a um Snapshot da versão/configuração que ele usa, o Aluno está protegido — nenhum conflito é gerado, e o estudo continua com aquele conteúdo. Snapshots de outra versão ou configuração não substituem esse vínculo.

Regras de severity

A severity de cada conflito é determinada pela seção afetada:

Severity Seções
high question_truefalse, question_multichoice, question_essay — impacta avaliações
medium topic, video — impacta Leitura, Resumo, Estudo Dirigido, aulas
low flashcard, audio, info, relations — formativo, complementar ou editorial

A severity pode ser promovida a critical se houver conflito simultâneo com Trilha e Plano, ou se mais de 50% dos items de uma seção de questões forem removidos.

Consequências por tipo de conflito

Conflito com Trilha (trail):

  • Bloqueia nova publicação da Trilha até resolução.
  • Opções de resolução: content_restored (conteúdo restaurado), trail_adapted (Trilha editada), dismissed (Gestor aceita inconsistência — raro, requer justificativa).
  • Ação “Verificar novamente” na UI re-executa a checagem; se a inconsistência foi resolvida, o conflito é auto-arquivado.

Conflito com Plano do Aluno (plan):

  • Não bloqueia nada — o estudo do Aluno continua.
  • Opções de resolução: dismissed (ignora item perdido — padrão), use_last_valid (usa última versão válida), plan_adapted (Gestor seleciona substituto), content_restored.

Cascata de status

A resolução dos conflitos segue uma cascata determinística:

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

Pseudocódigo completo da cascata e do algoritmo de detecção em [REF-30-B].

Relatório de Alterações e aprovação por item

O Relatório de Alterações é a visão do Gestor Pedagógico sobre o que mudou no conteúdo vindo do Word. Ele compara o conteúdo base em uso (o Snapshot) com o conteúdo mais recente da Unidade (unit_content), item a item, sem criar um log paralelo: parte das versões e dos Snapshots que já existem. Continua sendo uma view/query; o que se persiste é a decisão do Gestor sobre cada item.

Estado de implementação

O epic moodle-local_helico#118 está implementado em duas entregas. A primeira: chave e hash por item, comparação item a item, markdown determinístico, registro da decisão do Gestor com o sinal assíncrono content_item_approved, painel no Moodle e backfill do legado. A segunda, que consome esse sinal: aplicação do item aprovado aos Snapshots, revisão de simulado lendo do Snapshot, recálculo de nota por gabarito alterado, atualização do texto das atividades de correção da questão escrita e oferta de atualização de tópico no Caderno. O aviso ao Aluno sobre a oferta não foi construído: existe apenas o sinal assíncrono notebook_topic_update_offered, e o portal não foi alterado.

Chave por item

Cada item do Word que o Gestor pode decidir tem uma chave canônica, gerada pelo parser com o prefixo do IDNUMBER da Disciplina (ver a tabela de identificadores nesta página). A chave é gravada junto do item no unit_content e herdada pelo Snapshot, ao lado de um id inteiro estável: alocado uma vez por chave, nunca reusado e não mais derivado da posição do item. Cada item guarda também o hash do próprio conteúdo e, nas questões, o hash do gabarito (resposta correta e alternativas; na questão escrita, o espelho e os critérios). Esses campos não entram no content_hash do Snapshot, para não invalidar Snapshots existentes.

Item Chave no Word Granularidade da decisão
Tópico UXXX_TYY Tópico inteiro
Questão VF VF_QZZ Questão inteira
Questão objetiva OBJ_QZZ Questão inteira
Questão escrita DISC_QZZ, DISSERT_QZZ, PP_QZZ Questão inteira
Informações gerais subchaves overview, legislation, jurisprudence Por subchave
Vídeo campo video (url, title) Item inteiro

A chave é gravada exatamente como o parser a emite (IDNUMBER_U001_T01, IDNUMBER_VF_Q01…); a ausência ou a repetição da chave dentro de uma Unidade é erro de validação do conteúdo e bloqueia o processamento do arquivo. O id inteiro estável fica na tabela helico_unit_item_key (Unidade, tipo, chave, id), alocado como max + 1 dentro do tipo; inserir, remover ou reordenar itens no Word não muda o id dos demais. Conteúdo e Snapshots anteriores à chave são levados ao padrão pelo backfill: a chave de cada versão é recuperada do JSON bruto da própria versão (por isso o JSON de um arquivo arquivado é retido), conferida pelo texto do item; o que não casa de forma inequívoca fica sem chave, aparece no relatório e não pode ser decidido por item.

Dentro de um item não há merge: ou o item novo substitui o item em uso, ou não. Flashcards e áudios ficam fora do relatório: continuam sendo decisão do Gestor pelo botão de gerar na versão do arquivo da Disciplina. Ao lado de cada tópico alterado, o relatório apenas informa “áudio e flashcards ainda não regenerados”, sem bloquear nada.

Estados e classificação

Cada item aparece como alterado, adicionado ou removido no Word. As questões recebem ainda uma classificação do tipo de mudança, calculada pela comparação dos hashes:

Classificação Critério Efeito previsto na nota (fase seguinte)
gabarito hash do gabarito diferente Nota recalculada, com registro do antes e do depois
texto só o hash do item muda Nota mantida
removida a chave deixou de existir no Word A questão permanece no Snapshot; nota mantida
adicionada chave nova Não se aplica

Questão escrita nunca recalcula nota: a correção do professor permanece, e o texto atualizado também deve aparecer na tela de correção do mod_assign.

Ações do Gestor

O Gestor decide por item (ou em lote, por Disciplina ou por Unidade) entre:

  • Aprovar — registra a decisão (autor, data, chave, hash anterior e novo) e emite o sinal assíncrono content_item_approved. Nesta entrega não há consumidor do sinal.
  • Arquivar — mantém o item sem ação; fica no histórico e pode ser aprovado depois.

Um item que muda de novo depois de decidido volta a ser pendente. Esse fluxo substitui o antigo “Notificar o Aluno / Arquivar registro” por content_change: a decisão passa a ser por item, e a comunicação ao Aluno deixa de ser um aviso avulso e passa a fazer parte da fase seguinte. A decisão continua sendo do Gestor — nunca do sistema.

Painel

O painel vive no Moodle, em página administrativa:

  • lista só as Unidades com mudança pendente (Unidade sem mudança não aparece), com filtros por Disciplina e Unidade;
  • abas Pendentes, Arquivados e Histórico;
  • diff em markdown, “em uso” contra “novo”, alternável entre visão em linha e lado a lado, com destaque por palavra;
  • impacto antes de aprovar: alunos que usam o Snapshot e, para gabarito alterado, quantas notas seriam recalculadas;
  • ações Aprovar e Arquivar por item e em lote; o lote que inclui gabarito alterado pede confirmação com a contagem de notas afetadas.

O acesso é por capability própria, e não por is_siteadmin(). O Gestor Pedagógico é o papel responsável; o termo “coordenador” usado pela HÉLICO ainda precisa de confirmação.

Implementação da primeira entrega

Peça Onde
Origem do JSON da versão unit_content_source_service: dado um unit_content, devolve o JSON bruto do file_word que o originou ou o motivo de estar indisponível; cli/diagnose_unit_content_source.php lista os vínculos quebrados
Chave e id estável unit_item_id_allocator_service e tabela helico_unit_item_key; key, hash e answer_hash nos VOs topic e question_*
Comparação item a item unit_item_diff_service: lado “em uso” (último Snapshot da Unidade) contra o conteúdo mais recente; reordenar não é mudança; item fora do escopo do Snapshot não conta como adicionado; content_change.snapshot_id e o diff por item são gravados ao abrir a revisão
Markdown item_markdown_service: um bloco por item, ancorado pela chave (## IDNUMBER_U001_T01) ou, no legado, pela posição (“sem chave”); os hashes não entram no markdown
Decisão content_item_decision_service e tabela helico_content_item_decision (uma linha por Unidade, tipo, chave e hash novo; item com hash novo não tem linha e volta a pendente; guarda o resumo para o aluno e o item em markdown, antes e depois, como o Gestor o viu, porque depois de aplicado o Snapshot não tem mais o texto antigo); sinais content_item_approved e content_item_archived. A aba Histórico mostra cada decisão com esse diff (GET .../change-report/history/{id}); o aprovar em lote vale também para os arquivados (scope: archived)
Leitura do painel change_report_service; API em helico/admin/api/v1/change-report e página /admin/change-report (rota helico_admin_change_report)
Acesso capabilities local/helico:viewchangereport (ler) e local/helico:managechangereport (aprovar e arquivar), concedidas por padrão ao papel manager; atribua-as ao papel do Gestor Pedagógico. O link do menu Hélico só aparece para quem tem a de leitura
Backfill do legado migration migration_2026101503_unit_item_key_backfill e cli/backfill_unit_item_keys.php (--dry-run só lista); idempotente, não altera ids, content_hash, config_hash nem ativações

O impacto mostrado antes de aprovar é a contagem de alunos que estudam do Snapshot e, para gabarito alterado de questão V/F ou objetiva, o número de sessões com resposta à questão. Como a resposta guarda o id da questão mas não o tipo, e V/F, objetiva e escrita numeram a partir de 1, essa contagem é um limite superior.

Fase seguinte (planejada, não implementada)

Cada ação abaixo consome o sinal content_item_approved e tem issue própria no epic:

  • Aplicar o item aprovado ao Snapshot. O conteúdo base do Snapshot é atualizado, por chave, em todos os Snapshots da Unidade que contêm a chave, preservando o id inteiro de cada Snapshot. Questão removida no Word permanece. Essa mudança contraria a imutabilidade descrita no ADR-11 (o Snapshot é compartilhado e o content_hash passa a ser proveniência, não identidade) e exige atualizar o contrato.
  • Tópico no Caderno Online. O Caderno do Aluno contém o artefato dele (anotações e edições), que não é alterado pela aprovação. Quem tem artefato do tópico recebe uma oferta e decide se leva o texto novo ao próprio Caderno: aceitar grava uma nova versão do artefato, preservando a anterior; recusar mantém como está. Questão, informações gerais e vídeo mudam direto no Snapshot, sem etapa do Aluno.
  • Revisão de simulado lendo enunciado, alternativas, gabarito e comentário da mesma fonte, o Snapshot ativo do Aluno, e recálculo de nota para gabarito alterado.
  • Questão escrita: atualizar enunciado e espelho nas atividades de correção do mod_assign, sem tocar em notas, submissões nem vínculos.

Conflitos com Trilha e com Plano do Aluno, descritos nas seções anteriores, continuam como estão e fora desta frente.

Entidades envolvidas

Entidade Tipo Subdomain Papel
content_revision entity_root content.change O evento de reprocessamento
content_change entity_child content.change Diff de uma Unidade alterada
content_conflict entity_child content.change Uma referência quebrada
content_item_decision tabela dedicada content.change Decisão do Gestor sobre um item (helico_content_item_decision)
unit_item_key tabela dedicada content.base Id inteiro estável de cada chave do Word por Unidade (helico_unit_item_key)
content_item_application tabela dedicada content.change Auditoria da aplicação de um item aprovado a um Snapshot (helico_content_item_application)
response_regrade tabela dedicada content.change Antes e depois de uma resposta recalculada (helico_response_regrade)
notebook_topic_offer tabela dedicada activity.productive Oferta do texto novo de um tópico ao Aluno que tem artefato dele (helico_notebook_topic_offer)

Enums deste ato

Enum Valores
conflict_type trail, plan
conflict_status open, in_review, resolved, dismissed
conflict_reason item_removed, item_modified, section_removed
conflict_resolution_type content_restored, trail_adapted, plan_adapted, use_last_valid, dismissed
content_section info, topic, flashcard, video, audio, question_truefalse, question_multichoice, question_essay, relations
severity low, medium, high, critical
content_item_decision pending, approved, archived (decisão do Gestor por item; epic moodle-local_helico#118)
content_item_change changed, added, removed
question_change_kind answer_key, text, removed, added

Modelo de dados

Entities (EAV)

# Identifier Tipo Subdomain Gera
1 discipline entity_root content.base model + service + DTO + repository
2 unit entity_root content.base model + service + DTO + repository
3 file_word entity_root content.management model + service + DTO + repository
4 content_revision entity_root content.change model + service + DTO + repository
5 unit_content entity_child content.base model + DTO
6 content_change entity_child content.change model + DTO
7 content_conflict entity_child content.change model + DTO
8 sync_job entity_child content.management model + DTO
9 process_job entity_child content.management model + DTO
10 flashcard_job entity_child content.management model + DTO

Value Objects

# Identifier Subdomain Gera
11 unit_info content.base readonly class
12 topic content.base readonly class
13 flashcards content.base readonly class
14 video content.base readonly class
15 question_multiplechoice content.base.bank_question readonly class
16 question_truefalse content.base.bank_question readonly class
17 question_written content.base.bank_question readonly class

Services

# Identifier Subdomain Responsabilidade
18 publication content.management Orquestra o processamento: file_word para units para unit_content
19 file_word_process content.management Interpreta o Word, aplica Contrato Estrutural, gera manifest e Markdown
20 sharepoint_sync content.management Sincroniza Disciplinas com SharePoint via Microsoft Graph
21 unit_versioning content.base Gerencia versões de unit_content: cria versão, compara hashes

Commands

# Identifier Trigger Subdomain
22 unit_process cron content.management
23 flashcard_generate manual (Gestor) content.management
24 flashcard_persist cron content.management
25 file_word_autosync cron 30 7,18 content.management
26 file_word_manualsync cron */1 (fila) content.management
27 content_conflict_resolution manual (Gestor) content.change

Enums

# Identifier Subdomain
28 question_category content.base
29 conflict_type content.change
30 conflict_status content.change
31 conflict_reason content.change
32 conflict_resolution_type content.change
33 content_section content.change
34 severity content.change

Signals emitidos

Signal Payload Emitido por Listeners
file_word_created file_word_id, discipline_id, file_hash sharepoint_sync preprocess ad_hoc
file_word_preprocessed file_word_id, discipline_id, markdown_hash, unit_count file_word_process nenhum — Gestor decide
file_word_processed file_word_id, discipline_id, units_created/updated/archived, revision_id publication notification (Gestor)
unit_created unit_id, discipline_id, idnumber publication cross-domain
unit_archived unit_id publication cross-domain
unit_content_published unit_content_id, unit_id, version, content_hash publication cross-domain
content_revision_opened revision_id, file_word_id, discipline_id content_revision observabilidade
content_conflict_detected conflict_ids[], revision_id conflict_detection notification (Gestor)
content_conflict_resolved conflict_id, resolution_type content_conflict_resolution cascade check
content_item_approved unit_id, item_type, item_key, old_hash, new_hash, change_kind, user_id, decided_at content_item_decision nenhum nesta entrega
content_item_archived unit_id, item_type, item_key, old_hash, new_hash, change_kind, user_id, decided_at content_item_decision auditoria
flashcard_job_generated job_id, file_word_id, total_generated flashcard_generate flashcard_persist ad_hoc
flashcard_job_persisted job_id, total_persisted, unallocated flashcard_persist notification (Gestor)

Referências

  • ADR-30 — Decisões de arquitetura e mapa de materialização
  • REF-30-A — Pipeline de processamento: pseudocódigo, signals, critérios de aceitação
  • REF-30-B — Algoritmo de detecção de conflitos pedagógicos
  • Terms: content — Vocabulário canônico do domínio content
  • Contratos JSON — 64 contratos de validação
Navigation

Type to search…

↑↓ navigate↵ selectEsc close