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, parentBanco de Questões, aggregatediscipline - Depois:
domain: engine, parentHistó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, parentProduto Comercial - Depois:
domain: product, parentTemplate 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: apiera usado
Histórico
Renumerado de ADR-905.