workspace/projects/gamilit/docs/frontend/admin/components/ALERT-COMPONENTS-ARCHITECTURE.md

Arquitectura de Componentes de Alertas - Admin Portal

Version: 1.0.0 Fecha: 2025-12-18 Modulo: Admin Portal - Sistema de Alertas

---

ESTRUCTURA GENERAL

apps/frontend/src/apps/admin/
├── hooks/
│   └── useAlerts.ts              # Hook principal
├── components/alerts/
│   ├── alertUtils.ts             # Utilidades compartidas
│   ├── AlertsStats.tsx           # Cards de estadisticas
│   ├── AlertFilters.tsx          # Panel de filtros
│   ├── AlertsList.tsx            # Lista paginada
│   ├── AlertCard.tsx             # Card individual
│   ├── AlertDetailsModal.tsx     # Modal de detalles
│   ├── AcknowledgeAlertModal.tsx # Modal reconocer
│   └── ResolveAlertModal.tsx     # Modal resolver
└── pages/
    └── AdminAlertsPage.tsx       # Pagina principal

---

HOOK PRINCIPAL: useAlerts

Ubicacion: hooks/useAlerts.ts

Proposito

Gestion completa del ciclo de vida de alertas:

• Fetch con filtros y paginacion
• Estadisticas en tiempo real
• Acciones de gestion (acknowledge, resolve, suppress)

API Retornada

const {
  // Data
  alerts,
  stats,
  selectedAlert,

  // Estado
  isLoading,
  isLoadingStats,
  error,

  // Filtros & Paginacion
  filters,
  setFilters,
  pagination,

  // Acciones
  fetchAlerts,
  fetchStats,
  refreshAlerts,
  acknowledgeAlert,
  resolveAlert,
  suppressAlert,
  nextPage,
  prevPage,
  goToPage
} = useAlerts();

Pagination Object

interface Pagination {
  page: number;
  totalPages: number;
  totalItems: number;
  limit: number;
}

Validaciones de Acciones

Accion	Validacion
acknowledgeAlert	Nota opcional
resolveAlert	Nota requerida (min 10 chars)
suppressAlert	Sin validacion adicional

---

UTILITY MODULE: alertUtils.ts

Ubicacion: components/alerts/alertUtils.ts

Funciones Exportadas

getSeverityColor(severity) -> string

Retorna clases Tailwind con fondo solido para badges prominentes.

getSeverityColor('critical'); // 'bg-red-500 text-white'
getSeverityColor('high');     // 'bg-orange-500 text-white'
getSeverityColor('medium');   // 'bg-yellow-500 text-black'
getSeverityColor('low');      // 'bg-blue-500 text-white'

getSeverityColorWithBorder(severity) -> string

Retorna clases con fondo transparente + borde para badges sutiles.

getStatusColor(status) -> string

getStatusColor('open');         // Rojo con borde
getStatusColor('acknowledged'); // Naranja con borde
getStatusColor('resolved');     // Verde con borde
getStatusColor('suppressed');   // Gris con borde

getStatusTextColor(status) -> string

Solo colores de texto para etiquetas inline.

getSeverityLabel(severity) -> string

getSeverityLabel('critical'); // 'Critica'
getSeverityLabel('high');     // 'Alta'
getSeverityLabel('medium');   // 'Media'
getSeverityLabel('low');      // 'Baja'

getStatusLabel(status) -> string

getStatusLabel('open');         // 'Abierta'
getStatusLabel('acknowledged'); // 'Reconocida'
getStatusLabel('resolved');     // 'Resuelta'
getStatusLabel('suppressed');   // 'Suprimida'

formatAlertTimestamp(timestamp) -> string

Formato compacto para espacios limitados.

formatAlertTimestamp(fecha); // 'Hace 5m', 'Hace 2h', 'Hace 3d', 'dic 15'

formatAlertTimestampDetailed(timestamp) -> string

Formato detallado para mas informacion.

formatAlertTimestampDetailed(fecha); // 'Hace 5 min', 'Hace 2 horas'

---

COMPONENTES

1. AlertsStats

Ubicacion: components/alerts/AlertsStats.tsx

Props:

interface AlertsStatsProps {
  stats: AlertsStatsType | null;
  isLoading?: boolean;
}

Render:

• Grid de 4 cards con metricas:
  1. Alertas Abiertas (icono AlertTriangle)
  2. Reconocidas (icono AlertCircle)
  3. Resueltas (icono CheckCircle)
  4. Tiempo Promedio Resolucion (icono Clock)

---

2. AlertFilters

Ubicacion: components/alerts/AlertFilters.tsx

Props:

interface AlertFiltersProps {
  filters: AlertFiltersType;
  onFiltersChange: (filters: AlertFiltersType) => void;
  onRefresh: () => void;
  isLoading?: boolean;
}

Campos de Filtro:

Campo	Tipo	Opciones
Severidad	select	low, medium, high, critical
Estado	select	open, acknowledged, resolved, suppressed
Tipo Alerta	select	performance_degradation, high_error_rate, etc.
Desde	date	Date picker
Hasta	date	Date picker

---

3. AlertsList

Ubicacion: components/alerts/AlertsList.tsx

Props:

interface AlertsListProps {
  alerts: SystemAlert[];
  isLoading: boolean;
  pagination: Pagination;
  onAlertClick: (alert: SystemAlert) => void;
  onAcknowledge: (alert: SystemAlert) => void;
  onResolve: (alert: SystemAlert) => void;
  onSuppress: (alert: SystemAlert) => void;
  onNextPage: () => void;
  onPrevPage: () => void;
}

Estados:

• Loading: skeleton rows animados
• Empty: mensaje con icono
• Data: grid de AlertCard con paginacion

---

4. AlertCard

Ubicacion: components/alerts/AlertCard.tsx

Props:

interface AlertCardProps {
  alert: SystemAlert;
  onViewDetails: (alert: SystemAlert) => void;
  onAcknowledge: (alert: SystemAlert) => void;
  onResolve: (alert: SystemAlert) => void;
  onSuppress: (alert: SystemAlert) => void;
}

Secciones:

1. Badges (max 3): Severidad, Estado, Tipo
2. Contenido: Titulo, Descripcion (clamp 2 lineas)
3. Metadata: Usuarios afectados, Timestamp
4. Acciones: Botones dinamicos segun estado

Logica de Botones:

Estado	Detalles	Reconocer	Resolver	Suprimir
open	Si	Si	Si	Si
acknowledged	Si	No	Si	Si
resolved	Si	No	No	No
suppressed	Si	No	No	No

---

5. AlertDetailsModal

Ubicacion: components/alerts/AlertDetailsModal.tsx

Props:

interface AlertDetailsModalProps {
  alert: SystemAlert | null;
  isOpen: boolean;
  onClose: () => void;
}

Secciones:

1. Header con titulo y boton cerrar
2. Badges (severidad, estado)
3. Titulo y descripcion completa
4. Grid de informacion clave
5. Seccion Sistema (si aplica)
6. Seccion Gestion (si aplica)
7. JSON expandible (contexto, metricas)

---

6. AcknowledgeAlertModal

Ubicacion: components/alerts/AcknowledgeAlertModal.tsx

Props:

interface AcknowledgeAlertModalProps {
  alert: SystemAlert | null;
  isOpen: boolean;
  onClose: () => void;
  onConfirm: (note?: string) => Promise<void>;
}

Campos:

• Titulo de alerta (readonly)
• Textarea para nota (opcional)
• Botones: Cancelar, Reconocer

---

7. ResolveAlertModal

Ubicacion: components/alerts/ResolveAlertModal.tsx

Props:

interface ResolveAlertModalProps {
  alert: SystemAlert | null;
  isOpen: boolean;
  onClose: () => void;
  onConfirm: (note: string) => Promise<void>;
}

Validacion:

• Nota REQUERIDA
• Minimo 10 caracteres
• Contador en vivo: "5/10"
• Boton deshabilitado si < 10 chars

---

TIPOS PRINCIPALES

SystemAlert

interface SystemAlert {
  id: string;
  title: string;
  description?: string;
  severity: 'critical' | 'high' | 'medium' | 'low';
  status: 'open' | 'acknowledged' | 'resolved' | 'suppressed';
  alert_type: SystemAlertType;
  affected_users: number;
  triggered_at: string;
  source_system?: string;
  source_module?: string;
  error_code?: string;
  escalation_level?: number;
  acknowledged_by_name?: string;
  acknowledged_at?: string;
  acknowledgment_note?: string;
  resolved_by_name?: string;
  resolved_at?: string;
  resolution_note?: string;
  context_data?: Record<string, unknown>;
  metrics?: Record<string, unknown>;
}

AlertFilters

interface AlertFilters {
  severity?: SystemAlertSeverity;
  status?: SystemAlertStatus;
  alert_type?: SystemAlertType;
  date_from?: string;
  date_to?: string;
  page?: number;
  limit?: number;
}

AlertsStats

interface AlertsStats {
  open_alerts: number;
  acknowledged_alerts: number;
  resolved_alerts: number;
  avg_resolution_time_hours: number;
}

---

DIAGRAMA DE FLUJO

┌─────────────────────────────────────────────────────┐
│                AdminAlertsPage                       │
├─────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────┐   │
│  │              AlertsStats                     │   │
│  │  [Abiertas] [Reconocidas] [Resueltas] [Avg] │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │              AlertFilters                    │   │
│  │  [Severidad] [Estado] [Tipo] [Fechas]       │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │              AlertsList                      │   │
│  │  ┌─────────────┐ ┌─────────────┐            │   │
│  │  │ AlertCard   │ │ AlertCard   │            │   │
│  │  │ - Badges    │ │ - Badges    │            │   │
│  │  │ - Content   │ │ - Content   │            │   │
│  │  │ - Actions   │ │ - Actions   │            │   │
│  │  └─────────────┘ └─────────────┘            │   │
│  │  [< Prev]  1 2 3 4 5  [Next >]              │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────────────┐  ┌────────────────────┐      │
│  │ AlertDetailsModal│  │ AcknowledgeModal   │      │
│  └──────────────────┘  └────────────────────┘      │
│                        ┌────────────────────┐      │
│                        │ ResolveAlertModal  │      │
│                        └────────────────────┘      │
└─────────────────────────────────────────────────────┘

---

REFERENCIAS

• AdminAlertsPage.tsx - Implementacion de pagina
• useAlerts.ts - Hook de gestion
• adminTypes.ts - Tipos compartidos

---

Ultima actualizacion: 2025-12-18