Skip to content

REF-30-A: Pipeline de Processamento de Conteúdo

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_send do 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é-processamento

Pseudocó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_created emitido 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_preprocessed emitido 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 Gestor

Signal: 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

  1. Moodle ad_hoc tasks: usar \core\task\adhoc_task com set_custom_data() para payload
  2. Locks: usar \core\lock\lock_factory do Moodle (table-based lock)
  3. file_storage: usar \stored_file via file API do Moodle (component: local_helico, filearea: content)
  4. Signals: usar pattern outbox (ADR-707) — signal salvo em tabela, dispatcher processa async
  5. Notificações: registrar providers em db/messages.php do plugin
Navigation

Type to search…

↑↓ navigate↵ selectEsc close