rckrdmrd
50a821a415
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Actualizaciones de configuracion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
317 lines
8.1 KiB
Markdown
317 lines
8.1 KiB
Markdown
# 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 |
|