Padrão Arquitetural: Marcadores Canônicos de Avisos Críticos

O ecossistema implementa o padrão de Marcadores Canônicos de Avisos Críticos para guiar o operador até a raiz de incidentes operacionais de severidade estrita CRITICAL (ex.: falhas de comunicação, instâncias desconectadas).

1. Princípios Fundamentais

  1. Severidade Estrita: Apenas incidentes com severity = 'CRITICAL' ativam marcadores visuais no cabeçalho ou nas listas de navegação. Alertas WARNING e INFO são mantidos restritos aos feeds informativos.

  2. Máquina de Decisão Hierárquica (ContextController):

    • Alertas com scopeType = 'organization' (locationId = null): sinalizam o seletor de organização quando o operador estiver em outra organização; quando o operador já estiver na organização afetada, o seletor de unidade permanece completamente limpo, ativando diretamente os marcadores de destino interno (Home e Configurações).

    • Alertas com scopeType = 'location' (locationId != null): sinalizam a organização quando fora do contexto corporativo; sinalizam a unidade (btn-tenant-pill) quando dentro da organização, mas em filial distinta; e limpam o header quando o contexto estiver perfeitamente alinhado com a filial afetada.

  3. Idempotência Visual: Cada botão, card ou item de lista renderiza no máximo um único indicador visual (CriticalAlertDot), independentemente da quantidade de notificações ativas associadas àquele escopo.

2. Arquitetura de Sincronização e Autoridade de Dados

Para evitar condições de corrida (race conditions) e divergência de estado (state drift):

  • BFF como Fonte Única de Verdade: O endpoint /api/notifications/markers é a autoridade canônica que filtra severidade, status ativo e remove dispensas registradas pelo usuário (connect.user_notification_dismissals).

  • Deduplicação de Rollups Organizacionais: Notificações de agregação com scope_type = 'organization' e location_id = null são suprimidas no BFF caso existam incidentes atômicos ativos de filial (scope_type = 'location') para o mesmo evento e organização. Isso preserva a precisão da hierarquia e evita que alertas locais vazem indevidamente para outras unidades.

  • Segurança e RLS Estrito: A consulta no BFF é executada utilizando o cliente autenticado useServerSupabase(event) (JWT do usuário). É vedado o uso de service_role no caminho de leitura dos marcadores.

  • Invalidação Reativa: O Supabase Realtime não calcula estado no frontend; atua exclusivamente como trigger leve de invalidação com debounce (150ms), solicitando refetch limpo ao BFF.

  • Dispensa Otimista: Ao acionar a dispensa de um alerta, o composable useCriticalAlertMarkers remove o registro localmente de forma imediata antes da reconciliação com o servidor, eliminando atrasos perceptíveis.

3. Acessibilidade e Design Canônico

  • Componente CriticalAlertDot.vue:

  • Renderiza elemento com aria-hidden="true" e pointer-events: none;.

  • Não polui tecnologias assistivas com anúncios repetitivos de role="status". A semântica acessível reside no aria-label do elemento pai interativo (botão ou link).

  • Ancoragem visual adaptativa na borda superior direita dos componentes (top: -3px; right: -3px; z-index: 10;) com anel de contraste contra o fundo circundante.

  • Variantes canônicas:

    • default: Alinhado inline flexível para textos e cabeçalhos de popover.

    • on-pill: Ancorado na borda superior direita de seletores contextuais arredondados (btn-tenant-pill, btn-org-opaque).

    • on-card: Ancorado na borda superior direita de cards principais (HomeCardLinkItem).

    • on-item: Ancorado na borda superior direita de itens de navegação (categoria de configurações e subopções).

    • on-icon: Ancorado sobre cantos de ícones em modo compacto e no rodapé da barra lateral (BaseSidebar).

4. Sinalização em Cascata na Navegação

Quando há um incidente crítico em uma filial (ex.: WhatsApp desconectado em Alô Baterias Ceilândia): 1. Se o operador estiver em outra filial (Atacadão Santo Amaro): * O ponto vermelho é exibido na borda superior direita do botão seletor de filial (.btn-tenant-pill). * No menu popover do seletor, o ponto é exibido ao lado do item da filial afetada (Alô Baterias Ceilândia). * O card de Configurações, a barra lateral e os menus internos permanecem completamente limpos. 2. Se o operador estiver alinhado com a filial afetada (Alô Baterias Ceilândia): * O seletor de unidade fica limpo. * O card "Configurações" na Home exibe o ponto vermelho no canto superior direito. * O ícone de "Configurações" no rodapé da Sidebar principal exibe o ponto vermelho. * Na página de Configurações, a categoria "Integrações" exibe o ponto vermelho. * Dentro da categoria, o subitem "WhatsApp" exibe o ponto vermelho no canto superior direito.