Frontend — Background Jobs

Documentacion retrospectiva — Generada a partir del codigo implementado en feature/background-jobs-core (bautista-app).

---

Tabla de Contenidos

• Estrategia de Actualizacion en Tiempo Real
• Polling de Notificaciones
• Cadena de Despacho de Acciones (4 Tiers)
• Hooks Principales
• Componentes
• Context Providers
• Estructura de Archivos

---

Estrategia de Actualizacion en Tiempo Real

El frontend utiliza HTTP polling (no SSE) para consultar el estado de los jobs.

Razon: SSE esta bloqueado por restricciones de autenticacion cross-domain — EventSource no soporta headers custom (Authorization). Ver ADR-003.

Implementacion:

• TanStack Query con refetchInterval: 2000 (2 segundos)
• El polling se detiene automaticamente cuando el job llega a estado terminal (completed o failed)
• Se pausa cuando la tab esta en segundo plano (refetchIntervalInBackground: false)

useQuery({
  queryKey: ['job', jobId],
  queryFn: () => api.getJobStatus(jobId),
  refetchInterval: (query) =>
    query.state.data?.status === 'completed' || query.state.data?.status === 'failed'
      ? false
      : 2000,
})

---

Polling de Notificaciones

Las notificaciones no leidas se consultan periodicamente via GET /backend/jobs/notifications.

• Intervalo: 30 segundos
• Pausa automatica: Cuando la tab esta en segundo plano (document.hidden)
• Implementacion: JobNotificationsContext maneja el ciclo de vida del polling y expone las notificaciones al resto de la app

---

Cadena de Despacho de Acciones (4 Tiers)

Cuando un job completa (o falla), el frontend ejecuta acciones en cascada segun prioridad:

Tier	Mecanismo	Descripcion	Caso de uso
1	JobCallbackRegistry	Callback one-shot registrado por la vista que despachó el job	Vista sigue montada, quiere manejar el resultado directamente
2	JobActionRegistry	Accion basada en job_type, registrada globalmente	Accion estandar para un tipo de job (ej: invalidar queries de ventas)
2.5	Navegacion con notif_id	Navega a la vista correspondiente con ?notif_id={id} en la URL	La vista puede reaccionar al parametro para mostrar resultados
3	sessionStorage	Almacena el resultado del job para que la vista lo consuma al montar	Fallback cuando la vista no esta montada y no hay accion registrada

Flujo de decision:

1. Si existe callback en JobCallbackRegistry para job_id → ejecutar y salir
2. Si existe accion en JobActionRegistry para job_type → ejecutar
3. Navegar con ?notif_id si hay URL de destino configurada
4. Guardar en sessionStorage como fallback

---

Hooks Principales

Ubicacion: ts/core/hooks/

Hook	Proposito
useBackgroundJob	Despachar un job y trackear su estado con polling. Encapsula POST + polling de estado.
useJobStream	Polling de estado de un job especifico (GET /backend/jobs/{id}). Usado por useBackgroundJob.
useJobSession	Leer/escribir resultado de job en sessionStorage (Tier 3 de la cadena de despacho).
useJobActionRegistration	Registrar una accion de Tier 2 en JobActionRegistry para un tipo de job.

---

Componentes

Ubicacion: ts/core/components/

Componente	Descripcion
notifications/JobNotificationBell	Campana de notificaciones con badge. Requiere estar dentro del provider JobNotificationsContext.
notifications/JobNotificationBellStandalone	Version standalone que incluye su propio provider. Usada en el layout global.
JobProgressBar.tsx	Barra de progreso para jobs en ejecucion. Recibe progress (0-100) y status.

---

Context Providers

Ubicacion: ts/core/context/

Context	Proposito
JobNotificationsContext	Polling de notificaciones (30s), estado de notificaciones no leidas, marca como leida. Provee datos a JobNotificationBell.
ModoContext	Modo actual (oficial/prueba). Afecta el scope de los jobs despachados.

---

Estructura de Archivos

ts/core/
├── types/              # Tipos TypeScript: BackgroundJob, JobNotification, etc.
├── hooks/
│   ├── useBackgroundJob.ts
│   ├── useJobStream.ts
│   ├── useJobSession.ts
│   └── useJobActionRegistration.ts
├── jobs/
│   ├── JobCallbackRegistry.ts    # Tier 1: callbacks one-shot por job_id
│   └── JobActionRegistry.ts      # Tier 2: acciones por job_type
├── context/
│   ├── JobNotificationsContext.tsx
│   └── ModoContext.tsx
└── components/
    ├── notifications/
    │   ├── JobNotificationBell.tsx
    │   └── JobNotificationBellStandalone.tsx
    └── JobProgressBar.tsx

---

Ultima verificacion contra codigo: 2026-03-11 (feature/background-jobs-core).