# RF-NOTIF-002: Notificaciones por Email

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | RF-NOTIF-002 |
| **Modulo** | MGN-008 Notifications |
| **Titulo** | Notificaciones por Email |
| **Prioridad** | P0 - Critica |
| **Estado** | Draft |
| **Fecha** | 2025-12-05 |

---

## Descripcion

El sistema debe enviar notificaciones por email para eventos importantes, usando templates personalizables y respetando las preferencias de cada usuario.

---

## Requisitos Funcionales

### RF-NOTIF-002.1: Configuracion de Email

| Configuracion | Descripcion |
|---------------|-------------|
| SMTP Host | Servidor SMTP |
| SMTP Port | Puerto (587, 465) |
| SMTP User | Usuario autenticacion |
| SMTP Password | Password (encriptado) |
| From Address | Email remitente |
| From Name | Nombre remitente |
| Reply To | Email para respuestas |

### RF-NOTIF-002.2: Templates de Email

Estructura de template:

```typescript
interface EmailTemplate {
  id: UUID;
  tenant_id?: UUID;      // null = global
  code: string;          // Identificador unico
  name: string;          // Nombre descriptivo
  subject: string;       // Asunto (con variables)
  body_html: string;     // Cuerpo HTML
  body_text: string;     // Cuerpo texto plano
  variables: string[];   // Variables disponibles
  category: string;      // Categoria del template
  is_active: boolean;
  created_at: TIMESTAMPTZ;
  updated_at: TIMESTAMPTZ;
}
```

### RF-NOTIF-002.3: Variables en Templates

Sistema de variables con sintaxis Handlebars:

```html
<h1>Hola {{user.firstName}},</h1>

<p>Se ha creado un nuevo pedido:</p>

<table>
  <tr>
    <td>Numero:</td>
    <td>{{order.number}}</td>
  </tr>
  <tr>
    <td>Total:</td>
    <td>{{formatCurrency order.total order.currency}}</td>
  </tr>
</table>

{{#if order.items}}
<ul>
  {{#each order.items}}
  <li>{{this.name}} x {{this.quantity}}</li>
  {{/each}}
</ul>
{{/if}}

<a href="{{actionUrl}}">Ver pedido</a>
```

### RF-NOTIF-002.4: Templates Predefinidos

| Codigo | Descripcion | Variables |
|--------|-------------|-----------|
| `welcome` | Bienvenida nuevo usuario | user, tenant, activationUrl |
| `password_reset` | Recuperar password | user, resetUrl, expiresIn |
| `order_created` | Pedido creado | user, order, items |
| `invoice_sent` | Factura enviada | user, invoice, downloadUrl |
| `payment_received` | Pago recibido | user, payment, order |
| `task_assigned` | Tarea asignada | user, task, assigner |
| `approval_request` | Solicitud aprobacion | user, entity, approveUrl |

### RF-NOTIF-002.5: Personalizacion por Tenant

Cada tenant puede personalizar:

- Logo en header
- Colores del email
- Footer con datos empresa
- Templates especificos

```typescript
interface TenantEmailConfig {
  logoUrl: string;
  primaryColor: string;
  footerHtml: string;
  customTemplates: UUID[];  // Templates propios
}
```

### RF-NOTIF-002.6: Cola de Envio

Los emails se procesan via cola:

```typescript
interface EmailJob {
  id: UUID;
  templateCode: string;
  to: string[];
  cc?: string[];
  bcc?: string[];
  variables: Record<string, any>;
  attachments?: Attachment[];
  priority: 'low' | 'normal' | 'high';
  scheduledAt?: TIMESTAMPTZ;
  status: 'pending' | 'processing' | 'sent' | 'failed';
  attempts: number;
  lastError?: string;
  sentAt?: TIMESTAMPTZ;
}
```

### RF-NOTIF-002.7: Tracking de Emails

Opcionalmente, trackear apertura y clicks:

```typescript
interface EmailTracking {
  emailJobId: UUID;
  openedAt?: TIMESTAMPTZ;
  openCount: number;
  clicks: {
    url: string;
    clickedAt: TIMESTAMPTZ;
  }[];
  userAgent?: string;
  ipAddress?: INET;
}
```

---

## Operaciones

### Enviar Email

```typescript
POST /api/v1/notifications/email
{
  "template": "order_created",
  "to": ["cliente@example.com"],
  "variables": {
    "user": { "firstName": "Juan" },
    "order": { "number": "ORD-001", "total": 1500 }
  }
}

Response:
{
  "jobId": "uuid",
  "status": "queued",
  "scheduledAt": "2025-12-05T10:00:00Z"
}
```

### Listar Templates

```typescript
GET /api/v1/notifications/email/templates

Response:
{
  "data": [
    {
      "id": "uuid",
      "code": "welcome",
      "name": "Email de Bienvenida",
      "category": "auth",
      "variables": ["user", "tenant", "activationUrl"]
    }
  ]
}
```

### Crear/Editar Template

```typescript
POST /api/v1/notifications/email/templates
{
  "code": "custom_invoice",
  "name": "Factura Personalizada",
  "subject": "Factura {{invoice.number}}",
  "bodyHtml": "<html>...</html>",
  "bodyText": "...",
  "variables": ["user", "invoice"]
}
```

### Preview de Template

```typescript
POST /api/v1/notifications/email/templates/:id/preview
{
  "variables": {
    "user": { "firstName": "Juan" },
    "invoice": { "number": "INV-001" }
  }
}

Response:
{
  "subject": "Factura INV-001",
  "bodyHtml": "<html>...</html>",
  "bodyText": "..."
}
```

### Historial de Envios

```typescript
GET /api/v1/notifications/email/history?to=user@example.com

Response:
{
  "data": [
    {
      "id": "uuid",
      "template": "welcome",
      "to": ["user@example.com"],
      "status": "sent",
      "sentAt": "2025-12-05T10:00:00Z",
      "opened": true,
      "openedAt": "2025-12-05T10:05:00Z"
    }
  ]
}
```

---

## Reglas de Negocio

| ID | Regla | Severidad |
|----|-------|-----------|
| BR-001 | Reintentar 3 veces en caso de fallo | Reliability |
| BR-002 | Rate limit: 100 emails/min por tenant | Performance |
| BR-003 | Emails con tracking respetan privacidad | Privacy |
| BR-004 | Templates globales no editables por tenant | Security |
| BR-005 | Logs de email se retienen 90 dias | Compliance |

---

## Criterios de Aceptacion

- [ ] Configuracion SMTP funcional
- [ ] Templates con variables Handlebars
- [ ] Personalizacion por tenant
- [ ] Cola de envio con reintentos
- [ ] Tracking de apertura (opcional)
- [ ] Preview de templates
- [ ] Historial de envios

---

## Historial

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