Skip to content

ADR-20: Pipeline terms → LinkML → PHP

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:

  1. Classificação como ENTITY (registro EAV), ATTRIBUTE (metadata) ou VALUE_OBJECT (transiente).
  2. Definição de attributes no LinkML MANUAL block.
  3. Verificação via build_extensions check.
  4. 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close