ADR-20: Pipeline terms → LinkML → PHP
Status: Aceito Data: 2026-04-17
Contexto
O plugin local_helico herda o pipeline de geração de código do framework local_middag:
terms.yaml → LinkML → PHP (via build_extensions). Até agora, os termos do domínio
Conteúdo (terms-conteudo.yaml) estavam no formato antigo, sem alinhamento com o schema
centralizado em local_middag (terms.schema.yaml). O código PHP existente em
classes/extensions/content/ foi escrito manualmente, com TYPE constants usando prefixo
helico_ e sem correspondência formal com o catálogo de termos.
A adoção do pipeline exige decisões sobre prefixo de classe, organização de subdomains, convenção de idioma e processo de habilitação da geração.
Decisão
1. class_prefix: false
O gerador produz TYPE = identifier direto, sem prefixo helico_. Justificativa:
o ADR-10 estabeleceu EAV próprio em local_helico (helico_items/helico_itemmeta),
eliminando a necessidade de prefixo para desambiguação com middag.
A migração dos TYPE constants existentes (helico_disciplina → discipline, etc.)
será feita incrementalmente conforme cada term for validado e materializado.
2. Subdomains do domínio Content
O domínio content é subdividido em três bounded contexts:
| Subdomain | Slug | Dir | Escopo |
|---|---|---|---|
| Base de Conteúdo | content.base |
content/base |
Modelagem: Disciplina, Unidade, Material Didático, questões, tópicos |
| 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: Registro de Alteração, Relatório, Resolução de Conflito |
3. Convenção de idioma
| Campo | Idioma | Exemplo |
|---|---|---|
term (nome canônico) |
PT-BR | “Disciplina” |
domain (slug) |
EN | content.base |
identifier (slug técnico) |
EN | discipline |
aggregate (pasta) |
EN | discipline |
| Diretórios, classes, métodos PHP | EN snake_case | discipline_service |
| TYPE constant | EN (= identifier) | discipline |
3.1 Regra de simplicidade para identifiers
Identifiers devem ser curtos e claros, priorizando máximo 1 underscore:
- Evitar palavras acadêmicas que não ajudam no entendimento (
pedagogical,didactic). - Omitir o contexto do domain/aggregate/parent — o identifier é resolvido dentro dele.
- Usar prefixos de família para artefatos agrupados (ex:
file_word,file_markdown,file_pdf).
| Antes | Depois | Razão |
|---|---|---|
pedagogical_change_record |
change_record |
“pedagogical” redundante no contexto content.change |
discipline_wordfile |
file_word |
prefixo de família file_*, sem repetir parent |
unit_general_info |
unit_info |
“general” redundante |
content_topic |
topic |
“content” é o domain |
didactic_material |
material |
“didactic” redundante |
Exceções aceitas: file_word_autosync, file_word_sync (2 underscores) — o prefixo
file_word_ é a família do command, não redundância de contexto.
3.2 Vocabulário de definições (short/long) vs tipo técnico
Os campos short e long dos termos usam vocabulário validado com equipes não-técnicas
(pedagógica, editorial, comercial). Palavras como “Processo” em definições de termos cujo
tipo técnico é process_command são intencionais — refletem como as equipes entendem e
referenciam o conceito, não o artefato PHP que será gerado.
Regra: o type orienta o código; o short/long orienta pessoas. Não alinhar
forçosamente a linguagem das definições ao tipo técnico.
4. materialize: false como default
Todos os termos com tipo materializável iniciam com materialize: false. A habilitação
é incremental, após validação individual que inclui:
- Classificação como ENTITY (registro EAV), ATTRIBUTE (metadata) ou VALUE_OBJECT (transiente).
- Definição de attributes no LinkML MANUAL block.
- Verificação via
build_extensions check. - Aprovação →
materialize: true→build_extensions build.
5. Faixas de numeração de ADRs
| Faixa | Escopo |
|---|---|
| 01–09 | Princípios Arquiteturais |
| 10–19 | Persistência e Infraestrutura |
| 20–29 | Pipeline, Tooling e Convenções |
| 30–39 | Domínio Content |
| 40–49 | Domínios futuros (product, activity, engine, metrics, platform) |
Consequências
- Pipeline terms→LinkML→PHP formalmente adotado para
local_helico. - Geração incremental controlada: nenhum artefato gerado antes de validação.
- Subdomains refletem separação funcional real do conteúdo pedagógico.
- Identificadores em EN eliminam ambiguidade entre vocabulário pedagógico e código.
- Faixas de ADR permitem crescimento organizado por domínio.
- Migração de TYPE constants existentes (ex:
helico_disciplina→discipline) requer cuidado com dados no EAV. - Dois conjuntos de termos coexistem temporariamente: termos validados (materialize: true) e pendentes (materialize: false).
- Subdomains em EN no slug (
content.management) divergem do termo em PT-BR (“Gestão e Publicação de Conteúdo”) — aceito como trade-off de consistência técnica.
ADRs relacionados
- ADR-10 — Persistência EAV e critérios de uso — base para
class_prefix: false. - ADR-30 — Domínio Content — materialização e contratos das entities do content.
Histórico
Renumerado de ADR-901. Faixas de numeração atualizadas de 100-999 para 01-99.