Pular para conteúdo

Glossário do Framework

Este glossário estabelece a linguagem ubíqua do local_middag. Ter clareza sobre esses termos é fundamental para localizar a camada correta de uma implementação e respeitar os contratos arquiteturais.

O que é

Uma coleção de definições técnicas e conceituais que padronizam o vocabulário entre desenvolvedores do core, builders de extensions e integradores terceiros.

Por que existe

Para evitar ambiguidade em conceitos que possuem nomes semelhantes em outros frameworks (como Signal vs Evento Moodle) e para garantir que cada componente seja nomeado conforme sua responsabilidade técnica e zona de consumo.

Termos Canônicos

Adapter

  • Definição: Componente que isola o framework das APIs procedurais e globais do Moodle.
  • Aonde vive: classes/framework/support/moodle/
  • Relação: Atua como a fronteira de integração com o ecossistema Moodle.

Audit

  • Definição: Registro persistido e imutável que responde "quem fez o quê, quando e onde".
  • Aonde vive: classes/framework/application/service/audit/
  • Relação: É gerado a partir de um Signal e pode conter referências a uma Revision.

Command

  • Definição: Unidade de trabalho independente e serializável que encapsula a intenção de uma ação.
  • Aonde vive: classes/framework/application/command/
  • Relação: Sua execução é governada e rastreada por um Job.

Contract

  • Definição: Interface do PHP que define um papel arquitetural com propósito de variação, substituição ou DI.
  • Aonde vive: classes/framework/contract/
  • Relação: Quando marcado com @api, torna-se parte da API pública estável consumida via Facade.

Decorator

  • Definição: Padrão de design usado para anexar comportamentos transversais (como cache ou auditoria) sem alterar a classe base.
  • Aonde vive: classes/framework/infrastructure/persistence/repository/decorator/
  • Relação: Geralmente envolve um Repository para adicionar lógica de persistência extra.

Dispatcher

  • Definição: O motor central responsável por publicar signals e gerenciar listeners.
  • Aonde vive: classes/framework/kernel/dispatcher/
  • Relação: Publica as ocorrências que o framework chama de Signal.

Extension

  • Definição: Módulo desacoplado que implementa funcionalidades de negócio integradas ao lifecycle do framework.
  • Aonde vive: classes/extensions/
  • Relação: É descoberta e inicializada pelo Kernel.

Facade

  • Definição: Ponto de entrada estático e estável que blinda consumidores externos da complexidade do core.
  • Aonde vive: classes/facade/
  • Relação: Delega chamadas para serviços registrados no Container via Contracts @api.

Filter

  • Definição: Gatilho síncrono usado exclusivamente para transformar ou interceptar valores em um fluxo.
  • Aonde vive: classes/framework/application/service/filter/
  • Relação: Diferente do Signal, o Filter sempre espera um retorno modificado.

Hook

  • Definição: Projeção pública de uma ocorrência interna, seguindo a nomenclatura canônica middag/nome_do_hook.
  • Aonde vive: Registrado via Extension ou Kernel.
  • Relação: É a forma secundária (ergonômica) de reagir a um Signal.

Item

  • Definição: A unidade fundamental de persistência flexível (EAV) do framework.
  • Aonde vive: classes/framework/domain/item/
  • Relação: Possui metadados dinâmicos e é a fonte de verdade para Revisions.

Job

  • Definição: Registro de governança que rastreia o status e as tentativas de execução de um trabalho assíncrono.
  • Aonde vive: classes/framework/infrastructure/persistence/repository/job_repository
  • Relação: Governa a execução de um Command.

Kernel

  • Definição: O componente central que coordena o bootstrap, o container de DI e o lifecycle das extensions.
  • Aonde vive: classes/framework/kernel/
  • Relação: Inicializa o Dispatcher e resolve as dependências via Container.

Repository

  • Definição: Fronteira de persistência que isola o domínio do acesso direto ao banco de dados SQL.
  • Aonde vive: classes/framework/infrastructure/persistence/repository/
  • Relação: Gerencia a recuperação e persistência de Items, Revisions e Audits.

Revision

  • Definição: Snapshot imutável do estado de um Item em um ponto específico do tempo.
  • Aonde vive: classes/framework/infrastructure/persistence/repository/revision_repository
  • Relação: Toda Revision pertence obrigatoriamente a um Item.

Schedule

  • Definição: Declaração de um gatilho temporal periódico para execução de tarefas.
  • Aonde vive: classes/framework/application/schedule/
  • Relação: Dispara um Command em intervalos pré-definidos.

Signal

  • Definição: Ocorrência tipada e interna que sinaliza que algo aconteceu no sistema.
  • Aonde vive: Publicado via middag::dispatch().
  • Relação: É a fonte primária para reatividade, Auditoria e geração de Hooks.

O que não é

  • Signal não é Evento Moodle: Signals são internos do framework e desacoplados; Eventos Moodle são da plataforma.
  • Audit não é Revision: Audit diz quem fez; Revision diz como o dado ficou.
  • Facade não é Service: Facade é uma porta; o Service é quem executa a lógica.

Referências