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 compartilhadosdocs/plataforma/adrs/adr-30_dominio-content-arquitetura-e-materializacao.mddocs/plataforma/adrs/ref-30-a_pipeline-de-processamento-de-conteudo.mddocs/plataforma/adrs/ref-30-b_algoritmo-de-deteccao-de-conflitos.mddocs/plataforma/adrs/ref/ref-30-c_content-subdomain-map.mddocs/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}.phpsignal_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}.phpTask 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+ relinkbrew 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.txtpara 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:extensionsPRIMEIRO — pipeline regenerachange_record.phpcomocontent_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
- namespace
-
Step 3: atualizar
content_change_service.phppara setar$dto->type = content_change::TYPEno override decreate()/update().
Nota crítica: o método
on_file_syncedatual (change_record_service.php:61-65) tem TODO BL-001 não implementado. Mover o#[async_on(file_word_synced)]para orevision_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.yamlestá ativo no manifesto do pipeline (.vigim/ddd/linkml/...). -
Step 2:
composer build:extensions— deve criarclasses/extensions/content/change/revision/revision.phpcom:#[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. Factoryto_item_dto(file_word_id, parent_id, status, motivation, context, impact, responsible_id, total_units_changed, total_conflicts, severity)retornandoitem_dto. Factoryfrom_item(revision $r): arraypara 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_interfacedeclara getters tipados (mesma assinatura dos getters auto-gerados, mas como contrato). -
Step 2:
revision_repository_interfacedeclarafind_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, overridecreate/updatesetando$dto->type = revision::TYPE.create_revision/mark_resolved/recompute_severitylançamcoding_exceptionneste 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_serviceno 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.phpfoi 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, overridecreate/updatesetando type. Demais métodos lançamcoding_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/comunit_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
- 4 arquivos:
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)eget_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 pelounit_create_servicena 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): arraycomparando 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 emdiff_*. - Step 3: implementar helper
max_severity(?string $current, ?string $candidate): ?stringcom ordemlow < medium < high < critical.
Task 5.3: Implementar mark_resolved e recompute_severity
- Step 1:
mark_resolved(int $revision_id)valida que todos oscontent_changefilhos estão resolvidos antes de marcar revision comoresolved. Emiterevision_resolved. - Step 2:
recompute_severity(int $revision_id)recalculaseverityetotal_conflictslendo 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.phpclasses/extensions/content/change/revision/revision_service.php
Por quê: quem reage ao
file_word_syncedpara criar a revision é orevision_service. Ocontent_changeé entidade-filho; não tem agência sobre o aggregate.
- Step 1: remover hook
on_file_synceddocontent_change_service(caso pipeline tenha regenerado o stub). - Step 2: adicionar
#[async_on(signal: file_word_synced::class, priority: 20)]em métodoon_file_synceddorevision_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): arrayretornandocontent_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
trailque referencia umaunit? Confirmar com vocabulárioproduct.trailentregue em 2026-04-30. Prováveltrail_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_idou similar. - Step 2: verificar se há
unit_snapshotativo 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 docontent_changeestão resolvidos → marcacontent_changeresolvido. - Step 2: ao resolver
content_change, verificar se todos os filhos darevisionestão resolvidos → marcarevisionresolvida. - Step 3: emitir
revision_resolvedquando 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:
- Carrega
content_conflict. - Aplica
resolution_type(content_restored / trail_adapted / plan_adapted / dismissed). - Marca como resolvido com
resolved_by,resolved_at,resolution_note. - Emite
content_conflict_resolved. - Dispara cascata via
conflict_detection_service::cascade_resolve(...).
- Carrega
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(...): voidparapublic 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 decreate_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, chamarrevision_service::create_revision(...). motivation,context,impact,responsible_idvêm do dispatcher (Gestor preencheu antes do processamento ou null para autosync).
- Capturar
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 —
$datainicializa apenasqtd_question_*, mas linha 348 lê e escreve$data['qtd_topics']sem inicialização. Adicionar'qtd_topics' => 0no 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_contentpara 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 |
|---|---|---|---|
| — | — | Mitigado: Task 0.1 confirmou existência em local_middag/classes/framework/infrastructure/bus/ |
|
| — | — | 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.dylibausente. Resolver antes de prosseguir. - Phase 1 alinha código ao terms para
content_changevia 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.