Skip to content

ADR-04: Eventos para desacoplamento entre componentes

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ão SincronizarDisciplina.
  • 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close