Saltar al contenido principal

Arquitectura e Internos

Esta página es una visión técnica de alto nivel de la arquitectura de PulseChat: cómo está estructurado el módulo, clases clave y flujos importantes que puedes necesitar entender al depurar o extender el módulo.

1. Punto de Entrada del Módulo​

Archivo: modules/pulsechat/pulsechat.php

Responsabilidades:

  • Declara metadatos del módulo (nombre, versión, autor).
  • Define constantes:
    • PULSECHAT_MODULE_NAME, PULSECHAT_VERSION
    • Constantes de ruta/URL: PULSECHAT_MODULE_PATH, PULSECHAT_MODULE_URL, rutas de subida.
    • Constantes de tablas de BD: TABLE_PC_* (conversaciones, mensajes, participantes, etc.).
  • Registra hooks:
    • register_activation_hook
    • register_language_files
    • hooks()->add_action('admin_init', 'pulsechat_register_permissions')
    • hooks()->add_action('after_cron_run', 'pulsechat_cron_email_poll') (sondeo de email)
  • Añade la entrada del menú de administración.
  • Añade hooks del lado del cliente para inyectar el widget de chat en el portal del cliente cuando está habilitado.

2. Controladores​

2.1 controllers/Pulsechat.php​

Controlador principal de administración para la interfaz de chat:

  • Extiende AdminController.
  • Constructor:
    • Asegura que el helper esté cargado (pulsechat/pulsechat).
    • Redirige si el módulo está deshabilitado.
    • Verifica la capacidad view del personal.
    • Carga Pulsechat_model.
    • Determina el transporte (pusher vs. polling).
  • Métodos clave:
    • chat() -- renderiza la vista completa del chat (views/admin/chat_view.php).
    • complete_setup() -- maneja el asistente de transporte inicial.
    • Numerosos endpoints AJAX para:
      • Obtener contactos, grupos, clientes.
      • Enviar/recibir mensajes (sin canal).
      • Reacciones, destacados, fijados, subida de archivos.
      • Búsqueda, vistas de destacados/fijados/globales.
      • Exportación y helpers de analíticas (para analíticas dentro de la app).

2.2 controllers/Pulsechat_Channels.php​

Maneja endpoints omnicanal y de IA:

  • Canales:
    • conversations, conversation, mark_read, send_channel_message, contact, link_contact, CRUD de canales, etc.
  • Endpoints de IA:
    • ai_auto_reply()
    • ai_suggestions()
    • ai_rewrite()
    • ai_spelling()
    • ai_summary()
    • ai_sentiment()
    • ai_translate()
    • Estos delegan a PulsechatAI y devuelven JSON normalizado.
  • Analíticas:
    • analytics(), analytics_export() para métricas de canales (mensajes por día, por canal, uso de IA).

2.3 Controladores de Webhook​

  • controllers/webhooks/ChannelWebhook.php

    • Recibe webhooks de proveedores externos (WhatsApp, Telegram, etc.).
    • Despacha al adaptador de canal apropiado.

  • Pulsechat_webhook.php / webhook.php

    • Endpoints de compatibilidad o conveniencia para algunos proveedores.

3. Modelos​

3.1 models/Pulsechat_model.php​

Capa central de acceso a datos:

  • Extiende App_Model.
  • Asegura conexión UTF-8mb4 (para emojis).
  • Responsabilidades principales:
    • Usuarios y presencia:
      • get_staff_users(), get_group_users(), get_my_groups(), gestión de estados.
    • Conversaciones:
      • CRUD para pc_conversations, gestión de participantes en pc_participants.
      • Silenciar, fijar, archivar.
    • Mensajes:
      • Insertar mensajes en pc_messages.
      • Aplicar reacciones (pc_reactions), destacados (pc_starred_messages), fijados (pc_pinned_messages).
      • Cargar mensajes paginados para varios tipos de conversación.
    • Archivos:
      • Gestionar pc_shared_files, asegurar que mensajes y archivos se mantengan sincronizados.
    • Omnicanal:
      • Manejar pc_channels, pc_external_contacts, pc_contact_identities.
      • Reglas de automatización (pc_automation_rules).
      • Datos de analíticas en pc_analytics_cache, pc_assignments_log.
    • Registros de IA:
      • log_ai_usage() escribe en pc_ai_logs.
      • get_ai_usage_stats() agrega uso de IA para analíticas.

Todo el SQL usa db_prefix() para respetar el prefijo de tablas de Perfex.

4. Bibliotecas​

4.1 libraries/PulsechatAI.php​

Abstracción del motor de IA:

  • Maneja todos los casos de uso de IA:
    • Respuesta automática, sugerencias, reescritura, ortografía, resumen, sentimiento, traducción, modo chatbot.
  • Expone métodos como:
    • generateAutoReply()
    • generateSuggestions()
    • rewriteMessage()
    • correctSpelling()
    • summarizeConversation()
    • analyzeSentiment()
    • translate()
    • chatbotReply()
  • Internamente despacha entre:
    • API de Chat Completions de OpenAI.
    • API de Messages de Anthropic.
  • Registra el uso en pc_ai_logs vía Pulsechat_model.

4.2 Adaptadores de Canal​

Espacio de nombres: libraries/channels/

  • ChannelAdapterInterface.php -- define una interfaz común para adaptadores de canal.
  • Adaptadores para plataformas específicas:
    • WhatsappAdapter.php
    • TelegramAdapter.php
    • EmailAdapter.php
    • Potencialmente otros (SMS, Slack, Viber, etc.).
  • ChannelManager.php:
    • Orquesta el envío saliente y el procesamiento entrante entre adaptadores.
    • Maneja límites de frecuencia, registro de errores, descargas de medios y manejo de archivos adjuntos.

4.3 Coincidencia de Contactos​

  • libraries/ContactMatcher.php:
    • Convierte identificadores de canal (teléfono, email, IDs de chat) en pc_external_contacts.
    • Intenta coincidir con clientes/contactos/leads de Perfex vía tablas principales.

5. Vistas y Assets​

5.1 Vistas​

  • views/admin/chat_view.php

    • Página principal del chat de administración (interfaz completa de tres paneles).
    • Renderiza:
      • Barra lateral (pestañas, búsqueda, listas de contactos).
      • Contenido (mensajes y compositor).
      • Panel de detalles (información CRM, participantes, analíticas).
    • Inyecta el objeto de configuración JS pulsechatConfig.

  • views/admin/settings.php

    • Panel de configuración renderizado en admin/pulsechat/settings.
    • Secciones organizadas:
      • General, Notificaciones, Permisos, Funcionalidades, Límites, Datos.
      • Opciones omnicanal.
      • Configuración del Asistente de IA.

  • views/admin/settings_page.php

    • Página envolvente para la configuración del módulo (incluye settings.php dentro de un panel de Perfex con botón Guardar).

5.2 JavaScript​

Ubicado en assets/js/:

  • pulsechat-full.js:

    • Lógica principal del frontend para la interfaz de chat.
    • Gestiona:
      • Estado (state.activeChat, contactos, grupos, clientes).
      • Renderizado de la lista de mensajes, scroll infinito.
      • Indicadores de escritura, presencia, confirmaciones de lectura.
      • Selector de emojis y reacciones.
      • Configuración de visualización local (tema, diseño).
      • Manejadores de la barra de herramientas de IA cuando los canales están deshabilitados.

  • pulsechat-channels.js:

    • Frontend omnicanal.
    • Renderiza la lista de Canales, filtros y compositor de canal.
    • Maneja acciones de IA en modo canal.
    • Implementa respuestas predefinidas e interfaz de reglas de automatización.

  • pulsechat-analytics.js:

    • Renderiza gráficos y analíticas para uso omnicanal.

5.3 CSS​

  • assets/css/pulsechat-full.css
    • Estilos completos para la interfaz de chat de administración.
    • Incluye:
      • Diseño (barra lateral, contenido, detalles).
      • Selector de emojis, menús contextuales, modales.
      • Ajustes del modo oscuro.

6. Migraciones e Instalación​

6.1 install.php​

Ejecutado en la activación del módulo vía pulsechat_activation_hook():

  • Crea tablas principales (versiones iniciales de pc_conversations, pc_participants, pc_messages, etc.).
  • Añade opciones predeterminadas como:
    • pulsechat_enabled
    • pulsechat_clients_enabled
    • pulsechat_transport
    • Valores predeterminados para notificaciones, funcionalidades, límites de archivos, etc.

6.2 Migraciones​

Ubicadas en migrations/:

  • 100_version_100.php y posteriores -- base e cambios incrementales.
  • 122_version_122.php -- Fundación Omnicanal:
    • Añade pc_channels, pc_external_contacts, pc_contact_identities, pc_automation_rules, pc_ai_logs, etc.
    • Extiende tablas existentes para soporte de canales (channel_type, subject, delivery_status, ai_suggested, etc.).
    • Siembra opciones iniciales de IA de PulseChat.
  • 123_version_123.php -- asegura que pc_realtime_events exista.
  • 124_version_124.php -- IA Multi-Proveedor:
    • Añade opciones:
      • pulsechat_ai_provider
      • pulsechat_ai_anthropic_api_key

El sistema de migraciones de Perfex asegura que estas se ejecuten en orden al actualizar el módulo.

7. Notas de Extensibilidad​

Al extender PulseChat:

  • Nuevos Tipos de Canal:

    • Implementa ChannelAdapterInterface en un nuevo adaptador bajo libraries/channels/.
    • Registra campos de configuración en la interfaz de configuración de canales.
    • Actualiza el manejo de pc_channels según sea necesario.

  • Nuevas Acciones de IA:

    • Añade un nuevo método a PulsechatAI.
    • Añade un nuevo endpoint de controlador en Pulsechat_Channels.
    • Conecta un nuevo botón o control de interfaz en pulsechat-full.js / pulsechat-channels.js.
    • Considera registrar en pc_ai_logs para analíticas.

  • Integraciones Personalizadas:

    • Usa Pulsechat_model para operaciones de BD en lugar de escribir SQL directo.
    • Reutiliza utilidades existentes (ej. ContactMatcher) para evitar lógica duplicada.
tip

PulseChat depende en gran medida de los hooks de Perfex y los comportamientos de App_Controller; sigue esos patrones para mantenerte compatible con las actualizaciones del núcleo. Siempre añade una migración para cambios de esquema en lugar de modificar solo install.php.