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
itemdo 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
itempor 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.