# RF-NOTIF-003: Push Notifications

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-NOTIF-003 |
| **Modulo** | MGN-008 Notifications |
| **Titulo** | Push Notifications |
| **Prioridad** | P1 - Alta |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe soportar notificaciones push para navegadores web y dispositivos moviles, permitiendo alertar a usuarios incluso cuando no tienen la aplicacion abierta.

---

## Requisitos Funcionales

### RF-NOTIF-003.1: Registro de Dispositivos

```typescript
interface PushSubscription {
  id: UUID;
  user_id: UUID;
  device_type: 'web' | 'android' | 'ios';
  device_name: string;          // "Chrome en Windows"
  push_token: TEXT;             // Token del dispositivo
  endpoint: TEXT;               // Para Web Push
  keys: JSONB;                  // p256dh, auth para Web Push
  is_active: boolean;
  last_used_at: TIMESTAMPTZ;
  created_at: TIMESTAMPTZ;
}
```

### RF-NOTIF-003.2: Web Push (PWA)

Para navegadores web usando VAPID:

```typescript
// Configuracion
interface WebPushConfig {
  vapidPublicKey: string;
  vapidPrivateKey: string;  // Encriptado
  subject: string;          // mailto:admin@example.com
}

// Subscription del navegador
interface WebPushSubscription {
  endpoint: string;
  keys: {
    p256dh: string;
    auth: string;
  };
}
```

### RF-NOTIF-003.3: Estructura de Push Notification

```typescript
interface PushNotification {
  title: string;           // Max 50 chars
  body: string;            // Max 200 chars
  icon?: string;           // URL del icono
  badge?: string;          // Badge para mobile
  image?: string;          // Imagen grande
  tag?: string;            // Para agrupar
  data?: {
    url: string;           // URL al hacer click
    notificationId: UUID;
    entityType?: string;
    entityId?: UUID;
  };
  actions?: {
    action: string;
    title: string;
    icon?: string;
  }[];
  requireInteraction?: boolean;  // No cerrar automaticamente
  silent?: boolean;              // Sin sonido
  timestamp?: number;            // Timestamp del evento
}
```

### RF-NOTIF-003.4: Proveedores de Push

| Plataforma | Proveedor | Configuracion |
|------------|-----------|---------------|
| Web | Web Push (VAPID) | Claves VAPID |
| Android | Firebase Cloud Messaging | Server Key |
| iOS | APNs | Certificado + Key ID |

### RF-NOTIF-003.5: Sincronizacion con In-App

- Push notification crea/actualiza notificacion in-app
- Al hacer click en push, abre la app y marca como leida
- Si la app esta abierta, solo muestra in-app (no push)

### RF-NOTIF-003.6: Preferencias de Push

```typescript
interface PushPreferences {
  enabled: boolean;
  quietHours: {
    enabled: boolean;
    start: string;  // "22:00"
    end: string;    // "08:00"
  };
  allowedTypes: NotificationType[];
  devices: {
    deviceId: UUID;
    enabled: boolean;
  }[];
}
```

---

## Operaciones

### Registrar Dispositivo (Web)

```typescript
POST /api/v1/notifications/push/subscribe
{
  "deviceType": "web",
  "deviceName": "Chrome en Windows",
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/...",
    "keys": {
      "p256dh": "...",
      "auth": "..."
    }
  }
}

Response:
{
  "subscriptionId": "uuid",
  "vapidPublicKey": "..."
}
```

### Desregistrar Dispositivo

```typescript
DELETE /api/v1/notifications/push/subscribe/:subscriptionId
```

### Listar Dispositivos

```typescript
GET /api/v1/notifications/push/devices

Response:
{
  "devices": [
    {
      "id": "uuid",
      "deviceType": "web",
      "deviceName": "Chrome en Windows",
      "isActive": true,
      "lastUsedAt": "2025-12-05T10:00:00Z"
    }
  ]
}
```

### Enviar Push (Admin/Sistema)

```typescript
POST /api/v1/notifications/push/send
{
  "userId": "uuid",
  "title": "Nuevo pedido",
  "body": "Se ha creado el pedido #1234",
  "data": {
    "url": "/orders/uuid-order"
  }
}
```

### Enviar Push Masivo

```typescript
POST /api/v1/notifications/push/broadcast
{
  "tenantId": "uuid",
  "title": "Mantenimiento programado",
  "body": "El sistema estara en mantenimiento manana a las 22:00",
  "filter": {
    "roles": ["admin", "manager"]
  }
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Respetar quiet hours del usuario | UX |
| BR-002 | Max 1 push por minuto por tipo | UX |
| BR-003 | Token expirado se elimina automaticamente | Reliability |
| BR-004 | No enviar push si app esta activa | UX |
| BR-005 | Click en push marca como leida | UX |

---

## Criterios de Aceptacion

- [ ] Web Push con VAPID funcional
- [ ] Registro/desregistro de dispositivos
- [ ] Sincronizacion con notificaciones in-app
- [ ] Quiet hours respetadas
- [ ] Click abre la app en la URL correcta
- [ ] Dispositivos inactivos se limpian

---

## Historial

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