ADR-04: Eventos para desacoplamento entre componentes
Status: Aceito Data: 2026-04-17
Contexto
O local_helico é um sistema onde fatos relevantes do domínio frequentemente geram reações em múltiplos pontos: atualização de estados, registro de histórico, notificações, sincronizações, reprocessamento. Exemplo: a conclusão de uma atividade pode afetar o progresso do bloco, do fluxo, do plano e de métricas — tudo ao mesmo tempo.
Se cada fluxo chamar diretamente todos os componentes afetados, o acoplamento cresce rapidamente e o caso de uso se torna um agregador de dependências laterais.
O EventDispatcher do middag é o mecanismo de eventos utilizado pelo HÉLICO.
Decisão
Eventos são o mecanismo preferencial para comunicação entre componentes que não precisam de acoplamento síncrono direto.
Regras de uso:
- Quando usar evento: o fato é relevante para o domínio, e as reações podem ocorrer de forma independente sem comprometer a consistência imediata do fluxo principal.
- Quando NÃO usar evento: a ação é parte indispensável da consistência do caso de uso — deve permanecer explícita no fluxo.
- Nomeação: eventos representam fatos já ocorridos (passado).
DisciplinaSincronizada, nãoSincronizarDisciplina. - Payload: o evento carrega os dados mínimos necessários para que os listeners atuem sem re-consultar o contexto completo.
- Listeners: cada listener tem responsabilidade única.
Eventos por domínio (exemplos representativos):
| Domínio | Eventos |
|---|---|
| Conteúdo | DisciplinaSincronizada, UnidadeProcessada, SnapshotGerado |
| Produto | TrilhaPublicada, PlanoCompilado, MatriculaCriada |
| Motor Pedagógico | BlocoConcluido, NivelClassificado, FluxoAvancado |
| Atividades | AtividadeConcluida, SimuladoSubmetido, SessaoIniciada |
| Métricas | MetricaCalculada, RelatorioGerado |
Políticas operacionais:
- Retry: listeners que falham devem ser reexecutáveis (idempotentes). Política de retry configurável por listener com backoff exponencial.
- Dead letter: eventos que falharem após todas as tentativas são registrados em dead letter para investigação manual.
- Ordering: eventos dentro de um mesmo agregado mantêm ordem causal. Eventos entre agregados diferentes não garantem ordem global.
Consequências
- Menor acoplamento entre fluxo principal e reações laterais.
- Novos comportamentos podem ser adicionados como listeners sem alterar o core.
- Políticas de retry e dead letter garantem resiliência sem perda silenciosa.
- Eventos não substituem dependências essenciais: se o fluxo precisa do resultado, a chamada deve ser direta.
- Rastreabilidade de eventos exige convenções de logging e monitoramento.
ADRs relacionados
- Depende de ADR-01 (separação de responsabilidades e fronteira com middag).
- Complementa ADR-02 (4 fases do ciclo): transições entre fases são candidatas naturais a eventos.
- Mecanismo principal para manter ADR-03 (abstração seletiva) sem criar dependências diretas entre pontos de variação.
Histórico
Renumerado de ADR-105.