Alertas e Relatórios

Este módulo cobre as duas telas de observabilidade da frota — Alertas (regras que disparam eventos) e Relatórios (KPIs + gráficos sobre a telemetria coletada).

Alertas

Aberta em /alert-rules. O objetivo é transformar telemetria bruta em eventos acionáveis para o time de operação.

Tipos de regra suportados

Tipo	Trigger	Parâmetros
BATTERY_LOW	Bateria do device ≤ threshold	threshold (percentual, ex.: 20)
DEVICE_OFFLINE	Último checkin > threshold minutos	threshold (minutos, ex.: 30)
GEOFENCE_EXIT	Device saiu de uma geofence	geofenceId (opcional — vazio = qualquer geofence)

Como cada regra é avaliada

O motor de avaliação de regras processa suas regras a cada minuto:

1. Verifica todas as regras ativadas na sua organização

2. Para cada dispositivo, avalia se as condições foram atingidas (bateria atual, último checkin, eventos recentes de geofence)

3. Respeita o cooldown configurado — se a mesma regra já disparou para o mesmo device dentro do intervalo, ela é silenciada até o cooldown expirar

4. Ao disparar, uma nova notificação aparece no sino do header em tempo real

Configurações por regra

Campo	O que faz
name	Título visível na UI
type	BATTERY_LOW / DEVICE_OFFLINE / GEOFENCE_EXIT
threshold	Ponto de gatilho (contexto por tipo)
cooldownMinutes	Não redisparar para o mesmo device dentro desse intervalo (evita flood)
notifyUsers[]	IDs de usuários que recebem. Vazio = todos admins do tenant
enabled	Toggle rápido — desativa sem apagar

UI

• Aba Rules: tabela com search + sort + toggle switch de ativação + edit + delete

• Aba History: cronológico dos disparos com device, valor detectado, timestamp

Deduplicação

Cada disparo é registrado no histórico com regra + dispositivo + timestamp. O motor consulta esse histórico antes de disparar novamente, para evitar flood — se a mesma combinação foi acionada dentro do intervalo de cooldown, o disparo é suprimido.

Para regras de GEOFENCE_EXIT, o sistema garante ainda que cada evento único de saída seja processado apenas uma vez, mesmo em cenários de reprocessamento.

Entrega das notificações

Cada alerta disparado aparece imediatamente no sino do header do portal, para todos os usuários listados em notifyUsers (ou para todos os admins da organização, se o campo estiver vazio). O sino atualiza a cada poucos segundos e mostra:

• Título da regra

• Nome do dispositivo

• Valor detectado que estourou o limite

• Horário do disparo

Admins podem marcar como vista clicando na notificação. O histórico completo com todos os disparos (mesmo os já vistos) fica disponível na aba History da tela de Alertas.

Relatórios

Aberta na Home (/) do portal, para dar destaque.

Estrutura

• Filtro de data com presets 7/30/90 dias + range customizado

• 6 KPI cards: Total de dispositivos, Offline, Bateria baixa (≤20%), Dados móveis totais, Dados Wi-Fi totais, Chamadas

• Gráficos ApexCharts:

  • Consumo de dados no tempo (área empilhada: mobile + wifi)

  • Chamadas no tempo (barras)

  • Dispositivos ativos no tempo (área)

  • Distribuição de bateria (donut com 5 buckets: 0-20 / 21-40 / 41-60 / 61-80 / 81-100 + Unknown)

• Tabela de Top devices — toggle entre "por consumo de dados" e "por chamadas"

Buckets de agregação

Os gráficos podem ser agrupados por hora, dia, semana ou mês, dependendo do período selecionado.

Limites

• Faixa de datas máxima: 366 dias por consulta

• Faixa padrão: últimos 7 dias

• Métricas e buckets são validados na hora da consulta para evitar cargas excessivas na base

Export CSV

Cada card + tabela tem seu próprio botão CSV que baixa aquela seção específica:

• summary.csv — 10 linhas de KPI (Metric / Value)

• devices.csv — inventário completo com battery / online / lastSeen / model / OS

• data-usage-{bucket}.csv — timestamp + mobile MB + wifi MB

• calls-{bucket}.csv — timestamp + count + duration total

• status-{bucket}.csv — timestamp + active devices

• top-devices-{metric}.csv — deviceId + deviceName + colunas específicas por métrica

Export PDF

O botão Salvar como PDF aciona window.print(). Uma stylesheet @media print inline esconde:

• Sidebar

• Header (toolbar, alertas, user)

• Botões de export (.no-print)

O usuário escolhe "Salvar como PDF" no dialog do navegador. Zero dependências novas (não usa jsPDF ou html2canvas).

Combinação típica de Alertas + Relatórios

Fluxo operacional recomendado:

1. Alertas — cria regra DEVICE_OFFLINE ≥ 60 min e BATTERY_LOW ≤ 15% para todos os devices

2. Admin recebe notificações no sino em tempo real quando algo dispara

3. Relatórios — analista revisa semanalmente para spotting de tendências (aparelho X sempre offline aos sábados? bateria degradando faster?)

4. Ação — se pattern for observado, redistribui a policy (ex.: stayOnPluggedModes para setups sedentários) ou substitui hardware