# 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

```typescript
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 |

```typescript
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:

```typescript
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:

```typescript
// 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:

```typescript
// 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

```typescript
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

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

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

### Marcar Todas como Leidas

```typescript
PUT /api/v1/notifications/read-all
```

### Obtener Contador

```typescript
GET /api/v1/notifications/count

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

### Archivar Notificacion

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

### Ejecutar Accion

```typescript
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 |