template-saas/orchestration/_archive/analisis-previo/ANALISIS-VALIDACION-SPRINT-5-2026-01-10.md

ANÁLISIS DE VALIDACIÓN - SPRINT 5 (WhatsApp Integration)

Fecha: 2026-01-10 Estado: FASE 1 - Análisis Inicial Completado Sprint Analizado: Sprint 5 - WhatsApp Business API

---

RESUMEN EJECUTIVO

Se identificaron 9 GAPS CRÍTICOS que impiden el funcionamiento correcto de la integración WhatsApp:

Categoría	GAPS Críticos	GAPS Menores
DDL/Database	3	2
Backend	3	2
Frontend	3	1
Total	9	5

---

FASE 1: INVENTARIO DE CAMBIOS

1.1 Archivos DDL Creados

Archivo	Ruta	Estado
00-schema.sql	apps/database/ddl/schemas/whatsapp/	✅ Creado
01-whatsapp-configs.sql	apps/database/ddl/schemas/whatsapp/tables/	✅ Creado
02-whatsapp-messages.sql	apps/database/ddl/schemas/whatsapp/tables/	✅ Creado

1.2 Archivos Backend Creados

Archivo	Ruta	Estado
whatsapp.module.ts	apps/backend/src/modules/whatsapp/	✅ Creado
whatsapp.service.ts	apps/backend/src/modules/whatsapp/services/	✅ Creado
whatsapp.controller.ts	apps/backend/src/modules/whatsapp/controllers/	✅ Creado
whatsapp-webhook.controller.ts	apps/backend/src/modules/whatsapp/controllers/	✅ Creado
whatsapp-config.entity.ts	apps/backend/src/modules/whatsapp/entities/	✅ Creado
whatsapp-message.entity.ts	apps/backend/src/modules/whatsapp/entities/	✅ Creado
send-whatsapp.dto.ts	apps/backend/src/modules/whatsapp/dto/	✅ Creado
whatsapp-webhook.dto.ts	apps/backend/src/modules/whatsapp/dto/	✅ Creado
whatsapp-config.dto.ts	apps/backend/src/modules/whatsapp/dto/	✅ Creado
whatsapp.service.spec.ts	apps/backend/src/modules/whatsapp/tests/	✅ Creado
index.ts (varios)	apps/backend/src/modules/whatsapp/*/index.ts	✅ Creados

1.3 Archivos Backend Modificados

Archivo	Cambio
notifications.service.ts	Agregada integración con WhatsAppService
create-notification.dto.ts	Agregado canal 'whatsapp' y campo phoneNumber

1.4 Archivos Frontend Creados

Archivo	Ruta	Estado
WhatsAppSettings.tsx	apps/frontend/src/pages/admin/	✅ Creado
useWhatsApp.ts	apps/frontend/src/hooks/	✅ Creado
whatsapp.api.ts	apps/frontend/src/services/	✅ Creado
WhatsAppTestMessage.tsx	apps/frontend/src/components/whatsapp/	✅ Creado
index.ts	apps/frontend/src/components/whatsapp/	✅ Creado

---

FASE 2: ANÁLISIS DETALLADO DE DEPENDENCIAS

2.1 Cadena de Dependencias DDL

tenants.tenants (existente)
    │
    ├── whatsapp.configs (nuevo) - FK tenant_id
    │       │
    │       └── whatsapp.messages (nuevo) - FK config_id
    │               │
users.users (existente) ──────┘ FK user_id (nullable)

2.2 Cadena de Dependencias Backend

app.module.ts
    │
    └── WhatsAppModule (NO REGISTRADO) ❌
            │
            ├── WhatsAppService
            │       │
            │       ├── WhatsAppConfig (entity)
            │       └── WhatsAppMessage (entity)
            │
            ├── WhatsAppController
            │       └── requiere: JwtAuthGuard, RolesGuard, TenantId
            │
            └── WhatsAppWebhookController
                    └── requiere: ConfigService

notifications.module.ts
    │
    └── NotificationsService
            │
            └── @Optional() WhatsAppService (NO DISPONIBLE) ❌

2.3 Cadena de Dependencias Frontend

router/index.tsx
    │
    └── WhatsAppSettings (NO REGISTRADO) ❌

DashboardLayout.tsx
    │
    └── navigation[]
            └── WhatsApp item (NO EXISTE) ❌

whatsapp.api.ts
    │
    └── import { apiClient } from './api-client' (NO EXISTE) ❌
            └── debería ser: import { api } from './api'

useWhatsApp.ts
    │
    ├── import { useToast } from './useToast' ✅
    └── import { whatsappApi } from '../services/whatsapp.api' ⚠️ (api-client falla)

---

GAPS IDENTIFICADOS

GAPS CRÍTICOS - DDL

GAP-DDL-001: Schema no declarado en 01-schemas.sql

Severidad: CRÍTICA Archivo: apps/database/ddl/01-schemas.sql Problema: El schema whatsapp no está listado en el archivo principal de schemas Impacto: Inconsistencia en estructura DDL, dificulta mantenimiento Solución:

-- Agregar después de webhooks (línea ~11)
CREATE SCHEMA IF NOT EXISTS whatsapp;

GAP-DDL-002: ENUMs no centralizados

Severidad: CRÍTICA Archivo: apps/database/ddl/02-enums.sql Problema: Los 3 enums de WhatsApp están en 02-whatsapp-messages.sql en lugar de 02-enums.sql Impacto: Orden de ejecución incorrecto, posibles errores de dependencia Solución: Mover a 02-enums.sql:

CREATE TYPE whatsapp.message_status AS ENUM ('pending', 'sent', 'delivered', 'read', 'failed');
CREATE TYPE whatsapp.message_type AS ENUM ('text', 'template', 'image', 'document', 'audio', 'video', 'location', 'contacts', 'interactive');
CREATE TYPE whatsapp.message_direction AS ENUM ('outbound', 'inbound');

GAP-DDL-003: Script create-database.sh no incluye whatsapp

Severidad: CRÍTICA Archivo: apps/database/scripts/create-database.sh Problema: Schema whatsapp no está en:

• SCHEMA_ORDER array
• GRANT statements
• Table/Sequence privileges Impacto: Base de datos incompleta al ejecutar recreación Solución: Agregar "whatsapp" a SCHEMA_ORDER y grants correspondientes

GAPS CRÍTICOS - Backend

GAP-BE-001: Módulo no registrado en app.module.ts

Severidad: CRÍTICA Archivo: apps/backend/src/app.module.ts Problema: WhatsAppModule no está importado ni registrado Impacto: Módulo completo inaccesible, endpoints no funcionan Solución:

import { WhatsAppModule } from '@modules/whatsapp/whatsapp.module';
// En imports array:
WhatsAppModule,

GAP-BE-002: Configuración no definida

Severidad: CRÍTICA Archivo: apps/backend/src/config/env.config.ts Problema: No hay variables de entorno para WhatsApp Impacto: ConfigService.get('whatsapp.*') retorna undefined Solución:

whatsapp: {
  apiVersion: process.env.WHATSAPP_API_VERSION || 'v17.0',
  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN || '',
  appSecret: process.env.WHATSAPP_APP_SECRET || '',
},

GAP-BE-003: Notifications no importa WhatsApp

Severidad: CRÍTICA Archivo: apps/backend/src/modules/notifications/notifications.module.ts Problema: NotificationsModule no importa WhatsAppModule Impacto: Canal 'whatsapp' en notificaciones no funciona Solución:

imports: [
  // ... otros imports
  WhatsAppModule,
],

GAPS CRÍTICOS - Frontend

GAP-FE-001: Import incorrecto de API client

Severidad: CRÍTICA Archivo: apps/frontend/src/services/whatsapp.api.ts Problema: import { apiClient } from './api-client' - archivo no existe Impacto: Error de módulo en runtime, toda la funcionalidad falla Solución:

import { api } from './api';  // Cambiar apiClient por api en todo el archivo

GAP-FE-002: Ruta no registrada

Severidad: CRÍTICA Archivo: apps/frontend/src/router/index.tsx Problema: No hay ruta para WhatsAppSettings Impacto: Página inaccesible Solución:

{
  path: 'whatsapp',
  element: <WhatsAppSettings />,
}

GAP-FE-003: Navegación no actualizada

Severidad: CRÍTICA Archivo: apps/frontend/src/layouts/DashboardLayout.tsx Problema: No hay item de WhatsApp en el menú de navegación Impacto: Usuarios no pueden descubrir la funcionalidad Solución:

{ name: 'WhatsApp', href: '/dashboard/whatsapp', icon: MessageSquare },

GAPS MENORES

ID	Archivo	Problema	Impacto
GAP-DDL-004	README.md	Schema whatsapp no documentado	Documentación incompleta
GAP-DDL-005	README.md	Cambios Sprint 5 no registrados	Historial incompleto
GAP-BE-004	whatsapp.service.ts	TODO: Encrypt access_token	Seguridad (tokens en texto plano)
GAP-BE-005	whatsapp-webhook.controller.ts	TODO: Emit events	Mensajes entrantes no generan eventos
GAP-FE-004	index.ts (components)	Solo exporta WhatsAppTestMessage	Export incompleto

---

MATRIZ DE IMPACTO

GAP ID	Bloquea Funcionalidad	Bloquea DB	Bloquea Tests	Prioridad
GAP-DDL-001	No	Sí	No	P1
GAP-DDL-002	No	Sí	No	P1
GAP-DDL-003	No	Sí	No	P0
GAP-BE-001	Sí	No	No	P0
GAP-BE-002	Parcial	No	No	P1
GAP-BE-003	Sí	No	No	P0
GAP-FE-001	Sí	No	No	P0
GAP-FE-002	Sí	No	No	P0
GAP-FE-003	Sí	No	No	P1

---

ORDEN DE RESOLUCIÓN RECOMENDADO

Fase A: DDL y Scripts (Bloqueantes para DB)

1. GAP-DDL-001: Agregar schema a 01-schemas.sql
2. GAP-DDL-002: Mover enums a 02-enums.sql
3. GAP-DDL-003: Actualizar create-database.sh
4. Validar: Ejecutar drop-and-recreate.sh

Fase B: Backend (Bloqueantes para API)

1. GAP-BE-001: Registrar WhatsAppModule en app.module.ts
2. GAP-BE-002: Agregar configuración en env.config.ts
3. GAP-BE-003: Importar WhatsAppModule en notifications.module.ts
4. Validar: npm run test -- --testPathPattern=whatsapp

Fase C: Frontend (Bloqueantes para UI)

1. GAP-FE-001: Corregir import de api-client a api
2. GAP-FE-002: Registrar ruta en router
3. GAP-FE-003: Agregar item en navegación
4. Validar: npm run build

Fase D: Documentación

1. GAP-DDL-004: Actualizar README.md con schema whatsapp
2. GAP-DDL-005: Documentar cambios Sprint 5
3. Validar: Revisión manual

---

PRÓXIMOS PASOS

1. FASE 3: Crear plan detallado con archivos específicos a modificar
2. FASE 4: Validar plan contra este análisis
3. FASE 5: Refinar plan con dependencias cruzadas
4. FASE 6: Ejecutar correcciones
5. FASE 7: Validar ejecución con recreación de DB y tests

---

Documento creado: 2026-01-10 Autor: Claude Code - Validación Sprint 5 Estado: Listo para FASE 3 - Planeación