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_V2MINHADISCIPLINA_2026,MINHADISCIPLINA_2026_REVISADAMINHADISCIPLINA_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:
- Todo o conteúdo é reprocessado — o novo manifest sobrescreve integralmente o anterior.
- Adição de conteúdo é transparente — novos componentes aparecem normalmente.
- Edição gera um
content_changecom 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). - 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_contentanterior 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:
- CRON automático — o command
file_word_autosyncexecuta duas vezes ao dia (7h30 e 18h30) e varre a pasta completa do SharePoint. - Sync manual — o Gestor aciona a sincronização de uma Disciplina específica, que entra em fila e é processada pelo CRON
file_word_manualsynca cada minuto.
Em ambos os casos, o serviço sharepoint_sync faz o trabalho:
- Lista os arquivos via Microsoft Graph adapter (autenticação por certificado ou client secret; ver Credenciais do Moodle no Microsoft Graph).
- Para cada arquivo com nome válido, extrai o IDNUMBER e localiza (ou cria) a
disciplinecorrespondente. - Compara o hash do arquivo remoto com o último
file_wordregistrado. Se o hash é igual, não há alteração — o arquivo é ignorado. - Se o hash difere, o Word é baixado para o
file_storagedo Moodle e um novo registrofile_wordé criado com statuscreated. - 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:
- O serviço
file_word_processlê o Word dofile_storage. - Aplica o Contrato Estrutural e o Catálogo de Tags — etapa interna
file_word_validation. Se o Word é inválido, o status transiciona parafailedcom log detalhado. - 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_storagevinculado aofile_word(não em coluna, para suportar documentos grandes). - 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.
- O
file_wordtransiciona para statuspreprocessed. - 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:
- Guards: verifica lock por Disciplina, confirma que é o
file_wordmais recente, checa idempotência (se o hash já foi processado, retornaalready_processed). - Lock: adquire lock exclusivo por Disciplina.
- Manifest: lê o JSON manifest do
file_storage.
Criação e atualização de Unidades
Para cada Unidade no manifest:
- 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 signalunit_createdé emitido. - Computa hashes por seção:
info_hash,topic_hash,flashcard_hash,video_hash,audio_hash, hashes de questões erelations_hash. - Compara o hash consolidado com
unit.current_content_hash. Se igual, a Unidade não mudou — skip. - Se diferente, cria um novo
unit_content(entity_child, version N+1). Ounit_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 itemsCada 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,jurisprudenceelegislationsão campos textuais dounit_info— não geram classes próprias.synthesisé campo dotopic, 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
unitpara statusarchived. - 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:
- 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.
- Um
flashcard_jobé criado com statusgenerating. O Markdown é enviado para a API externa. - 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 parafailed(Gestor notificado). - Quando a resposta chega, o
flashcard_rawé salvo nofile_storage. O signalflashcard_job_generateddispara uma ad_hoc task de persistência. - A persistência distribui os flashcards para os
unit_contentexistentes por match detopic_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:
- Um
content_revisioné criado com statusopen, vinculado aofile_worde à Disciplina. A motivação e o contexto preenchidos pelo Gestor (ou fallback automático) ficam registrados. - 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 dounit_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 → resolvedPseudocó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#118está 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íncronocontent_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íncrononotebook_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:
- Guards: verifica lock por Disciplina, confirma que é o
file_wordmais recente, checa idempotência (se o hash já foi processado, retornaalready_processed). - Lock: adquire lock exclusivo por Disciplina.
- Manifest: lê o JSON manifest do
file_storage.
Criação e atualização de Unidades
Para cada Unidade no manifest:
- 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 signalunit_createdé emitido. - Computa hashes por seção:
info_hash,topic_hash,flashcard_hash,video_hash,audio_hash, hashes de questões erelations_hash. - Compara o hash consolidado com
unit.current_content_hash. Se igual, a Unidade não mudou — skip. - Se diferente, cria um novo
unit_content(entity_child, version N+1). Ounit_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 itemsCada 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,jurisprudenceelegislationsão campos textuais dounit_info— não geram classes próprias.synthesisé campo dotopic, 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
unitpara statusarchived. - 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:
- 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.
- Um
flashcard_jobé criado com statusgenerating. O Markdown é enviado para a API externa. - 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 parafailed(Gestor notificado). - Quando a resposta chega, o
flashcard_rawé salvo nofile_storage. O signalflashcard_job_generateddispara uma ad_hoc task de persistência. - A persistência distribui os flashcards para os
unit_contentexistentes por match detopic_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:
- Um
content_revisioné criado com statusopen, vinculado aofile_worde à Disciplina. A motivação e o contexto preenchidos pelo Gestor (ou fallback automático) ficam registrados. - 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 dounit_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 → resolvedPseudocó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#118está 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íncronocontent_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íncrononotebook_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_hashpassa 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