# US-MGN008-003: Gestionar Push Notifications

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN008-003 |
| **Modulo** | MGN-008 Notifications |
| **Sprint** | Sprint 5 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 5 |
| **Estado** | Ready |
| **RF Relacionado** | RF-NOTIF-003 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** recibir notificaciones push en mi navegador o dispositivo movil
**Para** estar alertado de eventos importantes incluso cuando no tengo la app abierta

---

## Descripcion

El sistema envia notificaciones push a navegadores web (Web Push con VAPID) y dispositivos moviles (FCM/APNs). Los usuarios pueden registrar multiples dispositivos y configurar preferencias de push.

### Contexto

- Web Push para navegadores
- FCM para Android
- APNs para iOS
- Sincronizacion con notificaciones in-app

---

## Criterios de Aceptacion

### Escenario 1: Registrar dispositivo web

```gherkin
Given un usuario autenticado en navegador
When acepta recibir notificaciones push
  And envia POST /api/v1/notifications/push/subscribe con subscription
Then el dispositivo se registra
  And retorna vapidPublicKey si es necesaria
```

### Escenario 2: Recibir push notification

```gherkin
Given un usuario con dispositivo registrado
  And evento que dispara notificacion
When el sistema envia push
Then el navegador/dispositivo muestra la notificacion
  And incluye titulo, cuerpo e icono
```

### Escenario 3: Click en push abre la app

```gherkin
Given push notification recibida
When usuario hace click en ella
Then el navegador abre la app en la URL especificada
  And la notificacion in-app correspondiente se marca como leida
```

### Escenario 4: Listar mis dispositivos

```gherkin
Given un usuario con multiples dispositivos registrados
When consulta GET /api/v1/notifications/push/devices
Then retorna lista de dispositivos:
  | id, deviceType, deviceName, isActive, lastUsedAt |
```

### Escenario 5: Desregistrar dispositivo

```gherkin
Given un dispositivo registrado
When envia DELETE /api/v1/notifications/push/subscribe/{id}
Then el dispositivo se elimina
  And ya no recibe notificaciones push
```

### Escenario 6: Respetar quiet hours

```gherkin
Given usuario con quiet hours 22:00-08:00
When evento ocurre a las 23:00
Then el push NO se envia
  And la notificacion in-app si se crea
```

### Escenario 7: No enviar push si app activa

```gherkin
Given usuario con app abierta (WebSocket conectado)
When llega una notificacion
Then solo se muestra in-app
  And NO se envia push
```

### Escenario 8: Enviar push a todos los dispositivos

```gherkin
Given usuario con 3 dispositivos registrados
When llega notificacion importante
Then se envia push a los 3 dispositivos
  And el primer click en cualquiera marca como leida
```

### Escenario 9: Token expirado se limpia

```gherkin
Given un dispositivo con token invalido
When el sistema intenta enviar push
  And recibe error de token invalido
Then el dispositivo se marca como inactivo
  And se notifica al usuario que reactive push
```

### Escenario 10: Broadcast a grupo de usuarios

```gherkin
Given administrador con permiso
When envia POST /api/v1/notifications/push/broadcast
  | tenantId | uuid |
  | title | "Mantenimiento programado" |
  | filter | { roles: ["admin"] } |
Then se envia push a todos los admins del tenant
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  MIS DISPOSITIVOS                                                 |
+------------------------------------------------------------------+

DISPOSITIVOS REGISTRADOS
+------------------------------------------------------------------+
| DISPOSITIVO          | TIPO  | ULTIMO USO        | ACCIONES      |
+------------------------------------------------------------------+
| Chrome en Windows    | 🌐 Web  | 2025-12-05 10:30  | [Desactivar]  |
| Firefox en MacOS     | 🌐 Web  | 2025-12-04 15:00  | [Desactivar]  |
| iPhone de Juan       | 📱 iOS  | 2025-12-05 08:00  | [Desactivar]  |
+------------------------------------------------------------------+

[+ Agregar este dispositivo]

CONFIGURACION DE PUSH
+------------------------------------------------------------------+
| ✓ Recibir notificaciones push                                    |
|                                                                   |
| Horas de silencio:                                                |
| [✓] Activar    Desde: [22:00]  Hasta: [08:00]                    |
|                                                                   |
| [=== Guardar ===]                                                |
+------------------------------------------------------------------+

Browser Push Permission:
+------------------------------------------------------------------+
|                                                                   |
|   [LOGO APP]                                                      |
|                                                                   |
|   Mi ERP quiere enviarte notificaciones                          |
|                                                                   |
|   Recibe alertas importantes incluso cuando                      |
|   no tienes la aplicacion abierta.                               |
|                                                                   |
|   [No, gracias]   [=== Permitir ===]                            |
|                                                                   |
+------------------------------------------------------------------+

Push Notification (Browser):
+------------------------------------------------------------------+
| [LOGO] Mi ERP                                                    |
| Nuevo pedido recibido                                             |
| Pedido #1234 por $1,500.00 de Juan Perez                         |
|                                        [Ver Pedido] [Descartar]  |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| POST | /notifications/push/subscribe | Registrar dispositivo |
| DELETE | /notifications/push/subscribe/:id | Desregistrar |
| GET | /notifications/push/devices | Mis dispositivos |
| POST | /notifications/push/send | Enviar push (admin) |
| POST | /notifications/push/broadcast | Broadcast (admin) |

### Web Push VAPID

```typescript
// Configuracion
interface VAPIDConfig {
  subject: 'mailto:admin@example.com';
  publicKey: 'BG...';
  privateKey: 'encrypted...';
}

// Subscription del browser
interface PushSubscription {
  endpoint: string;
  keys: {
    p256dh: string;
    auth: string;
  };
}
```

### Service Worker

```typescript
// sw.js
self.addEventListener('push', (event) => {
  const data = event.data.json();
  self.registration.showNotification(data.title, {
    body: data.body,
    icon: data.icon,
    data: { url: data.data.url }
  });
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  clients.openWindow(event.notification.data.url);
});
```

---

## Definicion de Done

- [ ] Web Push con VAPID funcional
- [ ] Service Worker implementado
- [ ] Registro/desregistro de dispositivos
- [ ] Sincronizacion con in-app
- [ ] Quiet hours respetadas
- [ ] Click abre URL correcta
- [ ] Limpieza de tokens invalidos
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla push_subscriptions | Dispositivos |
| US-MGN008-001 | Notificaciones in-app |
| web-push library | Para Web Push |
| Service Worker | En frontend |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Alertas criticas | Push inmediato |

---

## Historial

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