# TrackingPremium WhatsApp Chatbot --- Implementation Plan > **Fuente de verdad técnica del proyecto** > > Este documento describe el plan, pero **el código es la autoridad**. > > **Regla crítica:** antes de actualizar este plan (estados, módulos, > “implementado”, “parcial”, “pendiente” o el próximo paso), se debe > inspeccionar el código real. **No asumir que algo está terminado solo > porque aparece en este documento.** > > Verificar Entities, Controllers, Services, Repositories, DTOs, > Validators, Migrations, endpoints y uso runtime real de cada campo. ## Leyenda - ✅ **COMPLETADO** - ⚠️ **PARCIAL** - ⏳ **PENDIENTE** - 🚫 **FUERA DE ALCANCE** ------------------------------------------------------------------------ # Estado general --------------------------------------------------------------------------- Orden Módulo Backend Frontend Estado ----------------- --------------- ------------- ------------- ------------- 1 Chatbot ✅ Completado ✅ Completado ✅ COMPLETADO Configuration 2 Chatbot Channel ✅ Completado ✅ Completado ✅ COMPLETADO Configuration 3 Chatbot ✅ Completado ✅ Completado ✅ COMPLETADO Business Hours 4 Handoff ⚠️ Parcial ⏳ Pendiente ⚠️ PARCIAL Configuration 5 Conversations ⏳ Pendiente ⏳ Pendiente ⏳ PENDIENTE 6 Messages ⏳ Pendiente ⏳ Pendiente ⏳ PENDIENTE 7 Human Handoff ⏳ Pendiente ⏳ Pendiente ⏳ PENDIENTE Runtime 8 Agent ⏳ Pendiente ⏳ Pendiente ⏳ PENDIENTE Assignment / Routing 9 Agent ⏳ Pendiente ⏳ Pendiente ⏳ PENDIENTE Notifications 10 Usage / Billing ⚠️ Parcial ⏳ Pendiente ⚠️ PARCIAL --------------------------------------------------------------------------- ------------------------------------------------------------------------ # 1. Chatbot Configuration **Estado:** ✅ COMPLETADO ## Objetivo Mantener la configuración principal del chatbot para cada compañía. ## Implementado El backend dispone de `ChatbotConfiguration` y API para consultar, crear y actualizar la configuración. La configuración actual incluye campos relacionados con: - Activación/desactivación del chatbot. - Modelo de IA. - Prompt del sistema. - Límite/contexto de historial. - Timeout de conversación. - Timeout de handoff. - `autoHandoffEnabled`. - `humanHandoffMessage`. - `fallbackMessage`. - `unavailableMessage`. ## Entities - `ChatbotConfiguration` - `Maincompany` - `User` para información de creación/actualización cuando aplique. ## Endpoints Base: `/api/chatbot/configuration` - `GET /api/chatbot/configuration` - `POST /api/chatbot/configuration` - `PUT /api/chatbot/configuration` - `PATCH /api/chatbot/configuration/activate` - `PATCH /api/chatbot/configuration/deactivate` ## Frontend ✅ COMPLETADO Existe pantalla de configuración general del chatbot. ## Pendiente No agregar aquí reglas avanzadas de handoff que tengan una responsabilidad propia. ------------------------------------------------------------------------ # 2. Chatbot Channel Configuration **Estado:** ✅ COMPLETADO ## Objetivo Configurar los canales mediante los cuales una compañía/agencia utilizará el chatbot. La primera implementación está orientada a WhatsApp/Twilio. ## Implementado Existe configuración de canales asociada al chatbot y soporte de asociación opcional con agencia. Existe catálogo de números WhatsApp disponibles. ## Entities - `ChatbotChannelConfiguration` - `ChatbotConfiguration` - `WhatsappPhone` - `Agency` ## Endpoints Base: `/api/chatbot/channels` - `GET /api/chatbot/channels` - `GET /api/chatbot/channels/{id}` - `POST /api/chatbot/channels` - `PUT /api/chatbot/channels/{id}` - `PATCH /api/chatbot/channels/{id}/activate` - `PATCH /api/chatbot/channels/{id}/deactivate` - `DELETE /api/chatbot/channels/{id}` Catálogo: - `GET /api/chatbot/whatsapp-phones` ## Frontend ✅ COMPLETADO Existe ventana para creación/configuración de canales. ------------------------------------------------------------------------ # 3. Chatbot Business Hours **Estado:** ✅ COMPLETADO ## Objetivo Configurar los horarios de atención globales del chatbot y overrides por agencia. ## Implementado Existe `ChatbotBusinessHours`. Soporta: - Día de la semana. - Abierto/cerrado. - Hora de apertura. - Hora de cierre. - Configuración global. - Configuración específica por agencia. - Consulta de horario efectivo de una agencia. - Múltiples intervalos para un mismo día. Ejemplo válido: - Lunes 08:00--12:00 - Lunes 13:00--17:00 ## Entities - `ChatbotBusinessHours` - `ChatbotConfiguration` - `Agency` ## Endpoints Base: `/api/chatbot/business-hours` - `GET /api/chatbot/business-hours` - `PUT /api/chatbot/business-hours` - `GET /api/chatbot/business-hours/agencies/{agencyId}` - `PUT /api/chatbot/business-hours/agencies/{agencyId}` - `DELETE /api/chatbot/business-hours/agencies/{agencyId}` - `GET /api/chatbot/business-hours/agencies/{agencyId}/effective` ## Frontend ✅ COMPLETADO Existe pantalla para configurar horarios globales y rangos de atención. ## Nota técnica La entidad permite múltiples registros para el mismo `dayOfWeek`, por lo que puede representar varios intervalos en un mismo día. El backend debe evitar rangos solapados si esa validación todavía no existe. ------------------------------------------------------------------------ # 4. Handoff Configuration **Estado:** ⚠️ PARCIAL ## Objetivo Definir las reglas que determinan cuándo y cómo una conversación debe pasar del chatbot a atención humana. ## Implementado actualmente Dentro de `ChatbotConfiguration` ya existen: - `handoffTimeoutMinutes` - `humanHandoffMessage` - `autoHandoffEnabled` - `fallbackMessage` - `unavailableMessage` También existe `ChatbotBusinessHours`, que puede utilizarse como contexto para determinar si existe atención humana disponible. ## Importante Estos campos actualmente representan principalmente **persistencia/configuración**. No asumir que existe lógica runtime que ejecute el handoff. ## Pendiente Validar/diseñar soporte para: - Transferencia cuando el cliente solicita explícitamente un agente. - Transferencia cuando el chatbot no puede resolver. - Transferencia por sentimiento negativo, si forma parte del alcance. - Comportamiento fuera del horario de atención. - Comportamiento cuando no hay agentes disponibles. - Routing por compañía/agencia. - Estrategia de asignación. - Pool/cola de agentes. - Notificaciones. ## Frontend ⏳ PENDIENTE No crear una pantalla duplicando: - timeout de handoff; - mensaje de handoff; - campos que ya estén presentes en la configuración general. La futura UI debe enfocarse solamente en reglas y routing que realmente sean soportados por el backend. ------------------------------------------------------------------------ # 5. Conversations **Estado:** ⏳ PENDIENTE ## Objetivo Representar una conversación entre un cliente y el chatbot/agente humano. Debe convertirse en la entidad central del futuro **Centro de conversaciones**. ## Pendiente Definir, entre otros aspectos: - Identificador de conversación. - Compañía. - Agencia. - Canal. - Cliente identificado. - Estado. - Modo bot/humano. - Inicio y última actividad. - Cierre. - Relación con mensajes. - Relación con handoff. ## Frontend ⏳ PENDIENTE Futura pantalla: **Centro de conversaciones** ------------------------------------------------------------------------ # 6. Messages **Estado:** ⏳ PENDIENTE ## Objetivo Persistir los mensajes entrantes y salientes de cada conversación. Debe soportar mensajes enviados por: - Cliente. - Bot. - Agente humano. ## Pendiente Definir modelo y API según el flujo real de conversaciones. No confundir con tablas existentes utilizadas exclusivamente para mensajes automáticos/salientes si no representan el historial completo de una conversación. ## Frontend ⏳ PENDIENTE Los mensajes deberán visualizarse dentro del Centro de conversaciones. ------------------------------------------------------------------------ # 7. Human Handoff Runtime **Estado:** ⏳ PENDIENTE ## Objetivo Ejecutar y registrar una transferencia real de una conversación desde el bot hacia un agente humano. ## Estado actual No existe una entidad `ChatbotHandoff` dedicada. `ChatbotUsageMonthly.humanHandoffCount` es solamente una métrica y **no representa una transferencia individual**. ## Pendiente El runtime deberá poder representar, según el diseño final: - Conversación. - Motivo del handoff. - Estado. - Agencia. - Agente asignado. - Fecha de solicitud. - Fecha de asignación. - Fecha de atención. - Fecha de cierre/cancelación. La definición exacta debe realizarse antes de implementar. ## Frontend ⏳ PENDIENTE La operación del handoff deberá integrarse al Centro de conversaciones. ------------------------------------------------------------------------ # 8. Agent Assignment / Routing **Estado:** ⏳ PENDIENTE ## Objetivo Determinar quién puede atender una conversación transferida. Debe respetar el modelo multi-tenant y las reglas existentes de agencias. ## Contexto TrackingPremium maneja: - Compañías. - Agencias. - Agencia Master. - Clientes exclusivos o compartidos según las reglas existentes de cada agencia. - Números globales por compañía o números asociados a agencias. No modificar la estructura existente de Company, Agency o clientes sin una necesidad explícitamente aprobada. ## Pendiente Definir: - Routing por compañía. - Routing por agencia. - Agencia asociada al canal. - Agencia asociada al cliente. - Acceso de usuarios de agencia Master. - Agentes elegibles. - Asignación manual o automática. - Estrategia de distribución. ------------------------------------------------------------------------ # 9. Agent Notifications **Estado:** ⏳ PENDIENTE ## Objetivo Avisar a los agentes humanos cuando una conversación necesita atención. ## Pendiente Definir qué mecanismos se utilizarán: - Notificación dentro de TrackingPremium. - Actualización en tiempo real del Centro de conversaciones. - Email, si aplica. - WhatsApp, si aplica. No asumir canales de notificación hasta definir el alcance. ------------------------------------------------------------------------ # 10. Usage / Billing **Estado:** ⚠️ PARCIAL ## Objetivo Registrar consumo mensual del chatbot para métricas, restricciones y futura facturación. ## Implementado Existe `ChatbotUsageMonthly`. Incluye soporte para métricas como: - uso mensual; - contador de handoffs humanos (`humanHandoffCount`). ## Endpoints Base: `/api/chatbot/usage` - `GET /api/chatbot/usage/current` - `GET /api/chatbot/usage` - `GET /api/chatbot/usage/{year}/{month}` ## Pendiente Verificar el cableado runtime de cada contador. En particular, la existencia de `humanHandoffCount` no significa que exista actualmente un flujo de handoff que lo incremente. También queda por definir el alcance final de: - límites; - restricciones; - planes; - billing; - visualización frontend. ## Frontend ⏳ PENDIENTE ------------------------------------------------------------------------ # Próximo paso recomendado ## Handoff Configuration El próximo paso debe ser completar el diseño/backend necesario para **Handoff Configuration**, reutilizando lo que ya existe en `ChatbotConfiguration` y evitando duplicar campos. Antes de implementar, Cursor debe volver a inspeccionar el código actual y determinar exactamente qué configuración adicional es necesaria para soportar: 1. reglas de disparo; 2. comportamiento fuera de horario; 3. comportamiento cuando no existen agentes; 4. routing por compañía/agencia; 5. estrategia de asignación. No implementar todavía el runtime completo de conversaciones dentro de este módulo. ------------------------------------------------------------------------ # Orden recomendado de implementación restante 1. **Handoff Configuration** 2. **Conversation + Message model** 3. **Recepción de mensajes / creación de conversación** 4. **Procesamiento del chatbot** 5. **Human Handoff Runtime** 6. **Agent Assignment / Routing** 7. **Agent Notifications** 8. **Centro de conversaciones** 9. **Usage/Billing integration** 10. **Hardening, permisos, métricas y observabilidad** Este orden puede cambiar si el análisis del código demuestra dependencias diferentes. ------------------------------------------------------------------------ # Reglas para futuras actualizaciones Este plan debe actualizarse después de completar cada ticket. ## Regla crítica (obligatoria) Antes de actualizar este plan —incluido cambiar estados, marcar módulos como completados/parciales, reescribir “Implementado” o definir el próximo paso— Cursor **debe inspeccionar el código**. **No asumir que algo está terminado solo porque aparece en este documento.** El documento puede estar desactualizado, incompleto o adelantado al código. La evidencia válida es el código ejecutado/inspectado: - Entities y columnas reales - Controllers / routes reales - Services y uso runtime real de campos - Repositories, DTOs, Validators - Migrations aplicadas / scripts SQL - Tests que demuestren comportamiento No marcar funcionalidades como COMPLETADAS basándose únicamente en: - este plan; - tickets; - comentarios; - nombres de Entities; - migraciones; - existencia de métodos sin uso runtime; - campos persistidos sin lógica que los consuma. Se debe verificar el comportamiento real implementado. Cuando un ticket termine, Cursor debe: 1. Inspeccionar el código (no solo el diff del ticket). 2. Comparar el código real con este plan. 3. Actualizar las secciones afectadas según lo encontrado. 4. Actualizar la tabla **Estado general**. 5. Revisar dependencias. 6. Determinar un único **Próximo paso recomendado**. 7. No implementar automáticamente el siguiente ticket. ------------------------------------------------------------------------ # Restricciones arquitectónicas conocidas - TrackingPremium es multi-tenant. - Una compañía puede tener múltiples agencias. - Los clientes pueden ser exclusivos o compartidos según las reglas existentes de agencia. - Existe el concepto de Agencia Master. - Los usuarios de Agencia Master pueden tener visibilidad superior a usuarios de agencias normales. - Las conversaciones deberán poder filtrarse por agencia una vez identificado el cliente. - Una compañía puede utilizar un número global o números diferentes por agencia. - La solución debe soportar múltiples números. - No modificar innecesariamente las estructuras existentes de Company, Agency y clientes. - La integración actual de Twilio utilizada por funcionalidades existentes no debe romperse. - Las credenciales sensibles de Twilio nunca deben exponerse en frontend.