# US-MGN008-002: Gestionar Notificaciones por Email

## Identificacion

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

---

## Historia de Usuario

**Como** administrador del sistema
**Quiero** gestionar el envio de emails transaccionales con templates
**Para** comunicar eventos importantes a los usuarios de forma profesional

---

## Descripcion

El sistema envia emails transaccionales usando templates con variables. Los templates son personalizables por tenant (branding). Los emails se procesan via cola con reintentos y tracking opcional.

### Contexto

- Templates con sintaxis Handlebars
- Personalizacion por tenant (logo, colores)
- Cola de envio con reintentos
- Tracking de apertura y clicks

---

## Criterios de Aceptacion

### Escenario 1: Enviar email usando template

```gherkin
Given un template "welcome" configurado
When sistema envia POST /api/v1/notifications/email
  | template | "welcome" |
  | to | ["user@example.com"] |
  | variables | { user: { firstName: "Juan" } } |
Then el email se encola para envio
  And retorna jobId para tracking
```

### Escenario 2: Preview de template

```gherkin
Given un template con variables
When envia POST /api/v1/notifications/email/templates/{id}/preview
  | variables | { user: { firstName: "Juan" } } |
Then retorna el email renderizado sin enviarlo
  And muestra subject y body con las variables reemplazadas
```

### Escenario 3: Listar templates disponibles

```gherkin
Given un administrador de tenant
When accede a GET /api/v1/notifications/email/templates
Then retorna templates globales + templates del tenant
  And cada template indica sus variables disponibles
```

### Escenario 4: Crear template personalizado

```gherkin
Given un administrador con permiso "notifications.templates.manage"
When crea POST /api/v1/notifications/email/templates
  | code | "custom_order_confirmation" |
  | subject | "Pedido {{order.number}} confirmado" |
  | bodyHtml | "<html>...</html>" |
Then el template se guarda para el tenant
  And queda disponible para envios
```

### Escenario 5: Reintento automatico en fallo

```gherkin
Given un email encolado
When el envio falla (ej: SMTP timeout)
Then el sistema reintenta hasta 3 veces
  And espera tiempo exponencial entre reintentos
  And marca como failed si todos fallan
```

### Escenario 6: Email con branding de tenant

```gherkin
Given tenant con configuracion:
  | logoUrl | "https://company.com/logo.png" |
  | primaryColor | "#FF5733" |
When se envia un email
Then el template incluye el logo del tenant
  And los colores corresponden a la marca
```

### Escenario 7: Consultar historial de envios

```gherkin
Given emails enviados
When consulta GET /api/v1/notifications/email/history?to=user@example.com
Then retorna lista de emails enviados a ese destinatario
  And incluye status, sentAt, opened, openedAt
```

### Escenario 8: Tracking de apertura

```gherkin
Given email enviado con tracking habilitado
When el usuario abre el email
Then el sistema registra openedAt y openCount
  And registra userAgent e IP (si disponible)
```

### Escenario 9: Email con adjuntos

```gherkin
Given necesidad de enviar factura adjunta
When envia email con attachments
  | filename | "factura.pdf" |
  | content | base64 o URL |
Then el email incluye el adjunto
```

### Escenario 10: Programar envio

```gherkin
Given email a enviar en el futuro
When especifica scheduledAt
Then el email no se envia inmediatamente
  And se procesa a la hora indicada
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  TEMPLATES DE EMAIL                              [+ Nuevo Template]|
+------------------------------------------------------------------+
| [Categoria: Todas v]  [Origen: Todos v]  [Buscar...]              |
+------------------------------------------------------------------+

| CODIGO           | NOMBRE                | CATEGORIA  | ORIGEN   |
+------------------------------------------------------------------+
| welcome          | Email de Bienvenida   | Auth       | Global   |
| password_reset   | Recuperar Password    | Auth       | Global   |
| order_created    | Pedido Creado         | Orders     | Global   |
| custom_invoice   | Factura Personalizada | Financial  | Tenant   |
+------------------------------------------------------------------+

Editor de Template:
+------------------------------------------------------------------+
| EDITAR TEMPLATE: order_created                             [X]   |
+------------------------------------------------------------------+
| Nombre: Pedido Creado                                            |
| Codigo: order_created (no editable)                              |
|                                                                   |
| Asunto*                                                           |
| [Nuevo pedido {{order.number}} recibido                      ]   |
|                                                                   |
| Variables disponibles: user.firstName, order.number, order.total |
|                                                                   |
| Cuerpo HTML*                                                      |
| +--------------------------------------------------------------+ |
| | <h1>Hola {{user.firstName}},</h1>                            | |
| | <p>Hemos recibido tu pedido {{order.number}}.</p>            | |
| | <table>                                                       | |
| |   <tr><td>Total:</td><td>{{order.total}}</td></tr>           | |
| | </table>                                                      | |
| +--------------------------------------------------------------+ |
|                                                                   |
| [Preview]                                                         |
|                                                                   |
|                     [Cancelar]  [=== Guardar ===]                |
+------------------------------------------------------------------+

Preview Modal:
+------------------------------------------------------------------+
| PREVIEW                                                    [X]   |
+------------------------------------------------------------------+
| De: Mi Empresa <noreply@empresa.com>                             |
| Para: usuario@ejemplo.com                                         |
| Asunto: Nuevo pedido ORD-001 recibido                            |
+------------------------------------------------------------------+
|                                                                   |
| [LOGO DE LA EMPRESA]                                              |
|                                                                   |
| Hola Juan,                                                        |
|                                                                   |
| Hemos recibido tu pedido ORD-001.                                |
|                                                                   |
| Total: $1,500.00                                                  |
|                                                                   |
| [Ver Pedido]                                                      |
|                                                                   |
| --                                                                |
| Mi Empresa SA                                                     |
| contacto@empresa.com                                              |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| POST | /notifications/email | Enviar email |
| GET | /notifications/email/templates | Listar templates |
| POST | /notifications/email/templates | Crear template |
| PUT | /notifications/email/templates/:id | Actualizar |
| POST | /notifications/email/templates/:id/preview | Preview |
| GET | /notifications/email/history | Historial |

### Variables de Sistema

```typescript
const systemVariables = {
  appName: 'Mi ERP',
  appUrl: 'https://app.example.com',
  currentYear: new Date().getFullYear(),
  supportEmail: 'soporte@example.com'
};
```

### Cola de Emails (Bull)

```typescript
@Processor('emails')
export class EmailProcessor {
  @Process()
  async handleEmail(job: Job<EmailJobData>) {
    // Renderizar template
    // Enviar via SMTP
    // Registrar resultado
  }
}
```

---

## Definicion de Done

- [ ] Configuracion SMTP funcional
- [ ] CRUD templates con Handlebars
- [ ] Branding por tenant
- [ ] Cola con reintentos
- [ ] Preview de templates
- [ ] Tracking de apertura
- [ ] Historial de envios
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla email_templates | Templates |
| Tabla email_jobs | Cola |
| Bull Queue | Procesamiento asincrono |
| SMTP | Configuracion de envio |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Auth Module | Emails de welcome, reset |
| Todos los modulos | Emails transaccionales |

---

## Historial

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