# US-MGN008-001: Gestionar Notificaciones In-App

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN008-001 |
| **Modulo** | MGN-008 Notifications |
| **Sprint** | Sprint 5 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-NOTIF-001 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** recibir notificaciones dentro de la aplicacion en tiempo real
**Para** estar informado de eventos importantes sin salir de mi flujo de trabajo

---

## Descripcion

El sistema muestra notificaciones in-app en tiempo real usando WebSockets. Los usuarios pueden ver, marcar como leidas, archivar y ejecutar acciones desde las notificaciones. Soporta diferentes tipos, categorias y prioridades.

### Contexto

- Entrega en tiempo real via WebSocket
- Diferentes tipos y categorias
- Acciones ejecutables desde notificacion
- Agrupacion de notificaciones similares

---

## Criterios de Aceptacion

### Escenario 1: Recibir notificacion en tiempo real

```gherkin
Given un usuario con sesion activa
  And conectado al WebSocket de notificaciones
When el sistema envia una notificacion a ese usuario
Then la notificacion aparece instantaneamente en la UI
  And el contador de no leidas se incrementa
  And se muestra toast/popup segun prioridad
```

### Escenario 2: Listar mis notificaciones

```gherkin
Given un usuario autenticado
When accede a GET /api/v1/notifications
Then el sistema responde con status 200
  And retorna lista de notificaciones ordenadas por fecha desc
  And incluye unreadCount en la respuesta
```

### Escenario 3: Filtrar por estado de lectura

```gherkin
Given un usuario con notificaciones leidas y no leidas
When consulta GET /api/v1/notifications?isRead=false
Then retorna solo las notificaciones no leidas
```

### Escenario 4: Marcar como leida

```gherkin
Given una notificacion no leida
When envia PUT /api/v1/notifications/{id}/read
Then la notificacion se marca como leida
  And se actualiza read_at
  And el contador disminuye
```

### Escenario 5: Marcar todas como leidas

```gherkin
Given multiples notificaciones no leidas
When envia PUT /api/v1/notifications/read-all
Then todas las notificaciones se marcan como leidas
  And el contador se resetea a 0
```

### Escenario 6: Ejecutar accion desde notificacion

```gherkin
Given notificacion de tipo "approval_requested"
  And contiene accion "approve"
When envia POST /api/v1/notifications/{id}/actions/approve
Then la accion se ejecuta (aprueba la solicitud)
  And la notificacion se marca como leida
  And se muestra mensaje de confirmacion
```

### Escenario 7: Obtener contador de no leidas

```gherkin
Given un usuario con notificaciones
When consulta GET /api/v1/notifications/count
Then retorna:
  | total | 50 |
  | unread | 5 |
  | byCategory | { info: 3, warning: 2 } |
```

### Escenario 8: Agrupacion de notificaciones similares

```gherkin
Given 5 notificaciones de tipo "document_comment" para el mismo documento en 1 hora
When se muestran al usuario
Then se agrupan en una sola notificacion:
  | title | "5 nuevos comentarios" |
  | message | "En el documento 'Propuesta Q1'" |
```

### Escenario 9: Archivar notificacion

```gherkin
Given una notificacion visible
When envia PUT /api/v1/notifications/{id}/archive
Then la notificacion se archiva
  And no aparece en la lista normal
  And sigue accesible con filtro isArchived=true
```

### Escenario 10: Notificacion urgente muestra popup

```gherkin
Given notificacion con priority = "urgent"
When llega al usuario
Then se muestra popup modal que requiere interaccion
  And no desaparece automaticamente
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  HEADER                                        [🔔 5] [Usuario v] |
+------------------------------------------------------------------+

Panel de Notificaciones (dropdown):
+------------------------------------------------------------------+
|  NOTIFICACIONES                              [Marcar todas leidas]|
+------------------------------------------------------------------+
| 🔵 Nueva tarea asignada                           hace 5 min     |
|    Te han asignado la tarea 'Revisar informe'                    |
|                                           [Ver tarea] [Archivar] |
+------------------------------------------------------------------+
| 🔵 Aprobacion pendiente                           hace 15 min    |
|    Pedido #1234 requiere tu aprobacion                           |
|                              [Aprobar] [Rechazar] [Ver] [Arch]   |
+------------------------------------------------------------------+
| 🟠 Stock bajo                                     hace 1 hora    |
|    Producto 'Widget A' tiene stock critico                       |
|                                          [Ver producto] [Arch]   |
+------------------------------------------------------------------+
|    5 nuevos comentarios                           hace 2 horas   |
|    En el documento 'Propuesta Q1'                                |
|                                         [Ver documento] [Arch]   |
+------------------------------------------------------------------+
|                        [Ver todas las notificaciones]             |
+------------------------------------------------------------------+

Leyenda:
🔵 = No leida (circulo azul)
🟠 = Warning (circulo naranja)
Sin icono = Ya leida

Pagina Completa de Notificaciones:
+------------------------------------------------------------------+
|  MIS NOTIFICACIONES                                               |
+------------------------------------------------------------------+
| [Todas v] [No leidas] [Archivadas]    [Buscar...]                |
+------------------------------------------------------------------+

| FECHA              | TIPO           | MENSAJE          | ESTADO  |
+------------------------------------------------------------------+
| 2025-12-05 10:30   | Tarea          | Nueva tarea...   | 🔵      |
| 2025-12-05 10:15   | Aprobacion     | Pedido #1234...  | 🔵      |
| 2025-12-05 09:00   | Stock          | Widget A bajo... | 🟠      |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /notifications | Listar mis notificaciones |
| GET | /notifications/count | Contador |
| PUT | /notifications/:id/read | Marcar como leida |
| PUT | /notifications/read-all | Marcar todas |
| PUT | /notifications/:id/archive | Archivar |
| POST | /notifications/:id/actions/:actionId | Ejecutar accion |

### WebSocket Events

```typescript
// Cliente conecta
ws://api.example.com/notifications?token=JWT

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

### Categorias

| Categoria | Color | Uso |
|-----------|-------|-----|
| info | Azul | Informativo |
| success | Verde | Confirmacion |
| warning | Amarillo | Atencion |
| error | Rojo | Problema |

---

## Definicion de Done

- [ ] Gateway WebSocket funcional
- [ ] CRUD notificaciones
- [ ] Entrega en tiempo real
- [ ] Marcar como leida individual/masivo
- [ ] Ejecutar acciones desde notificacion
- [ ] Agrupacion de similares
- [ ] Contador en header
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla notifications | Storage |
| Socket.io Gateway | WebSocket |
| Redis | Para pub/sub |

### Bloquea

| Item | Descripcion |
|------|-------------|
| UI Header | Badge de notificaciones |
| Todos los modulos | Pueden enviar notificaciones |

---

## Historial

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