Alert Handlers

Um alert handler transforma eventos de domínio em alertas. Cada handler implementa App\Contracts\AlertHandlerContract e é registrado por um módulo através do método alertHandlers() do contrato de módulo. Quando o core recebe um evento, ele percorre os handlers dos módulos habilitados para o site e, para cada um cujo triggerEvents() corresponde, cria (ou resolve) um alerta.

Registro

No módulo, declare os handlers e os tipos de alerta que eles produzem:

public function alertHandlers(): array
{
    return [PanicAlertHandler::class];
}

public function alertTypes(): array
{
    return ['panic'];
}

A interface AlertHandlerContract

Todos os métodos abaixo são obrigatórios (a interface não define padrões).

Identidade e vínculo com o módulo

Método	Retorno	Descrição
module()	string	Identifier do módulo dono do handler
feature()	?string	Sub-recurso do qual o handler depende, ou null se sempre disponível. Quando definido, o dispatch central checa ModuleRegistry::isFeatureEnabledForSite antes de invocar
type()	string	Tipo do alerta (deve constar em alertTypes() do módulo)
severity()	EventSeverity	Severidade do alerta — um valor do enum App\Enums\EventSeverity

Gatilho e resolução

Método	Retorno	Descrição
triggerEvents()	list<string>	Tipos de evento que criam o alerta
resolveEvents()	list<string>	Tipos de evento que resolvem o alerta
extractAlertData(DomainEventContract $event)	AlertData	Extrai do evento os dados para montar o alerta (objeto App\DataObjects\AlertData)
matchesForResolve(DomainEventContract $event, Alert $alert)	bool	Decide se um evento de resolução corresponde a um alerta ativo específico
autoResolveNote()	string	Nota registrada quando o alerta é auto-resolvido por evento
resolveCooldownTtl()	int	Janela (em segundos) para evitar reabertura imediata após resolução

Deduplicação e escalonamento

Método	Retorno	Descrição
dedupTtl()	?int	TTL de deduplicação em segundos; null desativa a dedup
escalatable()	bool	Se o alerta pode ser escalonado
escalationTimeout()	int	Tempo (segundos) sem resposta antes do escalonamento

Apresentação

Método	Retorno	Descrição
title(Alert $alert)	string	Título exibido para o alerta
description(Alert $alert)	string	Descrição/detalhe do alerta

Fluxo de vida de um alerta

1. Um evento de domínio (DomainEventContract) é emitido.
2. O core seleciona os handlers dos módulos habilitados para o site; se o handler declara feature(), o sub-recurso também precisa estar ativo.
3. Se o tipo do evento está em triggerEvents(), o handler usa extractAlertData() para criar o alerta — respeitando dedupTtl() para não duplicar.
4. title() e description() definem como o alerta aparece; severity() classifica a urgência.
5. Quando um evento de resolveEvents() chega, matchesForResolve() decide qual alerta ativo ele resolve; autoResolveNote() documenta a resolução e resolveCooldownTtl() evita reabertura imediata.
6. Se escalatable() e o alerta ficar sem resposta por escalationTimeout() segundos, o fluxo de escalonamento é acionado.

Próximos passos

• Contrato de Módulo — Como alertHandlers() e features() se encaixam
• Sobre Alertas — Como os alertas aparecem para o operador
• Report Handlers — O contrato irmão para relatórios