Skip to content

Domínio content.change — Plano de Implementação

Domínio content.change — Plano de Implementação

Goal: Materializar o domínio content.change (Wave 1 + Wave 2 do ADR-30) sem refatorar o pipeline existente. Após a entrega, todo reprocessamento de Arquivo de Disciplina (Word) gera uma revision (aggregate root), com um content_change por unidade alterada (com diffs por seção) e os content_conflict detectados conforme REF-30-B. O unit_create_service continua estático e cumpre seu papel de Step 3 do pipeline.

Architecture: O unit_create_service::execute (Step 3) deixa de ser void e passa a devolver array $changes. O caller do Step 3 (publication / comando agendado) consome esse array e dispara o Step 5 chamando revision_service::create_revision(...), que cria o aggregate revision, materializa N content_change (um por unidade alterada) com diffs por seção comparando unit_content versão anterior vs nova, e dispara conflict_detection_service para gerar M content_conflict. Eventos canônicos: revision_opened, content_conflict_detected, content_conflict_resolved, revision_resolved.

Tech Stack: PHP 8.3 (Moodle 4.x), local_middag framework (estilo Symfony-like dentro do Moodle), local_middag\base\domain\item (EAV), #[item_type(...)] attribute, #[async_on(...)] para signals. Outbox pattern via local_middag/classes/framework/infrastructure/bus/ (outbox_store, signal_dispatcher, outbox_worker_command). LinkML em .vigim/ddd/linkml/ é detalhamento da implementação. Code-gen via composer build:extensions (php ../middag/cli/build.php --extensions build).

Reference docs:

  • .vigim/ddd/terms/terms-content.yaml — fonte canônica (verdade)
  • .vigim/ddd/linkml/entities/{revision,content_change,content_conflict,conflict_resolution,report_change}.linkml.yaml — campos da implementação
  • .vigim/ddd/linkml/core.linkml.yaml — enums compartilhados
  • docs/plataforma/adrs/adr-30_dominio-content-arquitetura-e-materializacao.md
  • docs/plataforma/adrs/ref-30-a_pipeline-de-processamento-de-conteudo.md
  • docs/plataforma/adrs/ref-30-b_algoritmo-de-deteccao-de-conflitos.md
  • docs/plataforma/adrs/ref/ref-30-c_content-subdomain-map.md
  • docs/metodologia/importacao-word/ciclo-de-alteracoes-do-word.md

Premissas vinculantes (decisões fechadas)

ID Decisão Origem
P-1 terms-content.yaml é verdade absoluta. Identifiers no terms NÃO são corrigidos por este plano. Código e ADRs alinham-se ao terms. Diretriz do Gestor (2026-04-30)
P-2 Identifier canônico do aggregate root é revision (terms-content.yaml:436), NÃO content_revision. ADR-30 e refs estão desalinhados — fica como pendência editorial fora deste plano. P-1
P-3 Identifier de “Resolução de Conflito Pedagógico” é conflict_resolution (terms-content.yaml:502), NÃO content_conflict_resolution. P-1
P-4 unit_create_service permanece estático. Sem refatoração para classe instanciável. Única mudança permitida: assinatura passa a retornar array $changes. A-03
P-5 content_change é granular por unidade, com diff_* (info, topic, flashcard, video, audio, question_*, relations) como propriedades JSON. Não é um content_change por seção. A-04:B + LinkML content_change.linkml.yaml:96-165
P-6 Renomeação change/record/ → change/content_change/ é obrigatória — terms tem identifier content_change para o termo, código tem change_record. A-02 (priorize terms)
P-7 Caso de uso pedagógico é o ciclo-de-alteracoes-do-word.md (em construção). Caso de uso técnico é ADR-30 + REF-30-A + REF-30-B (completo). Este plano executa o técnico. Confrontação 2026-04-30
P-8 LinkML em .vigim/ddd/linkml/ é detalhamento autoritativo da implementação, gerado a partir de terms. Está alinhado a P-1: revision.linkml.yaml usa slug revision, content_change.linkml.yaml usa content_change, content_conflict.linkml.yaml usa content_conflict. Campos PHP saem do LinkML, NÃO do ADR-30 (que tem nomes desalinhados como user_id vs responsible_id). Verificações 2026-04-30
P-9 Código PHP de itens EAV (#[item_type(...)] classes) é gerado pelo pipeline composer build:extensions (php ../middag/cli/build.php --extensions build). Arquivos têm BEGIN AUTO-GENERATED / END AUTO-GENERATED markers. Seções MANUAL (entre BEGIN MANUAL e END MANUAL) preservam código autoral. Não escrever item EAV manualmente — rodar pipeline. Verificações 2026-04-30

Fluxo alvo — Step 3 → Step 5

                                                     ┌──────────────────────────────┐
                                                     │   GESTOR PEDAGÓGICO          │
                                                     │   preenche motivation,       │
                                                     │   context, impact            │
                                                     └────────────┬─────────────────┘
                                                                  │
                                                                  ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  STEP 3 — Processamento (publication ou comando agendado dispara unit_create_service)│
│                                                                                      │
│   unit_create_service::execute(discipline) : array                                   │
│     foreach unidade in file_word JSON:                                               │
│       persist(discipline, hour_label, unidade, file_word)                            │
│         ├── get_or_create_unit (compara hash agregado)                               │
│         │     └── hash igual: pula. NÃO é mudança.                                   │
│         │     └── hash diff: capture old_content (versão N-1)                        │
│         ├── create_unidade_content (cria unit_content versão N)                      │
│         │     └── capture new_content                                                │
│         └── push em changes[]:                                                       │
│              { unit_id, from_version: N-1, to_version: N, old_content, new_content } │
│                                                                                      │
│   return ['changes' => changes[]];                                                   │
└────────────┬─────────────────────────────────────────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────────────────────────────────────────┐
│  STEP 5 — Content Revision (caller chama, somente se changes[] não vazio)            │
│                                                                                      │
│   revision_service::create_revision(                                                 │
│     file_word_id, discipline_id,                                                     │
│     motivation, context, impact, responsible_id,                                     │
│     changes[]                                                                        │
│   ) : revision                                                                       │
│                                                                                      │
│     1. Cria revision (status: open)                                                  │
│     2. foreach change in changes[]:                                                  │
│          ├── calcula diff_info, diff_topic, diff_flashcard, diff_video,              │
│          │   diff_audio, diff_question_truefalse, diff_question_multichoice,         │
│          │   diff_question_essay, diff_relations                                     │
│          │   (compara hashes granulares de old_content × new_content)                │
│          ├── cria content_change (parent: revision, entity_type: unit,               │
│          │                       entity_id: unit_id, from_version, to_version,       │
│          │                       diff_*, diff_hash)                                  │
│          └── conflict_detection_service::detect(content_change)                      │
│                ├── busca trails que referenciam unit + sem snapshot                  │
│                │   └── content_conflict (type: trail)                                │
│                ├── busca student plans ativos com item específico                    │
│                │   └── content_conflict (type: plan)                                 │
│                └── identifica topics alterados (notification futura)                 │
│     3. revision.severity = max(content_conflicts.severity)                           │
│        revision.total_units_changed = count(content_changes)                         │
│        revision.total_conflicts = count(content_conflicts)                           │
│     4. emit revision_opened(revision_id)                                             │
│     5. se há conflitos: emit content_conflict_detected(conflict_ids[])               │
└──────────────────────────────────────────────────────────────────────────────────────┘

Phase 0 — Prep (✅ CONCLUÍDA — resultados consolidados)

Task 0.1: Verificar disponibilidade do ADR-707 (outbox pattern) ✅

Resultado: Outbox EXISTE e está implementado em local_middag/classes/framework/infrastructure/bus/:

  • outbox_store.php, outbox_worker_command{,_handler}.php, outbox_purge_command{,_handler}.php
  • signal_dispatcher.php, async_signal_interface.php, async_consumer_registry.php, queue_worker.php
  • Tasks Moodle: task/outbox_worker_task.php, task/async_delivery_task.php
  • Testes: tests/framework/infrastructure/bus/*_test.php

Phase 5 usa signal_dispatcher via facade pública (memória do projeto: nunca importar @internal direto — buscar middag::* ou base\ui\*).

Task 0.2: Snapshot do estado atual em git ✅

Resultado: branch feature/new-contracts, HEAD 701ad0e, working tree limpa exceto inventory.csv (M) e o próprio PLAN.md (?). Não vou criar branch dedicada — continuo nesta. Inventário de change/:

change/conflict_created.php
change/content_revision_created.php
change/record/{change_record,change_record_dto,change_record_interface,change_record_repository_interface,change_record_service,change_record_service_interface}.php
change/record/{conflict_resolution_command,conflict_resolution_command_handler,conflict_resolution_type}.php
change/report_change/{report_change,report_change_dto,report_change_service,report_change_service_interface}.php

Task 0.3: Confirmar consumidores externos de change_record_* ✅

Resultado: zero consumidores externos. Busca ampla em local/ retorna apenas o próprio diretório change/record/ + ADRs como menção textual. Renomeação é segura.

Task 0.4: Mapear LinkML e estado dos artefatos gerados ✅

Resultado:

Artefato Estado
revision.linkml.yaml ✅ alinhado ao terms (slug revision); 11 attributes incl. resolved_by, resolved_at
content_change.linkml.yaml ✅ alinhado (slug content_change); 17 attributes incl. todos diff_* + entity_type/entity_id/from_version/to_version/snapshot_id/diff_hash
content_conflict.linkml.yaml ✅ alinhado (slug content_conflict); 13 attributes (campos do REF-30-B)
conflict_resolution.linkml.yaml ✅ alinhado (slug conflict_resolution); sem attributes (process_command)
report_change.linkml.yaml ✅ alinhado
Enums em core.linkml.yaml severity, change_record_status ⚠️ (nome velho), conflict_type, conflict_status, conflict_reason, conflict_resolution_type, content_section, change_entity_type
change/record/change_record.php ❌ obsoleto — gerado de versão antiga do LinkML; ainda tem motivation/context/impact/responsible_id que migraram pro revision
json-schema/contract/content_revision/ ❌ pasta com nome desalinhado (deveria ser revision/); campo user_id no schema vs responsible_id no LinkML

Phase 0.5 — Build check (BLOQUEADO por ambiente)

Antes de qualquer mutação, rodar pipeline em modo check para validar terms ↔ LinkML ↔ código. Bloqueio atual: php local não carrega — Library not loaded: libicuio.74.dylib. Homebrew com icu4c em versão diferente da esperada por PHP 8.3.6. Sem isso, composer build:* não roda.

Task 0.5.1: Resolver ambiente PHP

Files: N/A (ambiente local)

  • Step 1: consertar PHP CLI. Opções:
    • brew reinstall icu4c (reinstalar versão atual)
    • brew install icu4c@74 + relink
    • brew upgrade php (PHP nova versão pode resolver)
    • Container Docker com PHP 8.3 + icu4c 74
  • Step 2: validar com php -v + php -m | grep -i intl.

Task 0.5.2: Rodar checks não destrutivos

  • Step 1: composer check:docs — terms + specs check.
  • Step 2: composer build:extensions:check — confirmar quais arquivos PHP estão fora-de-sync com LinkML.
  • Step 3: capturar saída em /tmp/build-check-2026-04-30.txt para comparação após cada Phase.

Task 0.5.3: Decidir ordem de execução final

  • Step 1: com base no relatório do build:check, confirmar se Phase 1 (renomear) precede ou segue Phase 1.5 (rodar build:extensions). Provável: rodar composer build:extensions PRIMEIRO — pipeline regenera change_record.php como content_change.php (no caminho que o LinkML implica) automaticamente. Validar com a saída do check.

Phase 1 — Sincronizar change/record/ → change/content_change/ via pipeline (P-6 + P-9)

Mudança vs versão original do plano: ao invés de git mv manual + edição de namespace, usar o pipeline de geração. O LinkML (content_change.linkml.yaml) já tem o nome correto. composer build:extensions deve regenerar o item no caminho change/content_change/content_change.php (ou similar). Trabalho manual: confirmar o que o pipeline gera, complementar com DTO/service/interface se não forem gerados, e remover restos do velho change/record/.

Task 1.1: Rodar pipeline de geração

  • Step 1: composer build:extensions (após Task 0.5.1 desbloquear).
  • Step 2: verificar arquivos modificados:
git status -- classes/extensions/content/change/
  • Step 3: identificar 3 cenários:
Cenário Ação
Pipeline cria change/content_change/content_change.php automaticamente Pular para Task 1.3
Pipeline atualiza change/record/change_record.php mas não move Manualmente git mv o arquivo + atualizar namespace; rodar composer build:extensions:check para validar
Pipeline reporta erro ou conflito Investigar; reportar achado antes de prosseguir

Task 1.2: Mover artefatos não gerados pelo pipeline

Pipeline provavelmente gera apenas o item EAV (a classe com #[item_type]). DTO, interface, repository_interface, service, service_interface são autorais. Se ainda estão em change/record/:

  • Step 1:
cd /private/var/www/helico.localhost/moodle/local/helico
git mv classes/extensions/content/change/record/change_record_dto.php classes/extensions/content/change/content_change/content_change_dto.php
git mv classes/extensions/content/change/record/change_record_interface.php classes/extensions/content/change/content_change/content_change_interface.php
git mv classes/extensions/content/change/record/change_record_repository_interface.php classes/extensions/content/change/content_change/content_change_repository_interface.php
git mv classes/extensions/content/change/record/change_record_service.php classes/extensions/content/change/content_change/content_change_service.php
git mv classes/extensions/content/change/record/change_record_service_interface.php classes/extensions/content/change/content_change/content_change_service_interface.php
  • Step 2: atualizar nome de classe e namespace dentro de cada arquivo:

    • namespace local_helico\extensions\content\change\record → local_helico\extensions\content\change\content_change
    • classe change_record_dto → content_change_dto, change_record_service → content_change_service, etc.
    • referências internas a change_record::TYPE → content_change::TYPE
  • Step 3: atualizar content_change_service.php para setar $dto->type = content_change::TYPE no override de create() / update().

Nota crítica: o método on_file_synced atual (change_record_service.php:61-65) tem TODO BL-001 não implementado. Mover o #[async_on(file_word_synced)] para o revision_service (Phase 5) — content_change é entidade-filho, não tem agência sobre o aggregate.

Task 1.3: Mover conflict_resolution_* para futura change/content_conflict/

Identifier canônico do comando é conflict_resolution (terms:502, P-3). Nome dos arquivos não muda — só a pasta.

  • Step 1:
mkdir -p classes/extensions/content/change/content_conflict
git mv classes/extensions/content/change/record/conflict_resolution_command.php classes/extensions/content/change/content_conflict/
git mv classes/extensions/content/change/record/conflict_resolution_command_handler.php classes/extensions/content/change/content_conflict/
git mv classes/extensions/content/change/record/conflict_resolution_type.php classes/extensions/content/change/content_conflict/
  • Step 2: atualizar namespace dos 3 arquivos: change\record → change\content_conflict.

Task 1.4: Remover diretório change/record/ vazio

  • Step 1: rmdir classes/extensions/content/change/record (falha se não vazio — investigar).

Task 1.5: Atualizar content_extension.php e DI bindings

Files:

  • classes/extensions/content/content_extension.php

  • classes/extensions/content/content_hooks.php

  • Step 1: localizar bindings antigos:

grep -n "change_record\|change\\\\record" classes/extensions/content/content_extension.php classes/extensions/content/content_hooks.php
  • Step 2: substituir por content_change / content_conflict.

Task 1.6: Validar

  • Step 1: zero referências legadas:
grep -rn "change_record\b\|change\\\\record\b" classes/ db/ lang/
# expected: 0
  • Step 2: composer build:extensions:check — pipeline deve reportar tudo OK.

  • Step 3: composer fix:all (se existir) para PSR-12.

Task 1.7: Commit

  • Step 1:
git add -A classes/extensions/content/ .vigim/
git commit -m "refactor(content): align change/record/ to terms identifier content_change

- pipeline-driven rename via composer build:extensions
- moved authored artefacts (dto, services, interfaces, repository_interface)
- conflict_resolution_* moved to change/content_conflict/
- record/ directory removed
- no behavior change"

Phase 2 — Criar change/revision/ (Wave 1) — pipeline-first

Identifier canônico: revision (terms:436, P-2). LinkML detalhado em revision.linkml.yaml.

Task 2.1: Gerar revision.php via pipeline

  • Step 1: confirmar que revision.linkml.yaml está ativo no manifesto do pipeline (.vigim/ddd/linkml/...).

  • Step 2: composer build:extensions — deve criar classes/extensions/content/change/revision/revision.php com:

    • #[item_type('revision')]
    • METADATA_FIELDS = ['file_word_id', 'status', 'motivation', 'context', 'impact', 'responsible_id', 'severity', 'total_units_changed', 'total_conflicts', 'resolved_by', 'resolved_at'] (do LinkML)
    • getters tipados auto-gerados
  • Step 3: validar com cat classes/extensions/content/change/revision/revision.php.

Task 2.2: Criar revision_dto.php (autoral)

Files: classes/extensions/content/change/revision/revision_dto.php (NOVO)

  • Step 1: padrão idêntico ao unit_content_dto. Factory to_item_dto(file_word_id, parent_id, status, motivation, context, impact, responsible_id, total_units_changed, total_conflicts, severity) retornando item_dto. Factory from_item(revision $r): array para serialização.

Task 2.3: Criar revision_interface.php e revision_repository_interface.php

Files:

  • classes/extensions/content/change/revision/revision_interface.php (NOVO)

  • classes/extensions/content/change/revision/revision_repository_interface.php (NOVO)

  • Step 1: revision_interface declara getters tipados (mesma assinatura dos getters auto-gerados, mas como contrato).

  • Step 2: revision_repository_interface declara find_open_by_discipline(int): ?revision, find_by_file_word(int): ?revision, find_with_open_changes(int $discipline_id): array.

Task 2.4: Criar revision_service_interface.php e revision_service.php (esqueleto)

Files:

  • classes/extensions/content/change/revision/revision_service_interface.php (NOVO)

  • classes/extensions/content/change/revision/revision_service.php (NOVO)

  • Step 1: interface declara create_revision(int $file_word_id, int $discipline_id, ?string $motivation, ?string $context, ?string $impact, int $responsible_id, array $changes): revision, mark_resolved(int $revision_id): void, recompute_severity(int $revision_id): void.

  • Step 2: service estende item_service, override create/update setando $dto->type = revision::TYPE. create_revision/mark_resolved/recompute_severity lançam coding_exception neste momento (implementação na Phase 5).

Task 2.5: Registrar bindings

Files: classes/extensions/content/content_extension.php

  • Step 1: vincular revision_service_interface → revision_service no DI.

Task 2.6: Commit

  • Step 1:
git add -A classes/extensions/content/change/revision/ classes/extensions/content/content_extension.php
git commit -m "feat(content): add change/revision/ aggregate root (Wave 1)

- revision item generated from LinkML via build:extensions
- revision_service stub (create_revision deferred to Phase 5)
- aligned to terms.yaml slug 'revision'"

Phase 3 — Criar change/content_conflict/ (Wave 1) — pipeline-first

Identifier canônico: content_conflict (terms:479). LinkML detalhado em content_conflict.linkml.yaml.

Task 3.1: Gerar content_conflict.php via pipeline

  • Step 1: composer build:extensions (já rodado na Phase 1; rodar novamente se necessário).

  • Step 2: validar que classes/extensions/content/change/content_conflict/content_conflict.php foi criado com:

    • #[item_type('content_conflict')]
    • METADATA_FIELDS = ['conflict_type', 'status', 'section', 'reference_id', 'reference_hash', 'reason', 'severity', 'target_type', 'target_id', 'target_context', 'resolution_type', 'resolution_note', 'resolved_by', 'resolved_at'] (do LinkML)
    • getters auto-gerados

Task 3.2: Criar content_conflict_dto.php (autoral)

Files: classes/extensions/content/change/content_conflict/content_conflict_dto.php (NOVO)

  • Step 1: factory to_item_dto(content_change_id, conflict_type, section, reference_id, reference_hash, reason, severity, target_type, target_id, target_context).

Task 3.3: Criar content_conflict_service_interface.php e service stub

Files:

  • classes/extensions/content/change/content_conflict/content_conflict_service_interface.php (NOVO)

  • classes/extensions/content/change/content_conflict/content_conflict_service.php (NOVO)

  • Step 1: interface declara create(item_dto_interface): content_conflict, count_open(int $content_change_id): int, mark_resolved(int $conflict_id, string $resolution_type, int $resolved_by, ?string $note): void, mark_dismissed(int $conflict_id, int $resolved_by, ?string $note): void.

  • Step 2: service estende item_service, override create/update setando type. Demais métodos lançam coding_exception (Phase 6).

Task 3.4: Wire conflict_resolution_command_handler ao content_conflict_service

Files: classes/extensions/content/change/content_conflict/conflict_resolution_command_handler.php

  • Step 1: trocar dependência stub por content_conflict_service_interface. Implementação concreta entra na Phase 6.

Task 3.5: Registrar bindings

Files: classes/extensions/content/content_extension.php

  • Step 1: content_conflict_service_interface → content_conflict_service.

Task 3.6: Commit

  • Step 1:
git add -A classes/extensions/content/change/content_conflict/ classes/extensions/content/content_extension.php
git commit -m "feat(content): add change/content_conflict/ entity (Wave 1)

- content_conflict item generated from LinkML
- content_conflict_service stub (detection logic in Phase 6)
- conflict_resolution_command_handler wired to the new service"

Phase 4 — Renomear / criar eventos (signals)

ADR-30:457-458 + REF-30-A:447-461 definem o léxico de signals. Ajustando para revision (P-2). Eventos não são gerados pelo pipeline LinkML — são autorais.

Signal canônico Arquivo alvo Origem
revision_opened change/revision_opened.php renomear de change/content_revision_created.php
revision_resolved change/revision_resolved.php NOVO
content_conflict_detected change/content_conflict_detected.php renomear de change/conflict_created.php
content_conflict_resolved change/content_conflict_resolved.php NOVO

Task 4.1: Renomear content_revision_created.php → revision_opened.php

  • Step 1:
git mv classes/extensions/content/change/content_revision_created.php classes/extensions/content/change/revision_opened.php
  • Step 2: ajustar nome da classe e namespace dentro do arquivo. Payload: { revision_id, file_word_id, discipline_id }.

  • Step 3: grep -rn "content_revision_created" classes/ — deve ficar zero.

Task 4.2: Renomear conflict_created.php → content_conflict_detected.php

  • Step 1:
git mv classes/extensions/content/change/conflict_created.php classes/extensions/content/change/content_conflict_detected.php
  • Step 2: ajustar classe. Payload: { conflict_ids: int[], revision_id }.

  • Step 3: grep -rn "conflict_created" classes/ — zero.

Task 4.3: Criar revision_resolved.php

Files: classes/extensions/content/change/revision_resolved.php (NOVO)

  • Step 1: event class com payload { revision_id, discipline_id }.

Task 4.4: Criar content_conflict_resolved.php

Files: classes/extensions/content/change/content_conflict_resolved.php (NOVO)

  • Step 1: payload { conflict_id, resolution_type, content_change_id, revision_id }.

Task 4.5: Commit

  • Step 1:
git add -A classes/extensions/content/change/
git commit -m "refactor(content): rename signals to terms-aligned names

- content_revision_created → revision_opened
- conflict_created → content_conflict_detected
- add revision_resolved and content_conflict_resolved"

Phase 4.5 — Regenerar JSON-schemas em json-schema/contract/

A pasta atual json-schema/contract/content_revision/ tem nome fora do LinkML (revision) e campos desatualizados (user_id vs responsible_id). Faltam content_change/ e content_conflict/.

Task 4.5.1: Rodar composer build:docs:specs

  • Step 1: composer build:docs:specs — regenera schemas a partir do LinkML atual.

  • Step 2: verificar resultado:

ls -la .vigim/ddd/json-schema/contract/
git status -- .vigim/ddd/json-schema/
  • Step 3: três cenários:
Cenário Ação
Pipeline cria revision/, content_change/, content_conflict/ automaticamente e mantém content_revision/ órfão git rm -r .vigim/ddd/json-schema/contract/content_revision/
Pipeline atualiza content_revision/ no lugar (não respeitando slug) Abrir issue no MIDDAG CLI; renomear manual e flagar bug
Pipeline não toca em json-schema/contract/ Confirmar se há outro composer script (build:json-schema ou similar); investigar

Task 4.5.2: Validar contra unit_content/ (referência de convenção)

  • Step 1: comparar estrutura de revision/ com unit_content/:
    • 4 arquivos: <slug>.api.schema.json, <slug>.api.example.json, <slug>.persistence.schema.json, <slug>.persistence.example.json
    • Pasta children/ com schemas dos filhos referenciados

Task 4.5.3: Commit

  • Step 1:
git add -A .vigim/ddd/json-schema/
git commit -m "build(contracts): regenerate json-schema from LinkML for content.change

- json-schema/contract/revision/ replaces content_revision/ (slug aligned to terms)
- json-schema/contract/content_change/ and content_conflict/ created
- field user_id removed in favor of responsible_id (LinkML truth)"

Phase 5 — Implementar revision_service::create_revision (Wave 2)

Implementa o pseudocódigo do REF-30-A:416-430 com substituição content_revision_service → revision_service (P-2).

Task 5.1: Ler dependências do método

  • Step 1: confirmar unit_content_service::get_current_unit_content($unit) e get_next_version($unit) continuam sendo a fonte de versão.
  • Step 2: mapear como obter $old_content (versão N-1) — em geral a versão atual ANTES de criar a nova. Deve ser capturada pelo unit_create_service na Phase 7, não buscada aqui.

Task 5.2: Implementar create_revision

Files: classes/extensions/content/change/revision/revision_service.php

public function create_revision(
    int $file_word_id,
    int $discipline_id,
    ?string $motivation,
    ?string $context,
    ?string $impact,
    int $responsible_id,
    array $changes,
): revision {
    global $DB;

    $transaction = $DB->start_delegated_transaction();

    try {
        $revision_dto = revision_dto::to_item_dto(
            file_word_id: $file_word_id,
            parent_id: $discipline_id,
            status: 'open',
            motivation: $motivation,
            context: $context,
            impact: $impact,
            responsible_id: $responsible_id,
            total_units_changed: count($changes),
            total_conflicts: 0,
            severity: null,
        );

        $revision = $this->create($revision_dto);

        $total_conflicts = 0;
        $max_severity = null;
        $conflict_ids = [];

        foreach ($changes as $change) {
            $diff = $this->compute_diff($change['old_content'], $change['new_content']);

            $content_change_dto = content_change_dto::to_item_dto(
                parent_id: (int) $revision->get_id(),
                entity_type: 'unit',
                entity_id: $change['unit_id'],
                from_version: $change['from_version'],
                to_version: $change['to_version'],
                diff_info: $diff['info'] ?? null,
                diff_topic: $diff['topic'] ?? null,
                // ... demais diff_*
                diff_hash: $diff['hash'],
            );

            $content_change = middag::get(content_change_service_interface::class)->create($content_change_dto);

            $conflicts = middag::get(conflict_detection_service_interface::class)->detect($content_change);

            $total_conflicts += count($conflicts);
            foreach ($conflicts as $conflict) {
                $max_severity = $this->max_severity($max_severity, $conflict->get_severity());
                $conflict_ids[] = (int) $conflict->get_id();
            }
        }

        $this->update_metadata($revision, [
            'total_conflicts' => $total_conflicts,
            'severity' => $max_severity,
        ]);

        $transaction->allow_commit();

        $this->signal->emit(new revision_opened(
            revision_id: (int) $revision->get_id(),
            file_word_id: $file_word_id,
            discipline_id: $discipline_id,
        ));

        if ($total_conflicts > 0) {
            $this->signal->emit(new content_conflict_detected(
                conflict_ids: $conflict_ids,
                revision_id: (int) $revision->get_id(),
            ));
        }

        return $revision;
    } catch (Throwable $t) {
        $transaction->rollback($t);
        throw $t;
    }
}
  • Step 1: implementar com transação Moodle ($DB->start_delegated_transaction()).
  • Step 2: implementar helper compute_diff(unit_content $old, unit_content $new): array comparando hashes granulares (info_hash, topic_hash, flashcard_hash, video_hash, audio_hash, question_truefalse_hash, question_multichoice_hash, question_essay_hash, relations_hash). Quando hash difere, popula o JSON correspondente em diff_*.
  • Step 3: implementar helper max_severity(?string $current, ?string $candidate): ?string com ordem low < medium < high < critical.

Task 5.3: Implementar mark_resolved e recompute_severity

  • Step 1: mark_resolved(int $revision_id) valida que todos os content_change filhos estão resolvidos antes de marcar revision como resolved. Emite revision_resolved.
  • Step 2: recompute_severity(int $revision_id) recalcula severity e total_conflicts lendo do estado atual dos filhos.

Task 5.4: #[async_on(file_word_synced)] no revision_service

Files:

  • classes/extensions/content/change/content_change/content_change_service.php
  • classes/extensions/content/change/revision/revision_service.php

Por quê: quem reage ao file_word_synced para criar a revision é o revision_service. O content_change é entidade-filho; não tem agência sobre o aggregate.

  • Step 1: remover hook on_file_synced do content_change_service (caso pipeline tenha regenerado o stub).
  • Step 2: adicionar #[async_on(signal: file_word_synced::class, priority: 20)] em método on_file_synced do revision_service. Encadeamento: file_word_synced → unit_create_service (já roda) → revision_service.create_revision (chamado pelo caller que orquestra). Detalhar costura final na Phase 7.

Task 5.5: Commit

  • Step 1:
git add -A classes/extensions/content/change/
git commit -m "feat(content): implement revision_service.create_revision (Wave 2)

- creates revision aggregate inside Moodle transaction
- materializes content_change per unit using granular section hashes from unit_content
- delegates conflict detection to conflict_detection_service (Phase 6)
- emits revision_opened and content_conflict_detected signals via signal_dispatcher"

Phase 6 — Implementar conflict_detection_service (REF-30-B)

Task 6.1: Criar interface e service

Files:

  • classes/extensions/content/change/content_conflict/conflict_detection_service_interface.php (NOVO)

  • classes/extensions/content/change/content_conflict/conflict_detection_service.php (NOVO)

  • Step 1: declarar detect(content_change $change): array retornando content_conflict[].

  • Step 2: estrutura do service (sem lógica ainda).

Task 6.2: Implementar regras de conflito com Trilha

REF-30-B:60-100.

  • Step 1: identificar dependência: como buscar trail que referencia uma unit? Confirmar com vocabulário product.trail entregue em 2026-04-30. Provável trail_service::find_by_unit_id($unit_id).
  • Step 2: implementar laço sobre trails ativas + verificar se item removido era obrigatório.
  • Step 3: persistir content_conflict(type: trail, severity: ...).

Task 6.3: Implementar regras de conflito com Plano do Aluno

REF-30-B:101-150.

  • Step 1: identificar dependência: student_plan_service::find_active_by_unit_id ou similar.
  • Step 2: verificar se há unit_snapshot ativo para o plano + unit. Se sim, aluno está protegido — não gera conflito.
  • Step 3: implementar laço sobre planos sem snapshot, gerar content_conflict(type: plan).

Task 6.4: Cascata de status

REF-30-B:235-265.

  • Step 1: ao resolver/dismiss um content_conflict, verificar se todos os filhos do content_change estão resolvidos → marca content_change resolvido.
  • Step 2: ao resolver content_change, verificar se todos os filhos da revision estão resolvidos → marca revision resolvida.
  • Step 3: emitir revision_resolved quando aplicável.

Task 6.5: Implementar conflict_resolution_command_handler

Files: classes/extensions/content/change/content_conflict/conflict_resolution_command_handler.php

  • Step 1: substituir TODO atual pela lógica:
    1. Carrega content_conflict.
    2. Aplica resolution_type (content_restored / trail_adapted / plan_adapted / dismissed).
    3. Marca como resolvido com resolved_by, resolved_at, resolution_note.
    4. Emite content_conflict_resolved.
    5. Dispara cascata via conflict_detection_service::cascade_resolve(...).

Task 6.6: Commit

  • Step 1:
git add -A classes/extensions/content/change/content_conflict/
git commit -m "feat(content): implement conflict_detection_service per REF-30-B

- trail and plan conflict rules
- snapshot-aware student protection check
- cascade resolution: conflict → content_change → revision
- conflict_resolution_command_handler wired"

Phase 7 — Costurar unit_create_service ao pipeline

P-4: estático mantido, apenas troca de assinatura.

Task 7.1: Mudar assinatura de execute()

Files: classes/extensions/content/base/unit/unit_create_service.php

  • Step 1: linha 46 — trocar public static function execute(...): void para public static function execute(...): array.

  • Step 2: linha 78 — em vez de retornar void, retornar ['changes' => $changes] onde $changes é o array acumulado dentro do loop.

Task 7.2: Capturar old_content antes da nova versão

Files: mesmo

  • Step 1: em persist() (linha 141), antes de create_unidade_content (linha 162):
$service = middag::get(unit_content_service_interface::class);
$old_content = $service->get_current_unit_content($unit);
$from_version = $old_content instanceof unit_content ? (int) $old_content->get_meta('version') : 0;
  • Step 2: após create_unidade_content:
$new_content = $service->get_current_unit_content($unit);
$to_version = (int) $new_content->get_meta('version');
  • Step 3: acumular no array de saída:
return [
    'unit' => $unit,
    'change' => $old_content instanceof unit_content
        ? [
            'unit_id' => (int) $unit->get_id(),
            'from_version' => $from_version,
            'to_version' => $to_version,
            'old_content' => $old_content,
            'new_content' => $new_content,
        ]
        : null,
];

Task 7.3: Acumular changes no loop de execute()

  • Step 1: linhas 51-57 — converter o foreach para coletar $result['change'] em $changes[]. Retornar ['changes' => $changes].

Task 7.4: Identificar caller(s) de unit_create_service::execute

  • Step 1:
grep -rn "unit_create_service::execute\|unit_create_service\\\\execute" /private/var/www/helico.localhost/moodle/local/helico
  • Step 2: para cada caller:
    • Capturar $result = unit_create_service::execute($discipline);
    • Se $result['changes'] não vazio, chamar revision_service::create_revision(...).
    • motivation, context, impact, responsible_id vêm do dispatcher (Gestor preencheu antes do processamento ou null para autosync).

Task 7.5: Bug colateral em total_unidade_content

Files: classes/extensions/content/base/unit/unit_create_service.php:339-355

  • Step 1: linha 341-345 — $data inicializa apenas qtd_question_*, mas linha 348 lê e escreve $data['qtd_topics'] sem inicialização. Adicionar 'qtd_topics' => 0 no array.

Por quê: PHP 8.3 com declare(strict_types=1) emite warning em null + count.

Task 7.6: Performance — recolocar set_total_unidade_content fora do loop

Files: mesmo arquivo

  • Step 1: mover set_total_unidade_content para depois do loop. total_unidade_content($unidades) é constante em relação ao loop. Atual O(n²) vira O(n).

Task 7.7: Commit

  • Step 1:
git add -A classes/extensions/content/base/unit/unit_create_service.php
git commit -m "refactor(content): unit_create_service returns changes[] for revision pipeline

- execute() signature: void → array (P-4 keeps service static)
- persist() captures old_content/new_content for diff calculation
- caller of execute() now drives revision_service::create_revision
- fix: initialize qtd_topics in total_unidade_content
- perf: move set_total_unidade_content out of per-unit loop"

Phase 8 — Fechar caso de uso pedagógico

Task 8.1: Adicionar seção “Revisão de Conteúdo” em ciclo-de-alteracoes-do-word.md

Files: docs/metodologia/importacao-word/ciclo-de-alteracoes-do-word.md

  • Step 1: ler estado atual (em construção, linha 8).

  • Step 2: inserir entre seção “Sincronização Pedagógica SharePoint” e “Proteção do Aluno”:

## Revisão de Conteúdo

Cada novo processamento (segunda versão em diante) de um Arquivo de Disciplina (Word) gera uma **Revisão de Conteúdo** — registro que agrupa todas as alterações detectadas e os conflitos identificados naquele evento.

A Revisão de Conteúdo é aberta com motivação, contexto e impacto preenchidos pelo Gestor Pedagógico antes do processamento. Ao processar:

- Cada Unidade alterada gera um **Registro de Alteração Pedagógica** filho da Revisão, com diff por seção (informações gerais, tópicos, flashcards, banco de questões, vídeos, áudios, relações).
- Cada referência quebrada por uma alteração estrutural gera um **Conflito Pedagógico** filho do Registro correspondente.

O status da Revisão cascateia dos filhos: quando todos os Conflitos forem resolvidos ou dispensados pelo Gestor, e todos os Registros de Alteração estiverem resolvidos, a Revisão fica resolvida.

A Revisão alimenta o Relatório de Alteração Pedagógica usado para análise e decisão de comunicação ao Aluno.
  • Step 3: trocar status da página de “EM CONSTRUÇÃO” para “EM REVISÃO” se a pendência da linha 101-102 (limiar de relevância) for resolvida pelo Gestor antes do merge. Caso contrário, manter “EM CONSTRUÇÃO” e abrir issue editorial.

Task 8.2: Commit

  • Step 1:
git add -A docs/metodologia/importacao-word/ciclo-de-alteracoes-do-word.md
git commit -m "docs(metodologia): add Revisão de Conteúdo section to ciclo de alterações"

NOT in scope — pendências decorrentes

# Pendência Onde
1 Atualizar ADR-30 inteiro: trocar content_revision → revision, content_revision_service → revision_service, etc. (P-2) docs/plataforma/adrs/adr-30_*.md
2 Atualizar REF-30-A: pseudocódigos, signals (content_revision_opened → revision_opened) docs/plataforma/adrs/ref-30-a_*.md
3 Atualizar REF-30-B: descrição e cascata de status docs/plataforma/adrs/ref-30-b_*.md
4 Atualizar REF-30-C: tabela content.change (entity_root é revision) docs/plataforma/adrs/ref/ref-30-c_*.md
5 Inconsistência interna do terms — linhas 454, 480 referenciam aggregate: content_revision mas identifier é revision (P-1: NÃO tocar) terms-content.yaml
6 unit_versioning_service continua vazio (Wave 1 do ADR-30 lista como process_domain). Decidir se entra em plano separado ou fica para Wave seguinte base/unit_versioning/
7 RAG do VIGIM não configurado — limita pesquisa semântica nos terms/docs local/middag (rodar composer vigim:rag:setup)
8 Limiar objetivo de relevância para comunicação ao Aluno (pendência declarada em ciclo-de-alteracoes-do-word.md:101-102) Decisão pedagógica do Gestor
9 UI do Relatório de Alteração Pedagógica (report_change) — process/query, não bloqueia este plano change/report_change/
10 Geração de unit_snapshot quando Trilha publicada referencia uma versão — interage com product.trail entregue em 2026-04-30 Plano separado
11 Enum change_record_status em core.linkml.yaml:116 carrega vocabulário antigo (change_record) — deveria ser content_change_status para alinhar à renomeação. Não corrigir nesta entrega; abrir plano editorial separado quando os ADRs também forem atualizados .vigim/ddd/linkml/core.linkml.yaml
12 json-schema/contract/content_revision/ órfão se Phase 4.5 conseguir regenerar para revision/. Caso contrário, abrir issue no MIDDAG CLI sobre como o pipeline interpreta o slug .vigim/ddd/json-schema/contract/

Riscos e contramedidas

Risco Probabilidade Impacto Contramedida
ADR-707 (outbox) não existe ainda — — Mitigado: Task 0.1 confirmou existência em local_middag/classes/framework/infrastructure/bus/
Renomeação de signals quebra listeners externos — — Mitigado: Task 0.3 confirmou zero consumidores externos
PHP CLI local não carrega (icu4c 74 missing) Alta (atual) Alto — bloqueia todo composer build:* Phase 0.5 lista 4 opções de fix; trabalho pausado até resolver
Pipeline composer build:extensions não cria pasta nova ao trocar slug do LinkML Média Alto — força fallback manual Plano já prevê fallback manual nas Phases 1/2/3
Calculo de diff ficar caro em Disciplinas grandes Baixo Médio Hashes já existem, comparar hash antes de comparar JSON; só serializar diff quando hash difere
Falha parcial dentro de revision_service::create_revision Médio Alto Transação Moodle ($DB->start_delegated_transaction()) cobre revision + content_change + content_conflict
Caller de unit_create_service::execute não tem motivation/context/impact (cron sem Gestor) Alto Baixo Campos são nullable: true no LinkML — passar null e revision aceita
unit_content não expõe version via get_meta confiável Médio Médio Confirmar no Step 7.2; se não houver, usar unit_content_service::get_next_version aritmética para inferir
Inconsistência interna do terms (P-1, item 5 de NOT in scope) gera build_docs_glossary com warning Baixo Baixo Aceitar warning; documentar como decisão consciente em pendência editorial
Pipeline regenera content_change.php e perde edits MANUAL section Médio Médio Antes de cada composer build:extensions, conferir que edits estão entre BEGIN MANUAL / END MANUAL; nunca editar entre BEGIN AUTO-GENERATED / END AUTO-GENERATED

Resumo executivo

  • 10 phases ordenadas por dependência: 0 → 0.5 → 1 → 2 → 3 → 4 → 4.5 → 5 → 6 → 7 → 8.
  • Phase 0 ✅ CONCLUÍDA — verificações: ADR-707 existe, sem consumidores externos, LinkML alinhado, pipeline confirmado.
  • Phase 0.5 BLOQUEADA — PHP CLI local quebrado por dylib libicuio.74.dylib ausente. Resolver antes de prosseguir.
  • Phase 1 alinha código ao terms para content_change via pipeline. Pode ser merged isolada.
  • Phases 2 + 3 + 4 + 4.5 são Wave 1 do ADR-30 (entities + signals + json-schemas). Mergeable em conjunto.
  • Phases 5 + 6 + 7 são Wave 2 (lógica de negócio + costura no pipeline).
  • Phase 8 é doc, pode rodar em paralelo a partir da Phase 4.
  • Sem refatoração estrutural do unit_create_service (P-4 honrado).
  • Sem alteração no terms-content.yaml (P-1 honrado).
  • LinkML é a verdade dos campos (P-8); pipeline gera items EAV (P-9).
  • ADRs ficam desalinhados após este plano — pendência editorial #1-#4 abre PR de doc separado.
Navigation

Type to search…

↑↓ navigate↵ selectEsc close