REF-30-A: Pipeline de Processamento de Conteúdo
Status: Aceito Data: 2026-04-23 ADR: ADR-30 — Domínio Content: Arquitetura e Materialização Autor: Michael Meneses (Arquiteto)
Propósito
Especificação detalhada do pipeline de processamento de conteúdo para implementação pela equipe de desenvolvimento. Inclui fluxo operacional, signals emitidos, pseudocódigo de cada service/handler e critérios de aceitação.
Contexto de runtime
- Gestor Pedagógico opera no backend Moodle (admin)
- Aluno opera no frontend NextJS (via API REST)
- Jobs executam via Moodle ad_hoc tasks e scheduled tasks
- Signals usam o pattern outbox (ADR-707)
- Notificações via
message_senddo Moodle (2 providers:content_job_status,content_change_alert)
Step 1: Sincronização SharePoint
Fluxo
CRON (file_word_autosync: 30 7,18)
OU
Gestor aciona sync manual → fila → CRON (file_word_manualsync: */1)
│
▼
sharepoint_sync_service.sync(discipline_id?)
├── microsoft_graph_adapter.list_files(sharepoint_folder)
├── Para cada arquivo:
│ ├── Valida padrão do nome → extrai IDNUMBER
│ │ └── Se inválido → log + skip
│ ├── discipline = find_or_create(idnumber)
│ ├── Compara hash do arquivo remoto vs último file_word
│ │ └── Se igual → skip (sem alteração)
│ ├── Download do arquivo Word
│ ├── file_word = create(discipline_id, file_hash, file_storage_id)
│ └── emit signal: file_word_created(file_word_id)
└── Job: sync_job(status: completed, result: {files_checked, changes_detected})Signal: file_word_created
payload: { file_word_id: int, discipline_id: int, file_hash: string }
listeners:
- preprocess_listener → cria ad_hoc task para pré-processamentoPseudocódigo
// sharepoint_sync_service.php
public function sync(?int $discipline_id = null): sync_result {
$files = $this->graph_adapter->list_files($this->sharepoint_folder);
foreach ($files as $remote_file) {
$idnumber = $this->extract_idnumber($remote_file->name);
if ($idnumber === null) {
$this->logger->warning("Arquivo ignorado: {$remote_file->name}");
continue;
}
if ($discipline_id !== null && $idnumber !== $discipline_id) {
continue; // sync manual de disciplina específica
}
$discipline = $this->discipline_service->find_or_create($idnumber);
$last_file_word = $this->file_word_service->get_latest($discipline->id);
if ($last_file_word && $last_file_word->file_hash === $remote_file->hash) {
continue; // sem alteração
}
$file_storage_id = $this->download_and_store($remote_file);
$file_word = $this->file_word_service->create(
discipline_id: $discipline->id,
file_hash: $remote_file->hash,
file_storage_id: $file_storage_id,
);
$this->signal->emit('file_word_created', [
'file_word_id' => $file_word->id,
'discipline_id' => $discipline->id,
'file_hash' => $remote_file->hash,
]);
}
}Critérios de aceitação
- Arquivo com nome inválido é ignorado com log (sem erro)
- Arquivo sem alteração de hash não gera novo file_word
- Disciplina é criada automaticamente se não existir (idnumber único)
- Signal
file_word_createdemitido para cada novo file_word - sync_job registra status, timestamps e resultado
- Lock por discipline impede sync concorrente da mesma disciplina
- Notificação ao Gestor: “Sincronização concluída — N disciplinas atualizadas”
Step 2: Pré-processamento (ad_hoc)
Fluxo
Signal file_word_created → ad_hoc task
│
▼
file_word_process_service.preprocess(file_word_id)
├── Lê arquivo Word do file_storage
├── Aplica Contrato Estrutural + Catálogo de Tags
│ └── file_word_validation (etapa interna)
│ └── Se inválido → file_word.status = 'failed', log detalhado
├── Extrai unidades → gera JSON manifest
│ └── Salva como file_storage vinculado ao file_word
├── Gera Markdown de Tópicos (para flashcards)
│ ├── Salva como file_storage vinculado ao file_word
│ └── Computa hash do Markdown
├── file_word.status = 'preprocessed'
└── emit signal: file_word_preprocessed(file_word_id, markdown_hash)Signal: file_word_preprocessed
payload: { file_word_id: int, discipline_id: int, markdown_hash: string, unit_count: int }
listeners: (nenhum automático — Gestor decide próximo passo)Pseudocódigo
// file_word_process_service.php
public function preprocess(int $file_word_id): preprocess_result {
$file_word = $this->file_word_service->get($file_word_id);
$word_content = $this->file_storage->read($file_word->file_storage_id);
// Validação do Word (etapa interna)
$validation = $this->validate_word($word_content);
if (!$validation->is_valid) {
$file_word->status = 'failed';
$file_word->save();
$this->logger->error("Validação falhou: {$validation->errors}");
return preprocess_result::failed($validation->errors);
}
// Extrai unidades → JSON manifest
$units_manifest = $this->extract_units($word_content);
$manifest_storage_id = $this->file_storage->store(
json_encode($units_manifest),
"manifest_{$file_word_id}.json"
);
$file_word->set_meta('unit_manifest_storage_id', $manifest_storage_id);
// Gera Markdown de Tópicos
$markdown = $this->generate_topics_markdown($word_content, $units_manifest);
$markdown_hash = hash('sha256', $markdown);
$markdown_storage_id = $this->file_storage->store(
$markdown,
"markdown_{$file_word_id}.md"
);
$file_word->set_meta('markdown_storage_id', $markdown_storage_id);
$file_word->set_meta('markdown_hash', $markdown_hash);
$file_word->status = 'preprocessed';
$file_word->save();
$this->signal->emit('file_word_preprocessed', [
'file_word_id' => $file_word_id,
'discipline_id' => $file_word->parent_id,
'markdown_hash' => $markdown_hash,
'unit_count' => count($units_manifest->units),
]);
return preprocess_result::ok($units_manifest);
}Critérios de aceitação
- Word inválido → file_word.status = ‘failed’ com log detalhado
- JSON manifest salvo como file_storage (não meta column)
- Markdown de Tópicos salvo como file_storage com hash computado
- file_word.status transiciona para ‘preprocessed’
- Signal
file_word_preprocessedemitido com markdown_hash e unit_count - Notificação ao Gestor: “Pré-processamento concluído — N unidades encontradas”
Step 3: Processamento (ação do Gestor)
Fluxo
Gestor acessa discipline → lista file_word versions
├── Só o file_word mais recente pode ser processado (versões anteriores: desabilitado)
├── Tela mostra prévia: unidades do manifest + diff visual vs versão anterior
├── Gestor preenche motivação/contexto (opcionais, fallback automático)
└── Clica "Processar"
│
▼
publication_service.process(file_word_id, motivation?, context?)
├── Verifica lock por discipline (se locked → rejeita)
├── Verifica se é o file_word mais recente (se não → rejeita)
├── Verifica idempotência: se já processado (mesmo hash) → ignora
├── Lê JSON manifest do file_storage
├── Para cada unidade no manifest:
│ ├── unit = find_or_create(idnumber, discipline_id)
│ │ └── Se unit nova → cria curso-unidade Moodle (idnumber)
│ │ └── emit signal: unit_created(unit_id)
│ ├── Computa hashes por seção (info, topic, flashcard, video, audio, questions, relations)
│ ├── Compara com unit.current_content_hash
│ │ └── Se igual → skip (sem alteração real)
│ └── unit_content = create(unit_id, version: N+1, seções com hashes)
│ └── unit.current_content_hash = content_hash
│ └── unit.total_versions += 1
│ └── emit signal: unit_content_published(unit_content_id)
├── Unidades que existiam antes mas não estão no manifest:
│ ├── unit.status = 'archived'
│ ├── curso-unidade Moodle → hidden/blocked
│ └── emit signal: unit_archived(unit_id)
├── Se version > 1 (2º+ processamento):
│ └── content_revision_service.create_revision(file_word_id, motivation, context, changes[])
├── file_word.status = 'processed'
└── emit signal: file_word_processed(file_word_id)Signal: file_word_processed
payload: { file_word_id: int, discipline_id: int, units_created: int, units_updated: int, units_archived: int, revision_id: ?int }
listeners:
- notification_listener → notifica GestorSignal: unit_content_published
payload: { unit_content_id: int, unit_id: int, version: int, content_hash: string }
listeners:
- (consumido por outros domínios: engine, product)Pseudocódigo
// publication_service.php
public function process(int $file_word_id, ?string $motivation = null, ?string $context = null): process_result {
$file_word = $this->file_word_service->get($file_word_id);
$discipline = $this->discipline_service->get($file_word->parent_id);
// Guards
if ($this->is_locked($discipline->id)) {
throw new processing_locked_exception($discipline->id);
}
$latest = $this->file_word_service->get_latest($discipline->id);
if ($latest->id !== $file_word_id) {
throw new not_latest_version_exception($file_word_id, $latest->id);
}
if ($file_word->status === 'processed' && !$this->has_hash_changed($file_word)) {
return process_result::already_processed();
}
$this->acquire_lock($discipline->id);
try {
$manifest = $this->load_manifest($file_word);
$existing_units = $this->unit_service->get_by_discipline($discipline->id);
$changes = [];
foreach ($manifest->units as $unit_data) {
$unit = $this->find_or_create_unit($unit_data, $discipline);
$section_hashes = $this->compute_section_hashes($unit_data);
if ($unit->current_content_hash === $section_hashes->content_hash) {
continue; // sem alteração real
}
$unit_content = $this->unit_versioning_service->create_version(
unit: $unit,
data: $unit_data,
hashes: $section_hashes,
file_word_id: $file_word_id,
);
$changes[] = new unit_change(
unit_id: $unit->id,
unit_content_id: $unit_content->id,
previous_hash: $unit->current_content_hash,
new_hash: $section_hashes->content_hash,
changed_sections: $section_hashes->diff_sections,
);
$this->signal->emit('unit_content_published', [...]);
}
// Unidades que desapareceram
$manifest_idnumbers = array_column($manifest->units, 'idnumber');
foreach ($existing_units as $unit) {
if (!in_array($unit->idnumber, $manifest_idnumbers) && $unit->status !== 'archived') {
$unit->status = 'archived';
$unit->save();
$this->moodle_course_service->hide($unit->courseid);
$this->signal->emit('unit_archived', ['unit_id' => $unit->id]);
$changes[] = new unit_change(unit_id: $unit->id, archived: true);
}
}
// Content revision (2º+ processamento)
$revision_id = null;
if ($file_word->version > 1 && !empty($changes)) {
$revision_id = $this->content_revision_service->create_revision(
file_word_id: $file_word_id,
motivation: $motivation ?? "Reprocessamento de version {$file_word->version}",
context: $context,
changes: $changes,
);
}
$file_word->status = 'processed';
$file_word->save();
$this->signal->emit('file_word_processed', [...]);
return process_result::ok($changes, $revision_id);
} finally {
$this->release_lock($discipline->id);
}
}Critérios de aceitação
- Só o file_word mais recente pode ser processado (demais: rejeitado)
- Lock por discipline impede processamento concorrente
- Idempotência: se hash não mudou, retorna already_processed
- Unit criada com curso-unidade Moodle (idnumber sincronizado)
- Unit com hash igual ao anterior não gera novo unit_content
- Unit que desaparece → status ‘archived’ + curso-unidade bloqueado
- Unit que reaparece (era archived) → restaurada + novo unit_content SEMPRE
- Content revision criado automaticamente no 2º+ processamento (se houver changes)
- Motivação/contexto preenchidos pelo Gestor (opcionais, fallback automático)
- Prévia do processamento visível na tela (manifest + diff)
- Signals emitidos para cada etapa (unit_created, unit_content_published, unit_archived, file_word_processed)
- Notificação ao Gestor: “Processamento concluído — N unidades criadas, M atualizadas, K arquivadas”
Step 4: Geração de Flashcards (desacoplado)
Fluxo
Gestor aciona "Gerar Flashcards" (se markdown_hash diferente do último)
│ Consulta: SELECT meta_value FROM metadata WHERE meta_key = 'markdown_hash'
│ AND item_id = file_word_id
│ Compara com last_flashcard_markdown_hash
│ Se igual → botão desabilitado "Flashcards já atualizados"
│
▼
flashcard_generate_command.execute(discipline_id, file_word_id)
├── Cria flashcard_job(status: generating)
├── Lê Markdown do file_storage
├── Envia para API externa (Law School)
│ └── Se falha de rede → job.status = 'failed_retryable' (retry automático)
├── Aguarda resposta (async — job em fila)
└── Quando resposta chega:
├── flashcard_raw salvo no file_storage vinculado ao file_word
├── flashcard_job.status = 'generated'
├── flashcard_job.total_generated = N
└── emit signal: flashcard_job_generated(job_id, file_word_id)
Signal flashcard_job_generated → ad_hoc task para persistência
│
▼
flashcard_persist_command.execute(file_word_id)
├── Lê flashcard_raw do file_storage
├── Para cada flashcard_raw.item:
│ ├── Match topic_ref → unit_content.topic (por título)
│ │ └── Se não casar → marca como "não alocado"
│ └── Atualiza unit_content.flashcard + recomputa flashcard_hash
├── flashcard_job.status = 'completed'
├── flashcard_job.total_persisted = M
├── file_word.set_meta('last_flashcard_markdown_hash', markdown_hash)
└── emit signal: flashcard_job_persisted(job_id)Critérios de aceitação
- Botão “Gerar Flashcards” desabilitado se markdown_hash não mudou
- Geração assíncrona — Gestor não espera (job em fila)
- Falha de rede → retry automático (3x com backoff exponencial)
- Falha de API → job.status = ‘failed’, Gestor notificado
- flashcard_raw salvo como file_storage (não meta column)
- Distribuição automática por topic_ref
- Flashcards “não alocados” visíveis no dashboard do Gestor
- Hash do Markdown registrado para evitar geração redundante
- Notificação ao Gestor: “Flashcards gerados — N items, M alocados, K pendentes”
Step 5: Content Revision (automático no 2º+ processamento)
Fluxo
publication_service.process() detecta version > 1 com changes
│
▼
content_revision_service.create_revision(file_word_id, motivation, context, changes[])
├── content_revision = create(status: 'open', file_word_id, motivation, context)
├── Para cada unit_change com hash diferente:
│ ├── content_change = create(revision_id, unit_id, diff por seção)
│ └── conflict_detection_service.detect(content_change)
│ ├── Busca Trilhas que referenciam esta unit
│ │ └── Para cada Trilha: verifica se item removido/modificado era obrigatório
│ │ └── Se sim → content_conflict(type: trail, ...)
│ ├── Busca Planos do Aluno ativos que usam esta unit
│ │ └── Para cada Plano: verifica se item específico selecionado não existe mais
│ │ └── Se sim → content_conflict(type: plan, ...)
│ └── Identifica topics alterados (para notificação futura)
├── emit signal: content_revision_opened(revision_id)
└── Se há conflitos → emit signal: content_conflict_detected(conflict_ids[])Detalhes do algoritmo de detecção de conflitos em REF-30-B.
Critérios de aceitação
- Content revision criado com status ‘open’
- Content change criado apenas para units com hash realmente diferente
- Diff registrado por seção (quais seções mudaram)
- Conflitos com Trilha detectados (item obrigatório removido/modificado)
- Conflitos com Plano detectados (item específico selecionado que não existe mais)
- Alterações de tópico registradas para possível notificação
- Signals emitidos para revision e conflitos
- Gestor pode completar motivação/contexto depois (campos editáveis)
Mapa de Signals
| 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 |
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) |
Job Status Transitions
sync_job
pending → running → completed
→ failed (retryable: rede)
→ failed (Gestor: credenciais SharePoint)process_job (pré-processamento)
pending → running → completed (preprocessed)
→ failed (Word inválido — Gestor corrige)flashcard_job
pending → generating → generated → persisting → completed
→ failed_retryable (rede/API — retry auto)
→ failed (Gestor: API indisponível)Notas de implementação
- Moodle ad_hoc tasks: usar
\core\task\adhoc_taskcomset_custom_data()para payload - Locks: usar
\core\lock\lock_factorydo Moodle (table-based lock) - file_storage: usar
\stored_filevia file API do Moodle (component:local_helico, filearea:content) - Signals: usar pattern outbox (ADR-707) — signal salvo em tabela, dispatcher processa async
- Notificações: registrar providers em
db/messages.phpdo plugin