ADR-30: Dominio Content — Arquitetura e Materialização
Status: Aceito Data: 2026-04-23 Autor: Michael Meneses (Arquiteto)
Contexto
O domínio content é o primeiro a ter especificação completa para implementação. Após 9 sessões de trabalho, o catálogo de terms está normalizado (388 terms, 127 materializable), os contratos JSON validam a forma de cada entity (64 arquivos) e os LinkML MANUAL blocks definem a persistência EAV.
Este ADR consolida todas as decisões de arquitetura e materialização do domínio content em um único documento. Absorve e substitui ADR-201 (subdomains), ADR-202 (entity vs attribute), ADR-903 (change record e conflitos) e ADR-904 (mapa de materialização). Cada term com identifier recebe uma decisão explícita: o que gera, em que tier, com que dependências.
Organização em Subdomains
O domínio content concentra três preocupações funcionais distintas. A subdivisão em subdomains garante escopo claro e evolução independente.
Subdomains
| Subdomain | Slug | Dir | Escopo funcional |
|---|---|---|---|
| Base de Conteúdo | content.base |
content/base |
Modelagem: Disciplina, Unidade, questões, tópicos, flashcards, VOs |
| Gestão e Publicação | content.management |
content/management |
Operação: Word file, sync SharePoint, processamento, commands, jobs |
| Alteração Pedagógica | content.change |
content/change |
Impacto: Revisão de conteúdo, relatório, resolução de conflito |
Sub-subdomain retido: content.base.bank_question — agrupa os tipos de questão (question_multiplechoice, question_truefalse, question_written).
Consolidação (ADR-22 §5): Os antigos sub-subdomains content.base.info e content.base.topic foram consolidados em content.base. Não existem mais como divisões separadas.
Termos cross-cutting (Versionamento, Snapshot genérico, Versão Ativa) permanecem na raiz content sem subdomain, até que sua alocação definitiva se estabilize.
Critérios de alocação
- Modelagem estática (o que é o conteúdo) →
content.base - Operação (como o conteúdo é criado, processado, sincronizado) →
content.management - Impacto (o que acontece quando o conteúdo muda) →
content.change - Cross-cutting (aplica-se a mais de um subdomain) →
contentraiz
Relação entre subdomains
content.management produz → content.base (processamento gera Unidades/tópicos)
content.management detecta → content.change (sync identifica alterações)
content.change referencia → content.base (conflito impacta Unidade/Trilha)O fluxo é unidirecional: management alimenta base e dispara change. Change consulta base mas não o modifica — quem resolve é o Gestor via commands de management.
Princípio de Classificação
Entities mínimos, attributes ricos
Apenas objetos com identidade própria, lifecycle independente e necessidade de queries diretas são entities. Tudo o mais é attribute (metadata no parent) ou value_object (DTO transiente).
A Base de Conteúdo é quase estática — define o conteúdo pedagógico consumido por outros domínios (atividades, motor pedagógico, métricas). A “dinâmica” ocorre fora de content. Isso favorece poucos entities com attributes ricos.
Contagem atualizada
| Tipo | Quantidade | Exemplos |
|---|---|---|
| entity_root | 4 | discipline, unit, file_word, content_revision |
| entity_child | 7 | unit_content, content_change, content_conflict, sync_job, process_job, flashcard_job + (ver tabela) |
| value_object | 10 | flashcards, unit_info, topic, video, question_multiplechoice, question_truefalse, question_written + (ver tabela) |
Correção importante: flashcards é value_object — seção embarcada no unit_content, não registro EAV separado. Não gera model + DTO, gera readonly class.
Correção importante: doctrine, jurisprudence e legislation são campos do unit_info — não são VOs independentes. Não geram classes próprias.
Regras de classificação
| Classificação | Critério | Gera |
|---|---|---|
| entity_root | Identidade própria, lifecycle, queries diretas, aggregate root | model + service + DTO + repository |
| entity_child | Identidade própria, lifecycle vinculado ao parent, queries via parent | model + DTO |
| value_object | Imutável, sem identidade, sem persistência própria | readonly class (from_array/to_array) |
| attribute | Metadata no parent entity, sem registro próprio | — |
| attribute_group | Enum PHP gerado a partir de subterms | PHP enum |
| concept | Agrupador lógico, sem registro no EAV | — |
| process_command | Ação do sistema ou do Gestor | command + handler |
| process_domain | Serviço de domínio standalone | standalone service |
| rule | Contrato polimórfico ou regra de domínio | PHP interface (manual) |
O arquivo Word copiado é attribute, não o entity
O entity file_word é o registro do processamento. O arquivo Word em si (copiado para o file_storage do Moodle) é um attribute desse registro.
Regra para chave-valor genérica
Cada entity pode ter um attribute de chave-valor para dados não-estruturados (métricas totalizadas, configurações ad-hoc). Isso será definido como padrão no LinkML MANUAL block de cada entity.
Hierarquia content_revision
Problema
Quando um novo file_word é processado (segunda versão em diante), o sistema precisa: registrar o evento de reprocessamento, detectar quais Unidades mudaram, calcular diff semântico, detectar conflitos pedagógicos e permitir que o Gestor trate cada conflito individualmente.
Decisão — 3 entity types, 3 níveis
content_revision (1 per reprocessamento — o evento)
└── content_change (N per unit alterada — contém diff)
└── content_conflict (M per referência quebrada)Cada entity type tem uma responsabilidade clara:
content_revision= o evento de processamentocontent_change= o diff de uma unidadecontent_conflict= uma referência quebrada
| Entity | Type | Aggregate | Domain | Papel |
|---|---|---|---|---|
content_revision |
entity_root | content_revision |
content.change | Evento de processamento (1 per file_word) |
content_change |
entity_child | content_revision |
content.change | Diff de 1 unidade alterada (N per revision) |
content_conflict |
entity_child | content_revision |
content.change | Referência quebrada (M per content_change) |
Hierarquia EAV
content_revision (parent_id → discipline)
│
├── content_change #1 (parent_id → content_revision, entity_id → unit 501)
│ ├── content_conflict #1 (parent_id → content_change #1)
│ └── content_conflict #2 (parent_id → content_change #1)
│
├── content_change #2 (parent_id → content_revision, entity_id → unit 502)
│ └── content_conflict #3 (parent_id → content_change #2)
│
└── content_change #3 (parent_id → content_revision, entity_id → unit 503)
(sem conflitos)Campos — content_revision
| Campo | Tipo | Descrição |
|---|---|---|
id |
auto | ID EAV |
parent_id |
FK | discipline |
file_word_id |
FK, nullable | file_word que originou (null se edição manual) |
status |
enum | open, in_review, resolved, archived |
motivation |
text, nullable | Motivação pedagógica (preenchida pelo Gestor) |
context |
text, nullable | Contexto da revisão |
impact |
text, nullable | Impacto didático esperado |
responsible_id |
FK user | Quem iniciou o processamento |
total_units_changed |
int | Total de units alteradas (computado) |
total_conflicts |
int | Total de conflitos detectados (computado) |
severity |
enum, nullable | Maior severity entre os content_conflicts |
Campos — content_change
| Campo | Tipo | Descrição |
|---|---|---|
id |
auto | ID EAV |
parent_id |
FK | content_revision |
entity_type |
enum | discipline, unit, material |
entity_id |
FK | ID do objeto alterado |
status |
enum | open, in_review, resolved, archived |
from_version |
int | Versão anterior do unit_content |
to_version |
int | Versão nova |
snapshot_id |
FK, nullable | unit_snapshot no momento da alteração |
severity |
enum, nullable | Maior severity dos content_conflicts |
diff_info |
JSON, nullable | Diff da seção info |
diff_topic |
JSON, nullable | Diff dos tópicos |
diff_flashcard |
JSON, nullable | Diff dos flashcards |
diff_video |
JSON, nullable | Diff dos vídeos |
diff_audio |
JSON, nullable | Diff dos áudios |
diff_question_truefalse |
JSON, nullable | Diff das questões VF |
diff_question_multichoice |
JSON, nullable | Diff das questões objetivas |
diff_question_essay |
JSON, nullable | Diff das questões escritas |
diff_relations |
JSON, nullable | Diff do grafo de relações |
diff_hash |
string, nullable | Hash do diff completo |
Campos — content_conflict
| Campo | Tipo | Descrição |
|---|---|---|
id |
auto | ID EAV |
parent_id |
FK | content_change |
conflict_type |
enum | trail, plan |
status |
enum | open, in_review, resolved, dismissed |
section |
enum | info, topic, flashcard, video, audio, question_* |
reference_id |
int | ID do item afetado no unit_content |
reference_hash |
string, nullable | Hash do item (evidência) |
reason |
enum | item_removed, item_modified, section_removed |
severity |
enum | low, medium, high, critical |
target_type |
enum | trail, plan |
target_id |
FK | ID da Trilha ou Plano |
target_context |
text, nullable | Contexto legível para o Relatório |
resolution_type |
enum, nullable | content_restored, trail_adapted, plan_adapted, use_last_valid, dismissed |
resolution_note |
text, nullable | Nota do Gestor |
resolved_by |
FK user, nullable | Quem resolveu |
resolved_at |
datetime, nullable | Quando resolveu |
Fluxo de criação
1. Gestor inicia reprocessamento do file_word
→ Sistema pergunta: motivação? contexto? impacto esperado?
→ content_revision criada (status: open)
2. Sistema processa o Word e gera novas versões de unit_content
→ Para cada unit com hash diferente:
→ content_change criado (parent: content_revision)
→ diff calculado: v(n-1) × v(n), item a item
→ diff_* preenchidos
3. Para cada item removed/modified no diff:
→ Trilha referencia esse item + sem snapshot? → content_conflict (type: trail)
→ Plano referencia esse item + sem snapshot? → content_conflict (type: plan)
→ severity calculada conforme impacto
4. content_revision.severity = max(content_conflicts.severity)
content_revision.total_conflicts = count(content_conflicts)
5. Gestor consulta Relatório de Alteração Pedagógica
→ Lista content_revisions com summary
→ Expande para ver content_changes por unit
→ Trata cada content_conflict individualmente
→ Quando todos resolvidos: content_revision.status → resolvedPipeline Operacional — Visão Geral
┌─────────────────────────────────────────────────────────────────────┐
│ SINCRONIZAÇÃO (CRON/Gestor) │
│ │
│ SharePoint ──sync──▶ Identifica IDNUMBER ──▶ Cria discipline │
│ (padrão do nome) + registra file_word │
│ │
│ Arquivo inválido (nome fora do padrão) → desconsiderado │
└─────────────────┬───────────────────────────────────────────────────┘
│ ad_hoc trigger
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PRÉ-PROCESSAMENTO (ad_hoc) │
│ │
│ file_word ──▶ Gera Markdown de Tópicos (para flashcards) │
│ ──▶ Gera JSON manifest de Unidades da Disciplina │
│ (evita corrupção em coluna única para docs grandes) │
└─────────────────┬───────────────────────────────────────────────────┘
│ disponível para o Gestor
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PROCESSAMENTO (ação manual do Gestor) │
│ │
│ Gestor acessa discipline ──▶ Lista de file_word versions │
│ Seleciona version ──▶ "Processar" │
│ ├─▶ Cria/atualiza registros unit (EAV) │
│ ├─▶ Cria curso-unidade Moodle (IDNUMBER vinculado ao unit) │
│ └─▶ Cria unit_content (versão N, com hashes por seção) │
│ │
│ 1º processamento: unit + unit_content criados │
│ 2º+ processamento: ▼ (se hash mudou) │
└─────────────────┬───────────────────────────────────────────────────┘
│ a partir do 2º processamento
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CONTENT REVISION (automático no 2º+ proc.) │
│ │
│ content_revision (status: open) │
│ └─▶ Para cada unit com hash alterado: │
│ └─▶ content_change (diff por seção) │
│ └─▶ Busca referências em Trilhas/Planos │
│ └─▶ content_conflict (se ref quebrada) │
│ │
│ Possíveis consequências: │
│ • Notificação no Caderno Online do Aluno │
│ • Impacto no Plano do Aluno (snapshot protege ou não) │
│ • Bloqueio de nova publicação de Trilha Pedagógica │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ FLASHCARDS (desacoplado do processamento) │
│ │
│ Gestor aciona "Gerar Flashcards" (se hash do Markdown mudou) │
│ ├─▶ ad_hoc: envia Markdown para API externa (Law School) │
│ ├─▶ Aguarda retorno (5-20 min) — job em fila │
│ ├─▶ Baixa flashcard_raw e salva no file_word │
│ └─▶ Distribui para unit_content existentes (update flashcard) │
│ │
│ Decisão: flashcards são gerados DEPOIS do processamento. │
│ Não há dependência bloqueante entre processar e gerar flashcards. │
│ O Gestor pode processar imediatamente e atualizar flashcards │
│ quando disponíveis. │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ OBSERVABILIDADE (transversal) │
│ │
│ Todos os jobs (sync, process, flashcard) registram: │
│ • Status, progresso, etapa, resultado, erro │
│ • Timestamps de início/conclusão │
│ • Notificação ao Gestor: início + conclusão (ou erro) │
│ │
│ Requisitos: acompanhar, registrar, debugar, auditar │
└─────────────────────────────────────────────────────────────────────┘Mapa de Materialização
Legenda
| Tier | Geração | Status |
|---|---|---|
| T1 | Gera PHP agora (build:extensions) | Ativo |
| T2 | Em schema, geração planejada | Próxima wave |
| T3 | Reservado, sem geração | Futuro |
| — | Não materializa | Ontológico puro |
Entities (EAV) — T1
| # | Identifier | Type | Subdomain | Gera | Contrato | LinkML |
|---|---|---|---|---|---|---|
| 1 | discipline |
entity_root | content.base | model + service + DTO + repository | OK | OK |
| 2 | unit |
entity_root | content.base | model + service + DTO + repository | OK | OK |
| 3 | file_word |
entity_root | content.management | model + service + DTO + repository | OK | OK |
| 4 | content_revision |
entity_root | content.change | model + service + DTO + repository | OK | OK |
| 5 | unit_content |
entity_child | content.base | model + DTO | OK | OK |
| 6 | content_change |
entity_child | content.change | model + DTO | OK | OK |
| 7 | content_conflict |
entity_child | content.change | model + DTO | OK | OK |
| 8 | sync_job |
entity_child | content.management | model + DTO | OK | PENDENTE |
| 9 | process_job |
entity_child | content.management | model + DTO | OK | PENDENTE |
| 10 | flashcard_job |
entity_child | content.management | model + DTO | OK | PENDENTE |
Value Objects — T1
| # | Identifier | Subdomain | Gera | Contrato | Nota |
|---|---|---|---|---|---|
| 11 | unit_info |
content.base | readonly class | OK | Seção info do unit_content |
| 12 | topic |
content.base | readonly class | OK | Com subtitle + observations |
| 13 | synthesis |
content.base | campo de topic | OK | Não gera classe própria — é topic.synthesis |
| 14 | flashcards |
content.base | readonly class | OK | Seção embarcada no unit_content (não EAV) |
| 15 | video |
content.base | readonly class | OK | Asset no content_bank |
| 16 | question_multiplechoice |
content.base.bank_question | readonly class | OK | Estende question_base |
| 17 | question_truefalse |
content.base.bank_question | readonly class | OK | Estende question_base |
| 18 | question_written |
content.base.bank_question | readonly class | OK | Estende question_base |
Services (process_domain) — T1
| # | Identifier | Subdomain | Gera | Responsabilidade | Dependências |
|---|---|---|---|---|---|
| 19 | publication |
content.management | standalone service | Orquestra o processamento: interpreta file_word → cria/atualiza units → gera unit_content | file_word_process, unit_versioning |
| 20 | file_word_process |
content.management | standalone service | Interpreta o Word: aplica Contrato Estrutural + Catálogo de Tags → extrai unidades e componentes → gera Markdown de Tópicos | — |
| 21 | sharepoint_sync |
content.management | standalone service | Sincroniza Disciplinas com SharePoint via Microsoft Graph: detecta alterações → cria/atualiza file_word → dispara pré-processamento | microsoft_graph (adapter) |
| 22 | unit_versioning |
content.base | standalone service | Gerencia versões de unit_content: cria nova versão, compara hashes, determina Versão Ativa | — |
Decisão: object_versioning (process_domain, materialize: false) permanece false — é conceito genérico. unit_versioning é a materialização concreta.
Commands (process_command) — T2
| # | Identifier | Subdomain | Trigger | Gera | Payload |
|---|---|---|---|---|---|
| 23 | unit_process |
content.management | cron * * |
command + handler | { discipline_id, file_word_id } |
| 24 | flashcard_generate |
content.management | manual (Gestor) | command + handler | { discipline_id, file_word_id } |
| 25 | flashcard_persist |
content.management | cron */1 * |
command + handler | { file_word_id } |
| 26 | file_word_autosync |
content.management | cron 30 7,18 |
command + handler | { } (varredura completa) |
| 27 | file_word_manualsync |
content.management | cron */1 (fila) |
command + handler | { discipline_id } |
| 28 | content_conflict_resolution |
content.change | manual (Gestor) | command + handler | { conflict_id, resolution_type, resolution_note } |
Enums — T1
| # | Identifier | Subdomain | Gera | Decisão |
|---|---|---|---|---|
| 29 | question_category |
content.base | PHP enum | Habilitar materialização — usado nos contratos como campo category |
| 30 | bracket_tag |
content.management | — | materialize: false — catálogo de documentação, não gera código |
Rules com identifier — Decisões
| # | Identifier | Decisão | Justificativa |
|---|---|---|---|
| 31 | question_contract |
Interface PHP (manual, não gerada) | Contrato polimórfico para questões — PHP interface com métodos get_statement(), get_difficulty(), etc. Implementado por cada VO de questão |
| 32 | content_conflict_contract |
Interface PHP (manual, não gerada) | Contrato polimórfico para conflitos — PHP interface para detecção/resolução uniforme |
Processes com identifier — Decisões
| # | Identifier | Type | Decisão | Justificativa |
|---|---|---|---|---|
| 33 | file_word_validation |
process | Método de file_word_process | Etapa interna do processamento, não service independente |
| 34 | report_change |
process | Query service (manual) | View/query sobre registros existentes — não EAV, não gera modelo |
Technical Components — Fora do content (BL-004)
| # | Identifier | Decisão |
|---|---|---|
| 35 | sharepoint |
Adapter externo — implementação em classes/adapter/sharepoint/ |
| 36 | microsoft_graph |
Adapter externo — implementação em classes/adapter/sharepoint/ |
Termos sem materialização (ontológicos puros) — 23 terms
Agrupadores, conceitos, event_groups, attributes sem identifier, roles — 23 termos restantes. Não geram código. Servem a glossário, árvore e documentação.
Fora do Domínio Content — Relocação Pendente
| Term | Identifier | Domain atual | Destino sugerido | Motivo |
|---|---|---|---|---|
| Histórico de Uso da Questão | question_history |
content.base | engine.session ou metrics | Registro de runtime, não propriedade da Base de Conteúdo |
| Questão Elegível | — (concept) | content.base | engine.algorithm | Critério de seleção depende de contexto de execução |
Ordem de Implementação
Wave 1 — Entities + VOs (fundação)
discipline → unit → unit_content (+ VOs: topic, unit_info, questions, flashcards, video)
file_word
content_revision → content_change → content_conflict
Jobs: sync_job, process_job, flashcard_jobDependência: Pipeline LinkML + build:extensions deve estar funcional.
Wave 2 — Services (lógica de negócio)
file_word_process (parsing do Word)
unit_versioning (hash comparison, versão ativa)
publication (orquestração: file_word → units → unit_content)
sharepoint_sync (integração SharePoint — depende de adapter BL-004)Dependência: Wave 1 completa + adapters de BL-004.
Wave 3 — Commands (automação)
file_word_autosync + file_word_manualsync (sync CRON)
unit_process (processamento CRON)
flashcard_generate + flashcard_persist (flashcard pipeline)
content_conflict_resolution (resolução manual)Dependência: Wave 2 completa.
Wave 4 — Observabilidade + Notificações
Job monitoring (status, progresso, debug, audit)
Notificações ao Gestor (início/conclusão/erro de jobs)
Notificações ao Aluno (alterações de conteúdo relevantes)
Report_change (query service para Relatório de Alteração)Dependência: Wave 3 completa.
Decisões Consolidadas
Decisões de arquitetura (sessões 6-8)
| # | Decisão | Justificativa |
|---|---|---|
| 1 | Flashcards desacoplados do processamento | Geração leva 5-20 min, bloquearia Gestor. Processar primeiro, flashcards depois. |
| 2 | question_category materializa como enum |
Usado nos contratos (campo category), precisa de PHP enum |
| 3 | question_contract e content_conflict_contract são interfaces manuais |
Rules polimórficas — interface, não specification gerada |
| 4 | file_word_validation é método, não service |
Etapa interna de file_word_process |
| 5 | object_versioning não materializa |
Conceito genérico; unit_versioning é a materialização concreta |
| 6 | report_change é query service manual |
View sobre registros existentes, não entity |
| 7 | question_history sai do content |
Runtime, não Base de Conteúdo |
| 8 | Video/audio no content_bank (não info) | ADR-21: assets com mídia, hashing e relations |
| 9 | overview substituiu general_information |
Evita redundância info.general_information |
| 10 | synthesis não gera classe própria |
É campo do topic, não VO independente |
Decisões de pipeline (sessão 9)
| # | Decisão | Opção | Justificativa |
|---|---|---|---|
| 11 | JSON manifest de unidades | file_storage vinculado ao file_word | Padronizar no file_storage. Sem limite de tamanho, padrão Moodle para artefatos. |
| 12 | Trigger do pré-processamento | Signal file_word_created → ad_hoc task |
Event-driven (ADR-707), desacoplado, rastreável pelo job. |
| 13 | Content revision — criação | Gestor preenche antes de processar (campos opcionais) | Campos opcionais, não bloqueiam. Fallback: texto automático “Reprocessamento de version N”. Tela mostra prévia do que será reprocessado (requer JSON manifest). |
| 14 | Distribuição de flashcards | Automático por topic_ref | Match título do tópico → unit_content.topic. Flashcards não alocados ficam no file_word como “não alocados”, visíveis no dashboard do Gestor. |
| 15 | Notificações | message_send do Moodle, 2 providers |
content_job_status (Gestor, backend/Moodle) e content_change_alert (Aluno, via API para NextJS). |
| 16 | Hash comparison | Por seção (info_hash, topic_hash, etc.) | Já nos contratos. Suficiente para content_change saber quais seções mudaram. |
| 17 | Unit que desaparece do Word | Status archived no unit + bloqueia curso-unidade |
Soft delete, preserva histórico. Curso-unidade Moodle também bloqueado. Se unit voltar → sempre gera novo unit_content. |
| 18 | Curso-Unidade Moodle | Criado no “Processar” pelo Gestor (backend/Moodle) | Idnumber do curso = idnumber do unit. Criação atômica com o registro EAV. Aluno não acessa Moodle, somente NextJS. |
| 19 | Processamento concorrente | Lock por discipline, somente version mais recente | Só o file_word mais recente pode ser processado. Se já houver processamento em andamento, o novo fica na fila. |
| 20 | Detecção de conflitos — escopo | Referências diretas (Trilha + Planos do Aluno ativos) | Conflito com Trilha: bloqueia nova publicação, precisa validação. Conflito com Plano do Aluno: somente se item específico foi selecionado na Trilha/Plano de Estudo e não existe mais. Alteração de tópico: Gestor decide notificação ao Aluno a partir do Relatório. Validado com Codex-002c-snapshot.md. |
| 21 | Signals emitidos | Lifecycle completo por entity root | file_word: created, preprocessed, processed. unit: created, archived. unit_content: published. content_revision: opened, resolved. content_conflict: detected, resolved, dismissed. flashcard_job: generated, persisted, failed. |
| 22 | Markdown de Tópicos | Cache por hash do file_word | Cada file_word gera MD no pré-processamento. Flashcards só regenerados se hash do MD diferente do último. Consulta por hash na tabela metadata. |
| 23 | Retry de jobs | Auto para rede/timeout, manual para falha de negócio | failed_retryable vs failed. Falha de validação do Word = Gestor corrige. Falha de API = retry automático com backoff. |
| 24 | Idempotência do processamento | Hash check + botão desabilitado | Backend: se version já processada (mesmo hash), ignora. Frontend: botão “já processado” desabilitado. |
| 25 | Escopo dos REFs | Diagramas + signals + pseudocódigo + testes de aceitação | REF-30-A (pipeline) e REF-30-B (conflitos) com nível de detalhe para implementação direta. |
Decisões de hierarquia content_revision (sessão 8)
| # | Decisão | Justificativa |
|---|---|---|
| 26 | 3 entity types dedicados (content_revision, content_change, content_conflict) | Cada tipo tem uma responsabilidade clara; suporta processamento futuro sem file_word |
Decisões de classificação (consolidação)
| # | Decisão | Justificativa |
|---|---|---|
| 27 | flashcards reclassificado como value_object |
Seção embarcada no unit_content, não registro EAV separado |
| 28 | doctrine, jurisprudence, legislation são campos do unit_info, não VOs independentes |
Campos textuais internos ao VO unit_info, não justificam classes próprias |
Gaps identificados na validação do Codex-002c
| Gap | Descrição | Ação |
|---|---|---|
use_last_valid |
Opção de resolução de conflito com Plano: “utilizar última referência válida”. Não está no enum conflict_resolution_type. |
Incluído na tabela de campos em 2026-10-15. Falta incluir no enum de código (conflict_resolution_type) e em core.linkml.yaml. |
recheck |
Ação de “Verificar novamente” para conflito com Trilha. Não é resolução — é re-validação do sistema. | Definir como ação de UI (não resolution_type). O sistema re-executa a checagem de consistência. |
| Notificação NextJS | Aluno interage com NextJS, não Moodle. content_change_alert precisa de endpoint API para push. |
Incluir no REF-30-A como signal → API endpoint → NextJS. Atualizado em 2026-10-15: a decisão do Gestor passa a ser por item (content_item_approved, epic moodle-local_helico#118); a notificação ao Aluno é fase posterior. |
Consequências
- Mapa completo para implementação — equipe sabe exatamente o que gerar para cada term
- 64 contratos JSON já validam a forma dos dados
- Pipeline operacional documentado end-to-end
- Decisões de materialização explícitas — sem ambiguidade
- Ordem de waves permite paralelismo (W1 pode ter 3 devs simultâneos)
- Cada subdomain tem escopo claro e pode evoluir independentemente
- Diretórios PHP refletem a separação funcional (
content/base/,content/management/,content/change/) - Modelo 1 + N claro: 1 revision → N content_changes → M content_conflicts
- Entities mínimos (4 roots + 7 children) reduzem registros EAV
- Value objects mantêm tipagem forte em PHP sem custo de persistência
- Adapters SharePoint (BL-004) são pré-requisito para W2 completa
- Schema change de subterm (identifier) depende de middag
- Question_history precisa de home em outro domínio antes de migrar
- 3 níveis de hierarquia no EAV (revision → content_change → content_conflict)
- Attributes complexos (arrays de questões, flashcards) precisam de serialização JSON
- Queries que filtram por attribute interno exigem JSON search ou índices específicos
ADRs Relacionados
- ADR-01 — Separação de responsabilidades e fronteira MIDDAG
- ADR-05 — Contratos de interface para tipos polimórficos
- ADR-10 — EAV próprio em local_helico
- ADR-11 — Estratégia de versionamento snapshot imutável
- ADR-20 — Pipeline terms→LinkML→PHP
- ADR-21 — Contratos JSON para validação de entities
- ADR-22 — Convenções de domínio e pertencimento de terms
- ADR-707 — Signal outbox pattern (middag)
REFs Relacionados
- REF-30-A — Pipeline de Processamento de Conteúdo
- REF-30-B — Algoritmo de Detecção de Conflitos Pedagógicos
- REF-30-C — Mapa term → subdomain → classificação
- REF-30-D — Inventário entity / attribute / VO
- REF-30-E — Especificação dos contratos de interface
Histórico
Consolida ADR-201, ADR-202, ADR-903 e ADR-904. Corrige classificação de flashcards (value_object), remove doctrine/jurisprudence/legislation como VOs independentes, atualiza nomenclatura (content_change, content_conflict, content_conflict_resolution), consolida subdomínios (ADR-22 §5).