erp-core/docs/02-fase-core-business/MGN-008-notifications/especificaciones/INDICE-ET-NOTIF.md

Indice de Especificaciones Tecnicas - MGN-008 Notifications

Identificacion

Campo	Valor
Modulo	MGN-008
Epic	Notifications
Total ET	3
Story Points	25
Fecha	2025-12-05

---

Especificaciones Tecnicas

ID	Titulo	RF Cubiertos	Estado
ET-NOTIF-database	Schema core_notifications	RF-001 a RF-004	Documentado
ET-NOTIF-backend	Servicios, WebSocket y API REST	RF-001 a RF-004	Documentado
ET-NOTIF-frontend	Componentes React + Socket.io	RF-001 a RF-004	Documentado

---

Resumen de Componentes

Database (ET-NOTIF-database)

Tabla	RF	Descripcion
notifications	RF-001	Notificaciones in-app para usuarios
email_templates	RF-002	Templates de email reutilizables
email_jobs	RF-002	Cola de trabajos de email
push_subscriptions	RF-003	Dispositivos registrados para push
push_jobs	RF-003	Cola de trabajos push
notification_preferences	RF-004	Preferencias por usuario y tipo

Total: 6 tablas

Funciones:

• send_notification() - Envio con aplicacion de preferencias
• mark_as_read() - Marcar notificaciones leidas
• get_unread_count() - Conteo por tipo
• cleanup_old_notifications() - Limpieza automatica
• cleanup_completed_jobs() - Limpieza de colas

Backend (ET-NOTIF-backend)

Servicio	Responsabilidad	RF
NotificationsService	CRUD in-app + WebSocket	RF-001
EmailService	Cola y envio de emails	RF-002
EmailTemplatesService	Gestion de templates	RF-002
PushService	Subscripciones y envio push	RF-003
PreferencesService	Preferencias de usuario	RF-004

Total: 18 endpoints REST + WebSocket

Componentes adicionales:

• NotificationsGateway (WebSocket)
• EmailProcessor (Bull job processor)
• PushProcessor (Bull job processor)

---

Matriz de Trazabilidad RF -> ET

RF	Database	Backend
RF-NOTIF-001	notifications	NotificationsService, NotificationsGateway
RF-NOTIF-002	email_templates, email_jobs	EmailService, EmailTemplatesService, EmailProcessor
RF-NOTIF-003	push_subscriptions, push_jobs	PushService, PushProcessor
RF-NOTIF-004	notification_preferences	PreferencesService

---

Arquitectura de Canales

+-------------------+
|   Notification    |
|     Service       |
+--------+----------+
         |
    +----+----+----+
    |    |    |    |
    v    v    v    v
+-----+ +---+ +----+
|In-App| |Email| |Push|
+--+--+ +--+--+ +--+--+
   |       |       |
   v       v       v
WebSocket  SMTP  VAPID
(Socket.io)(Node) (web-push)

Flujo de Envio

1. Crear notificacion -> NotificationsService.send()
2. Verificar preferencias -> PreferencesService.get()
3. Filtrar canales segun preferencias
4. In-App: Guardar + WebSocket emit
5. Email: Queue job con Bull (respeta frequencia)
6. Push: Queue job para cada subscripcion activa

---

Dependencias Tecnicas

Externas

• PostgreSQL 15+ (JSONB, arrays)
• Redis (Bull queues, Socket.io adapter)
• TypeORM 0.3+
• NestJS 10+
• Socket.io 4+
• Bull/BullMQ (Job queues)
• Nodemailer (SMTP)
• web-push (VAPID)
• Handlebars (Templates)

Internas

• core_tenants.tenants (RLS)
• core_users.users (Referencias)
• MGN-001 Auth (JWT para WebSocket)
• MGN-006 Settings (SMTP config)

---

Configuracion Requerida

Variables de Entorno

# SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user
SMTP_PASS=secret
SMTP_SECURE=false
EMAIL_FROM="App <noreply@example.com>"

# Push Notifications (VAPID)
VAPID_PUBLIC_KEY=BNxxx...
VAPID_PRIVATE_KEY=xxx...
PUSH_SUBJECT=mailto:admin@example.com

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

---

Service Worker (Push)

// public/sw.js
self.addEventListener('push', (event) => {
  const data = event.data.json();

  const options = {
    body: data.body,
    icon: data.icon || '/icon-192.png',
    badge: data.badge || '/badge.png',
    data: {
      url: data.actionUrl,
      ...data.data,
    },
  };

  event.waitUntil(
    self.registration.showNotification(data.title, options)
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();

  if (event.notification.data?.url) {
    event.waitUntil(
      clients.openWindow(event.notification.data.url)
    );
  }
});

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	Requirements-Analyst	Creacion inicial con 2 ET
1.1	2025-12-05	Requirements-Analyst	Agregado ET Frontend