erp-core/docs/02-fase-core-business/MGN-008-notifications/requerimientos/RF-NOTIF-001.md

RF-NOTIF-001: Notificaciones In-App

Identificacion

Campo	Valor
ID	RF-NOTIF-001
Modulo	MGN-008 Notifications
Titulo	Notificaciones In-App
Prioridad	P0 - Critica
Estado	Draft
Fecha	2025-12-05

---

Descripcion

El sistema debe permitir enviar y mostrar notificaciones dentro de la aplicacion, incluyendo alertas, mensajes del sistema, y notificaciones de actividad que los usuarios pueden ver en tiempo real.

---

Requisitos Funcionales

RF-NOTIF-001.1: Estructura de Notificacion

Campo	Tipo	Descripcion
id	UUID	Identificador unico
tenant_id	UUID	Tenant destino
user_id	UUID	Usuario destino
type	VARCHAR(50)	Tipo de notificacion
category	VARCHAR(50)	Categoria (info, warning, error, success)
title	VARCHAR(255)	Titulo corto
message	TEXT	Mensaje completo
data	JSONB	Datos adicionales (links, acciones)
is_read	BOOLEAN	Marcada como leida
read_at	TIMESTAMPTZ	Cuando se leyo
is_archived	BOOLEAN	Archivada
expires_at	TIMESTAMPTZ	Fecha de expiracion
created_at	TIMESTAMPTZ	Fecha de creacion

RF-NOTIF-001.2: Tipos de Notificacion

enum NotificationType {
  // Sistema
  SYSTEM_ALERT = 'system_alert',
  MAINTENANCE = 'maintenance',

  // Tareas
  TASK_ASSIGNED = 'task_assigned',
  TASK_COMPLETED = 'task_completed',
  TASK_DUE = 'task_due',

  // Aprobaciones
  APPROVAL_REQUESTED = 'approval_requested',
  APPROVAL_GRANTED = 'approval_granted',
  APPROVAL_REJECTED = 'approval_rejected',

  // Documentos
  DOCUMENT_SHARED = 'document_shared',
  DOCUMENT_COMMENT = 'document_comment',

  // Usuarios
  USER_MENTION = 'user_mention',
  TEAM_INVITE = 'team_invite',

  // Negocios
  ORDER_CREATED = 'order_created',
  PAYMENT_RECEIVED = 'payment_received',
  STOCK_LOW = 'stock_low'
}

RF-NOTIF-001.3: Categorias y Prioridades

Categoria	Color	Descripcion
info	Azul	Informativo
success	Verde	Accion exitosa
warning	Amarillo	Requiere atencion
error	Rojo	Error o problema

enum NotificationPriority {
  LOW = 'low',       // Puede esperar
  NORMAL = 'normal', // Mostrar en lista
  HIGH = 'high',     // Destacar en UI
  URGENT = 'urgent'  // Popup inmediato
}

RF-NOTIF-001.4: Acciones en Notificacion

Las notificaciones pueden incluir acciones:

interface NotificationAction {
  label: string;           // "Ver pedido", "Aprobar"
  type: 'link' | 'action'; // Navegar o ejecutar
  url?: string;            // Para links
  actionId?: string;       // Para acciones
  primary?: boolean;       // Destacar
}

// Ejemplo
{
  "type": "approval_requested",
  "title": "Aprobacion pendiente",
  "message": "Pedido #1234 requiere tu aprobacion",
  "data": {
    "entityType": "orders",
    "entityId": "uuid-order",
    "actions": [
      { "label": "Aprobar", "type": "action", "actionId": "approve", "primary": true },
      { "label": "Rechazar", "type": "action", "actionId": "reject" },
      { "label": "Ver pedido", "type": "link", "url": "/orders/uuid-order" }
    ]
  }
}

RF-NOTIF-001.5: Notificaciones en Tiempo Real

Usando WebSockets para entrega inmediata:

// Conexion WebSocket
ws://api.example.com/notifications?token=JWT

// Eventos
interface NotificationEvent {
  type: 'new' | 'read' | 'archived' | 'count_update';
  payload: Notification | { count: number };
}

RF-NOTIF-001.6: Agrupacion de Notificaciones

Notificaciones similares se agrupan:

// Si hay 5 comentarios en 1 hora en el mismo documento:
{
  "type": "document_comment",
  "title": "5 nuevos comentarios",
  "message": "En el documento 'Propuesta Q1'",
  "data": {
    "count": 5,
    "groupedIds": ["uuid1", "uuid2", ...]
  }
}

---

Operaciones

Listar Notificaciones

GET /api/v1/notifications?isRead=false&limit=20

Response:
{
  "data": [
    {
      "id": "uuid",
      "type": "task_assigned",
      "category": "info",
      "title": "Nueva tarea asignada",
      "message": "Te han asignado la tarea 'Revisar informe'",
      "isRead": false,
      "createdAt": "2025-12-05T10:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "unreadCount": 5
  }
}

Marcar como Leida

PUT /api/v1/notifications/:id/read

// O multiples:
PUT /api/v1/notifications/read
{
  "ids": ["uuid1", "uuid2"]
}

Marcar Todas como Leidas

PUT /api/v1/notifications/read-all

Obtener Contador

GET /api/v1/notifications/count

Response:
{
  "total": 50,
  "unread": 5,
  "byCategory": {
    "info": 3,
    "warning": 2
  }
}

Archivar Notificacion

PUT /api/v1/notifications/:id/archive

Ejecutar Accion

POST /api/v1/notifications/:id/actions/:actionId

// Ejecuta la accion asociada (aprobar, rechazar, etc.)

---

Reglas de Negocio

ID	Regla	Severidad
BR-001	Notificaciones expiran despues de 30 dias	Info
BR-002	Maximo 100 notificaciones no leidas	Info
BR-003	Notificaciones urgentes muestran popup	UX
BR-004	Agrupacion si > 3 del mismo tipo en 1h	UX
BR-005	WebSocket reconecta automaticamente	Reliability

---

Criterios de Aceptacion

• Crear y mostrar notificaciones in-app
• Entrega en tiempo real via WebSocket
• Marcar como leida individual y masivo
• Contador de no leidas en header
• Acciones ejecutables desde notificacion
• Agrupacion de notificaciones similares
• Expiracion automatica

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	Requirements-Analyst	Creacion inicial