Skip to content

ADR-01: Separação de responsabilidades e fronteira com middag

ADR-01: Separação de responsabilidades e fronteira com middag

Status: Aceito Data: 2026-04-17

Contexto

O local_helico é um plugin de domínio pedagógico construído sobre o local_middag e o Moodle. O local_middag é o framework-base que fornece patterns de orquestração — Command/Handlers, Job/Adhoc, EventDispatcher — usados por toda a aplicação.

O risco principal é que regras pedagógicas — o diferencial real do produto — fiquem diluídas em código de orquestração, persistência ou handlers operacionais, tornando o domínio difícil de localizar, testar e evoluir.

O middag é a camada de infraestrutura e orquestração usada pelo HÉLICO — não um sistema externo a ser isolado. A questão real não é “isolar do middag”, mas definir onde termina a regra pedagógica e onde começam os detalhes de persistência e coordenação técnica.

Decisão

Regra pedagógica e orquestração operacional devem ter responsabilidades distintas no código. A fronteira entre domínio e infraestrutura é definida em 4 camadas:

Camada Responsabilidade Relação com middag/Moodle
Domínio (regra pedagógica) Decisão, critério, política, cálculo Pode usar patterns do middag via interface (EventDispatcher, etc.). Não chama $DB, get_config() ou APIs do Moodle.
Aplicação (Command/Handlers) Orquestração via patterns middag Usa diretamente Command/Handlers, coordena fluxo
Infraestrutura (adapter, gateway, repository) Persistência, APIs externas Usa $DB, APIs Moodle, facades middag diretamente
Entrada (controller, external) Roteamento HTTP/API Estende api_controller do middag

Na prática:

  • Regra pedagógica é decisão de domínio: progressão, classificação, seleção de atividade, elegibilidade, critério de conclusão. Deve residir em componentes nomeados pela semântica do domínio (services de domínio, policies ou equivalentes).
  • Orquestração é coordenação de fluxo via patterns do middag: Command/Handlers leem contexto, validam pré-condições, invocam a regra, persistem resultados e disparam eventos via EventDispatcher.
  • Infraestrutura — persistência, APIs do Moodle, facades do local_middag, Job/Adhoc — não deve estruturar a decisão pedagógica, mas é o mecanismo legítimo de execução.

Regras práticas:

  • Models estendem item do middag — essa herança é aceita como decisão pragmática, não como acoplamento a combater.
  • Services de domínio recebem contexto já preparado — não acessam persistência diretamente.
  • Application services (Command/Handlers) coordenam a ponte entre domínio e infraestrutura.
  • DTOs continuam como mecanismo de transporte entre camadas.
  • A separação deve ser proporcional à complexidade. Não é necessário criar camada para tudo; é necessário que cada componente tenha motivo de mudança coerente com seu papel.

A fronteira real: regra pedagógica não depende de detalhes de persistência, mas pode usar patterns de orquestração do middag via interface.

Consequências

  • Regras pedagógicas ficam localizáveis, testáveis e reutilizáveis entre fluxos.
  • Regras pedagógicas testáveis com mocks dos patterns do middag.
  • Orquestração (Command/Handlers, EventDispatcher) pode mudar sem reescrever regra de domínio.
  • Código de domínio expressa intenção pedagógica; código de orquestração expressa coordenação técnica.
  • Mudanças em APIs do Moodle ou versões do middag afetam adapters e handlers, não regras de domínio.
  • Models herdam de item por pragmatismo — aceito e documentado.
  • Menor atrito com a realidade do código, sem pretensão de isolamento total.
  • Exige disciplina para distinguir regra relevante de detalhe operacional.

ADRs relacionados

  • Base para ADR-02 (ciclo de vida em 4 fases), ADR-03 (abstração seletiva e hierarquia de atividades) e ADR-04 (eventos para desacoplamento).
  • Informa ADR-10 (EAV próprio e critérios de persistência) sobre independência de persistência.

Histórico

Consolida ADR-101 e ADR-104.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close