# PLAN SPRINT 5 - WhatsApp Business API

**Proyecto:** template-saas
**Sprint:** 5
**Objetivo:** Integrar WhatsApp Business API para notificaciones
**Fecha Inicio:** 2026-01-10
**SP Total:** 13

---

## RESUMEN EJECUTIVO

### Estado Actual
- **Canales de notificación:** Email, Push, In-app, WebSocket
- **WhatsApp:** No integrado
- **SMS:** No integrado

### Gap a Cerrar
Integrar WhatsApp Business API como canal de notificaciones:
1. Provider de WhatsApp (Meta Cloud API)
2. Templates de mensajes aprobados
3. Webhook para status de entrega
4. UI de configuración por tenant
5. Tests de integración

---

## TAREAS DEL SPRINT

### WA-001: WhatsApp Provider Backend

**Agente:** Backend-Agent
**SP:** 5
**Dependencia:** Ninguna

#### Archivos a Leer
```yaml
archivos:
  - apps/backend/src/modules/email/services/email.service.ts
  - apps/backend/src/modules/notifications/services/notifications.service.ts
  - apps/database/ddl/02-enums.sql
```

#### Entregables
```yaml
entregables:
  - apps/backend/src/modules/whatsapp/whatsapp.module.ts
  - apps/backend/src/modules/whatsapp/services/whatsapp.service.ts
  - apps/backend/src/modules/whatsapp/services/whatsapp-template.service.ts
  - apps/backend/src/modules/whatsapp/controllers/whatsapp-webhook.controller.ts
  - apps/backend/src/modules/whatsapp/dto/send-whatsapp.dto.ts
  - apps/backend/src/modules/whatsapp/dto/whatsapp-webhook.dto.ts
  - apps/backend/src/modules/whatsapp/__tests__/whatsapp.service.spec.ts
```

#### Funcionalidades
- Envío de mensajes de texto
- Envío de mensajes con template
- Webhook para delivery status
- Rate limiting por tenant
- Retry logic para fallos

---

### WA-002: DDL WhatsApp

**Agente:** Database-Agent
**SP:** 2
**Dependencia:** Ninguna
**Paralelo con:** WA-001

#### Entregables
```yaml
entregables:
  - apps/database/ddl/schemas/whatsapp/tables/01-whatsapp-configs.sql
  - apps/database/ddl/schemas/whatsapp/tables/02-whatsapp-messages.sql
  - apps/database/ddl/02-enums.sql (actualizar)
```

#### Tablas
- `whatsapp.configs` - Configuración por tenant (phone_number_id, access_token)
- `whatsapp.messages` - Log de mensajes enviados

#### Enums
- `whatsapp.message_status`: 'pending', 'sent', 'delivered', 'read', 'failed'
- `whatsapp.message_type`: 'text', 'template', 'media'

---

### WA-003: Entidades TypeORM

**Agente:** Backend-Agent
**SP:** 2
**Dependencia:** WA-002

#### Entregables
```yaml
entregables:
  - apps/backend/src/modules/whatsapp/entities/whatsapp-config.entity.ts
  - apps/backend/src/modules/whatsapp/entities/whatsapp-message.entity.ts
```

---

### WA-004: Frontend WhatsApp Config

**Agente:** Frontend-Agent
**SP:** 2
**Dependencia:** WA-001

#### Entregables
```yaml
entregables:
  - apps/frontend/src/pages/admin/WhatsAppSettings.tsx
  - apps/frontend/src/hooks/useWhatsApp.ts
  - apps/frontend/src/services/whatsapp.api.ts
  - apps/frontend/src/components/whatsapp/WhatsAppTestMessage.tsx
```

#### Funcionalidades
- Configuración de credenciales Meta
- Test de conexión
- Envío de mensaje de prueba
- Ver historial de mensajes

---

### WA-005: Integración Notifications

**Agente:** Backend-Agent
**SP:** 2
**Dependencia:** WA-001, WA-003

#### Entregables
```yaml
entregables:
  - apps/backend/src/modules/notifications/services/notifications.service.ts (modificar)
  - apps/backend/src/modules/notifications/dto/send-notification.dto.ts (modificar)
```

#### Cambios
- Agregar 'whatsapp' al enum de canales
- Integrar WhatsAppService en NotificationsService
- Validar que tenant tenga WhatsApp configurado

---

## CONFIGURACIÓN META CLOUD API

### Variables de Entorno
```env
WHATSAPP_API_VERSION=v17.0
WHATSAPP_VERIFY_TOKEN=your_verify_token
# Per-tenant configs stored in DB
```

### Webhook Events
- `messages` - Mensajes entrantes
- `message_status` - Updates de status (sent, delivered, read)

---

## EJECUCIÓN DEL SPRINT

### Orden de Ejecución

```
WA-002 (DDL)
    │
    └── WA-003 (Entities)
            │
WA-001 (Backend) ──────────┤
    │                      │
    ├── WA-004 (Frontend)  │
    │                      │
    └── WA-005 (Integration)
```

### Comandos de Validación

```bash
# Tests del módulo
cd apps/backend && npm run test -- --testPathPattern=whatsapp

# Recrear BD con nuevo schema
cd apps/database && FORCE=1 ./scripts/drop-and-recreate.sh
```

### Métricas de Éxito

| Métrica | Objetivo |
|---------|----------|
| Endpoints nuevos | 5-6 |
| Tests nuevos | ~20 |
| Tablas nuevas | 2 |
| Webhook funcional | SI |

---

## ESTRUCTURA DE ARCHIVOS

```
apps/backend/src/modules/whatsapp/
├── whatsapp.module.ts
├── services/
│   ├── whatsapp.service.ts
│   └── whatsapp-template.service.ts
├── controllers/
│   └── whatsapp-webhook.controller.ts
├── entities/
│   ├── whatsapp-config.entity.ts
│   └── whatsapp-message.entity.ts
├── dto/
│   ├── send-whatsapp.dto.ts
│   └── whatsapp-webhook.dto.ts
└── __tests__/
    └── whatsapp.service.spec.ts

apps/database/ddl/schemas/whatsapp/
├── tables/
│   ├── 01-whatsapp-configs.sql
│   └── 02-whatsapp-messages.sql
```

---

## REFERENCIAS

- [Meta Cloud API Docs](https://developers.facebook.com/docs/whatsapp/cloud-api)
- [Webhook Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks)
- [Message Templates](https://developers.facebook.com/docs/whatsapp/message-templates)

---

**Creado:** 2026-01-10
**Sprint:** 5 de 5
**Estado:** COMPLETADO

---

## REPORTE DE EJECUCION

**Fecha Completado:** 2026-01-10

### Entregables Generados

#### WA-002: DDL WhatsApp
| Archivo | Estado |
|---------|--------|
| apps/database/ddl/schemas/whatsapp/00-schema.sql | Creado |
| apps/database/ddl/schemas/whatsapp/tables/01-whatsapp-configs.sql | Creado |
| apps/database/ddl/schemas/whatsapp/tables/02-whatsapp-messages.sql | Creado |

#### WA-003: Entidades TypeORM
| Archivo | Estado |
|---------|--------|
| apps/backend/src/modules/whatsapp/entities/whatsapp-config.entity.ts | Creado |
| apps/backend/src/modules/whatsapp/entities/whatsapp-message.entity.ts | Creado |

#### WA-001: Backend WhatsApp Module
| Archivo | Estado |
|---------|--------|
| apps/backend/src/modules/whatsapp/whatsapp.module.ts | Creado |
| apps/backend/src/modules/whatsapp/services/whatsapp.service.ts | Creado |
| apps/backend/src/modules/whatsapp/controllers/whatsapp.controller.ts | Creado |
| apps/backend/src/modules/whatsapp/controllers/whatsapp-webhook.controller.ts | Creado |
| apps/backend/src/modules/whatsapp/dto/send-whatsapp.dto.ts | Creado |
| apps/backend/src/modules/whatsapp/dto/whatsapp-webhook.dto.ts | Creado |
| apps/backend/src/modules/whatsapp/dto/whatsapp-config.dto.ts | Creado |
| apps/backend/src/modules/whatsapp/__tests__/whatsapp.service.spec.ts | Creado |

#### WA-004: Frontend WhatsApp
| Archivo | Estado |
|---------|--------|
| apps/frontend/src/pages/admin/WhatsAppSettings.tsx | Creado |
| apps/frontend/src/hooks/useWhatsApp.ts | Creado |
| apps/frontend/src/services/whatsapp.api.ts | Creado |
| apps/frontend/src/components/whatsapp/WhatsAppTestMessage.tsx | Creado |

#### WA-005: Integration Notifications
| Archivo | Cambio |
|---------|--------|
| apps/backend/src/modules/notifications/dto/create-notification.dto.ts | Agregado 'whatsapp' al enum de canales |
| apps/backend/src/modules/notifications/services/notifications.service.ts | Integrado WhatsAppService |

### Funcionalidades Implementadas

1. **Configuracion por Tenant**
   - CRUD de configuracion WhatsApp Business API
   - Verificacion automatica de credenciales
   - Rate limiting configurable

2. **Envio de Mensajes**
   - Mensajes de texto
   - Mensajes con template
   - Mensajes multimedia (imagen, documento, audio, video)

3. **Webhook Handler**
   - Verificacion de webhook Meta
   - Procesamiento de mensajes entrantes
   - Actualizacion de status de delivery

4. **Frontend Admin**
   - Pagina de configuracion
   - Prueba de conexion
   - Historial de mensajes

### Metricas Finales

| Metrica | Objetivo | Resultado |
|---------|----------|-----------|
| Tablas DDL | 2 | 2 |
| Entidades | 2 | 2 |
| Endpoints API | 5-6 | 8 |
| Tests | ~20 | 22 |
| SP completados | 13 | 13 |