Skip to content

ADR-22: Convenções de domínio e pertencimento de terms

ADR-22: Convenções de domínio e pertencimento de terms

Status: Aceito Data: 2026-04-22 Autor: Michael Meneses (Arquiteto)

Contexto

Após a normalização completa do catálogo de terms (388 terms, 21 domínios, 127 materializable) e a especificação de contratos JSON do domínio content (64 arquivos), foi necessário confrontar a árvore de cada domínio para garantir que os terms estejam corretamente posicionados. A análise revelou termos genéricos presos a domínios específicos, subdomínios excessivamente fragmentados, nomes de domínio ambíguos e parents cross-domain que quebravam a navegação da árvore.

ADRs relacionados

  • ADR-20 — Pipeline terms→LinkML→PHP
  • ADR-21 — Contratos JSON para validação de entities
  • ADR-30 — Domínio Content (arquitetura change_record, conflitos, mapa de materialização)

Decisões

1. Conceitos genéricos movidos para terms.yaml

Quatro conceitos do domínio content são transversais e não pertencem a nenhum domínio específico:

Term Domain anterior Novo parent
Rastreabilidade Pedagógica content.change HÉLICO (raiz)
Snapshot content Rastreabilidade Pedagógica
Versionamento de Objetos content Rastreabilidade Pedagógica
Versão Ativa content Versionamento de Objetos

Justificativa: Snapshot e Versionamento são padrões arquiteturais usados por múltiplos domínios (content, engine, product). Rastreabilidade Pedagógica agrupa esses conceitos e também é cross-cutting. Mantê-los em content impedia que outros domínios se declarassem filhos naturais dessas abstrações.

2. Versão Ativa — parent ajustado

  • Antes: parent Versionamento de Unidade (content.base)
  • Depois: parent Versionamento de Objetos (genérico)

O conceito de “versão vigente” é genérico e não específico de Unidades.

3. Histórico de Uso da Questão movido para engine

  • Antes: domain: content.base, parent Banco de Questões, aggregate discipline
  • Depois: domain: engine, parent Histórico Diagnóstico

Justificativa: O histórico de uso nasce da execução do estudo, não da autoria do conteúdo. O Histórico Diagnóstico já agrupa evidências acumuladas do Aluno para decisões pedagógicas. O aggregate discipline foi removido pois o histórico pertence ao contexto do motor, não à entity discipline.

4. Conteudista — mantém-se em content.base, futuro VO

O Conteudista é um role editorial específico da Base de Conteúdo. Permanece em content.base com parent Base de Conteúdo. Em fase futura, poderá ser criado como Value Object para receber dados de sistemas externos.

5. Subdomínios consolidados no content

Subdomain anterior Novo domain Terms afetados
content.base.info content.base unit_info, legislation, jurisprudence, doctrine, video, Áudios da Unidade, Quadro Geral de Informações
content.base.topic content.base topic, synthesis

Mantido: content.base.bank_question (3 VOs com identidade forte: question_multiplechoice, question_truefalse, question_written).

Justificativa: info e topic tinham menos de 5 terms cada e todas são filhas diretas de Unidade ou Material Didático. A granularidade excessiva fragmentava a árvore sem benefício semântico.

6. Domínio api renomeado para platform

Todos os 36 terms com domain: api passam a usar domain: platform.

Justificativa: O domínio mistura componentes técnicos (Backend, Moodle, React), telas/screens (Área do Aluno, Roteiro de Estudos) e roles (Gestor Pedagógico, Permissão). O nome api sugere apenas interface programática, enquanto platform reflete o macrodomínio “Plataforma e Sistema” que a raiz Plataforma e Sistema já expressa.

7. Bloco de Montagem e Tipo de Módulo movidos para product.learning_path

  • Antes: domain: engine.plan
  • Depois: domain: product.learning_path
  • Parent: Montagem dos Módulos (já em product.learning_path)

Justificativa: Ambos são conceitos de design da Trilha (configuração pelo Gestor), não de execução do motor. O parent já estava em product.learning_path; o domain agora acompanha.

8. Parents cross-domain — convenção aceita

Regras configuradas na Trilha mas executadas pelo motor mantêm cross-domain parent intencional:

Term Domain Parent (outro domain)
Regra de Conclusão activity Configuração das Atividades (product.learning_path)
Regra de Disponibilidade engine.plan Configuração das Atividades (product.learning_path)
Regra de Progressão engine.plan Configuração das Atividades (product.learning_path)
Questão Elegível activity.assessment Banco de Questões (content.base)

Convenção: Cross-domain parent é aceito quando:

  • O parent indica onde o conceito é configurado
  • O domain indica onde o conceito opera
  • A relação é semântica e estável (não acidental)

9. Status da Disciplina no Roteiro — parent corrigido

  • Antes: parent Disciplina (content.base)
  • Depois: parent Disciplina no Roteiro de Estudos (platform)

É um state_group da visão do Roteiro, não uma propriedade da entity Disciplina.

10. Preset de Produto movido para product

  • Antes: domain: product.commercial, parent Produto Comercial
  • Depois: domain: product, parent Template de Configuração

Justificativa: Preset configura a Trilha Pedagógica, não a oferta comercial. É uma regra que restringe campos de um Template de Configuração.

11. Roles dispersos — convenção aceita

Cada role vive no domínio onde atua:

Role Domain Justificativa
Aluno engine.onboarding Ciclo do Aluno começa no onboarding
Gestor Pedagógico platform Perfil de sistema na plataforma
Tutor product Recurso opcional do Produto
Conteudista content.base Role editorial da Base de Conteúdo

Mapa de Domínios Resultante

Domínio Subdomínios Escopo
(genérico/terms.yaml) — Metodologia, documentação, conceitos estruturais, rastreabilidade, versionamento
content content.base, content.base.bank_question, content.management, content.change Base de Conteúdo, gestão editorial, change tracking
product — Estrutura do Produto, Trilha Pedagógica (root), Tutoria, Presets
product.learning_path — Configuração da Trilha (etapas, montagem, validação, publicação)
product.commercial — Catálogo comercial, ofertas, campanhas, transações, pós-venda
engine engine.algorithm, engine.plan, engine.access, engine.session, engine.onboarding Motores, execução do estudo, acesso, sessões
activity activity.assessment, activity.formative, activity.productive Atividades-base, avaliações, formativas, produtivas
metrics — Classificação, desempenho, métricas, relatórios
platform — Plataforma HÉLICO, componentes técnicos, screens, roles de sistema

Consequências

  • Árvore genérica ganha 4 conceitos de rastreabilidade e versionamento, disponíveis para qualquer domínio
  • content perde 5 terms e consolida 2 subdomínios em 1
  • engine perde 2 terms de configuração (Bloco de Montagem, Tipo de Módulo) e ganha 1 (Histórico de Uso)
  • api renomeado para platform — 36 terms afetados
  • product ganha 1 term (Preset de Produto)
  • product.learning_path ganha 2 terms (Bloco de Montagem, Tipo de Módulo)
  • Convenções de cross-domain parent e roles dispersos documentadas para uso futuro
  • Requer atualização de referências em contratos JSON e código existente onde domain: api era usado

Histórico

Renumerado de ADR-905.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close