Aller au contenu principal

Architecture et Fonctionnement Interne

Cette page est une vue technique de haut niveau de l'architecture de PulseChat : comment le module est structur\u00e9, les classes cl\u00e9s et les flux importants que vous pourriez avoir besoin de comprendre lors du d\u00e9bogage ou de l'extension du module.

1. Point d'Entr\u00e9e du Module​

Fichier : modules/pulsechat/pulsechat.php

Responsabilit\u00e9s :

  • D\u00e9clare les m\u00e9tadonn\u00e9es du module (nom, version, auteur).
  • D\u00e9finit des constantes :
    • PULSECHAT_MODULE_NAME, PULSECHAT_VERSION
    • Constantes de chemin/URL : PULSECHAT_MODULE_PATH, PULSECHAT_MODULE_URL, chemins d'upload.
    • Constantes de tables BD : TABLE_PC_* (conversations, messages, participants, etc.).
  • Enregistre des 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') (interrogation email)
  • Ajoute l'entr\u00e9e du menu d'administration.
  • Ajoute des hooks c\u00f4t\u00e9 client pour injecter le widget de chat dans le portail client lorsqu'il est activ\u00e9.

2. Contr\u00f4leurs​

2.1 controllers/Pulsechat.php​

Contr\u00f4leur principal d'administration pour l'interface de chat :

  • \u00c9tend AdminController.
  • Constructeur :
    • S'assure que le helper est charg\u00e9 (pulsechat/pulsechat).
    • Redirige si le module est d\u00e9sactiv\u00e9.
    • V\u00e9rifie la capacit\u00e9 view du personnel.
    • Charge Pulsechat_model.
    • D\u00e9termine le transport (pusher vs. polling).
  • M\u00e9thodes cl\u00e9s :
    • chat() -- rend la vue compl\u00e8te du chat (views/admin/chat_view.php).
    • complete_setup() -- g\u00e8re l'assistant de transport initial.
    • Nombreux endpoints AJAX pour :
      • R\u00e9cup\u00e9rer contacts, groupes, clients.
      • Envoyer/recevoir des messages (hors canal).
      • R\u00e9actions, favoris, \u00e9pingles, upload de fichiers.
      • Recherche, vues favoris/\u00e9pingles/globales.
      • Export et helpers analytiques (pour les analytiques in-app).

2.2 controllers/Pulsechat_Channels.php​

G\u00e8re les endpoints omnicanaux et IA :

  • Canaux :
    • conversations, conversation, mark_read, send_channel_message, contact, link_contact, CRUD de canaux, etc.
  • Endpoints IA :
    • ai_auto_reply()
    • ai_suggestions()
    • ai_rewrite()
    • ai_spelling()
    • ai_summary()
    • ai_sentiment()
    • ai_translate()
    • Ceux-ci d\u00e9l\u00e8guent \u00e0 PulsechatAI et retournent du JSON normalis\u00e9.
  • Analytiques :
    • analytics(), analytics_export() pour les m\u00e9triques des canaux (messages par jour, par canal, utilisation IA).

2.3 Contr\u00f4leurs de Webhook​

  • controllers/webhooks/ChannelWebhook.php

    • Re\u00e7oit les webhooks des fournisseurs externes (WhatsApp, Telegram, etc.).
    • Dispatche vers l'adaptateur de canal appropri\u00e9.

  • Pulsechat_webhook.php / webhook.php

    • Endpoints de compatibilit\u00e9 ou de commodit\u00e9 pour certains fournisseurs.

3. Mod\u00e8les​

3.1 models/Pulsechat_model.php​

Couche centrale d'acc\u00e8s aux donn\u00e9es :

  • \u00c9tend App_Model.
  • Assure la connexion UTF-8mb4 (pour les emojis).
  • Responsabilit\u00e9s principales :
    • Utilisateurs et pr\u00e9sence :
      • get_staff_users(), get_group_users(), get_my_groups(), gestion des statuts.
    • Conversations :
      • CRUD pour pc_conversations, gestion des participants dans pc_participants.
      • Silencier, \u00e9pingler, archiver.
    • Messages :
      • Ins\u00e9rer des messages dans pc_messages.
      • Appliquer les r\u00e9actions (pc_reactions), favoris (pc_starred_messages), \u00e9pingles (pc_pinned_messages).
      • Charger des messages pagin\u00e9s pour diff\u00e9rents types de conversation.
    • Fichiers :
      • G\u00e9rer pc_shared_files, s'assurer que messages et fichiers restent synchronis\u00e9s.
    • Omnicanal :
      • G\u00e9rer pc_channels, pc_external_contacts, pc_contact_identities.
      • R\u00e8gles d'automatisation (pc_automation_rules).
      • Donn\u00e9es analytiques dans pc_analytics_cache, pc_assignments_log.
    • Journaux IA :
      • log_ai_usage() \u00e9crit dans pc_ai_logs.
      • get_ai_usage_stats() agr\u00e8ge l'utilisation IA pour les analytiques.

Tout le SQL utilise db_prefix() pour respecter le pr\u00e9fixe de tables de Perfex.

4. Biblioth\u00e8ques​

4.1 libraries/PulsechatAI.php​

Abstraction du moteur IA :

  • G\u00e8re tous les cas d'utilisation IA :
    • R\u00e9ponse automatique, suggestions, r\u00e9\u00e9criture, orthographe, r\u00e9sum\u00e9, sentiment, traduction, mode chatbot.
  • Expose des m\u00e9thodes comme :
    • generateAutoReply()
    • generateSuggestions()
    • rewriteMessage()
    • correctSpelling()
    • summarizeConversation()
    • analyzeSentiment()
    • translate()
    • chatbotReply()
  • Dispatche en interne entre :
    • API Chat Completions d'OpenAI.
    • API Messages d'Anthropic.
  • Enregistre l'utilisation dans pc_ai_logs via Pulsechat_model.

4.2 Adaptateurs de Canal​

Espace de noms : libraries/channels/

  • ChannelAdapterInterface.php -- d\u00e9finit une interface commune pour les adaptateurs de canal.
  • Adaptateurs pour des plateformes sp\u00e9cifiques :
    • WhatsappAdapter.php
    • TelegramAdapter.php
    • EmailAdapter.php
    • Potentiellement d'autres (SMS, Slack, Viber, etc.).
  • ChannelManager.php :
    • Orchestre l'envoi sortant et le traitement entrant entre les adaptateurs.
    • G\u00e8re les limites de d\u00e9bit, la journalisation des erreurs, les t\u00e9l\u00e9chargements de m\u00e9dias et la gestion des pi\u00e8ces jointes.

4.3 Correspondance de Contacts​

  • libraries/ContactMatcher.php :
    • Convertit les identifiants de canal (t\u00e9l\u00e9phone, email, IDs de chat) en pc_external_contacts.
    • Tente de faire correspondre avec les clients/contacts/leads de Perfex via les tables principales.

5. Vues et Assets​

5.1 Vues​

  • views/admin/chat_view.php

    • Page principale du chat d'administration (interface compl\u00e8te \u00e0 trois panneaux).
    • Rend :
      • Barre lat\u00e9rale (onglets, recherche, listes de contacts).
      • Contenu (messages et compositeur).
      • Panneau de d\u00e9tails (infos CRM, participants, analytiques).
    • Injecte l'objet de configuration JS pulsechatConfig.

  • views/admin/settings.php

    • Panneau de param\u00e8tres rendu dans admin/pulsechat/settings.
    • Sections organis\u00e9es :
      • G\u00e9n\u00e9ral, Notifications, Permissions, Fonctionnalit\u00e9s, Limites, Donn\u00e9es.
      • Options omnicanales.
      • Configuration de l'Assistant IA.

  • views/admin/settings_page.php

    • Page enveloppante pour les param\u00e8tres du module (inclut settings.php dans un panneau Perfex avec bouton Sauvegarder).

5.2 JavaScript​

Situ\u00e9 dans assets/js/ :

  • pulsechat-full.js :

    • Logique frontend principale pour l'interface de chat.
    • G\u00e8re :
      • \u00c9tat (state.activeChat, contacts, groupes, clients).
      • Rendu de la liste de messages, scroll infini.
      • Indicateurs de saisie, pr\u00e9sence, accus\u00e9s de r\u00e9ception.
      • S\u00e9lecteur d'emojis et r\u00e9actions.
      • Param\u00e8tres d'affichage locaux (th\u00e8me, disposition).
      • Gestionnaires de la barre d'outils IA lorsque les canaux sont d\u00e9sactiv\u00e9s.

  • pulsechat-channels.js :

    • Frontend omnicanal.
    • Rend la liste des Canaux, filtres et compositeur de canal.
    • G\u00e8re les actions IA en mode canal.
    • Impl\u00e9mente les r\u00e9ponses pr\u00e9d\u00e9finies et l'interface des r\u00e8gles d'automatisation.

  • pulsechat-analytics.js :

    • Rend les graphiques et analytiques pour l'utilisation omnicanale.

5.3 CSS​

  • assets/css/pulsechat-full.css
    • Styles complets pour l'interface de chat d'administration.
    • Inclut :
      • Disposition (barre lat\u00e9rale, contenu, d\u00e9tails).
      • S\u00e9lecteur d'emojis, menus contextuels, modales.
      • Ajustements du mode sombre.

6. Migrations et Installation​

6.1 install.php​

Ex\u00e9cut\u00e9 lors de l'activation du module via pulsechat_activation_hook() :

  • Cr\u00e9e les tables principales (versions initiales de pc_conversations, pc_participants, pc_messages, etc.).
  • Ajoute des options par d\u00e9faut telles que :
    • pulsechat_enabled
    • pulsechat_clients_enabled
    • pulsechat_transport
    • Valeurs par d\u00e9faut pour les notifications, fonctionnalit\u00e9s, limites de fichiers, etc.

6.2 Migrations​

Situ\u00e9es dans migrations/ :

  • 100_version_100.php et suivantes -- base et changements incr\u00e9mentaux.
  • 122_version_122.php -- Fondation Omnicanale :
    • Ajoute pc_channels, pc_external_contacts, pc_contact_identities, pc_automation_rules, pc_ai_logs, etc.
    • \u00c9tend les tables existantes pour le support des canaux (channel_type, subject, delivery_status, ai_suggested, etc.).
    • Alimente les options IA initiales de PulseChat.
  • 123_version_123.php -- s'assure que pc_realtime_events existe.
  • 124_version_124.php -- IA Multi-Fournisseur :
    • Ajoute des options :
      • pulsechat_ai_provider
      • pulsechat_ai_anthropic_api_key

Le syst\u00e8me de migration de Perfex s'assure qu'elles s'ex\u00e9cutent dans l'ordre lors de la mise \u00e0 jour du module.

7. Notes d'Extensibilit\u00e9​

Lors de l'extension de PulseChat :

  • Nouveaux Types de Canal :

    • Impl\u00e9mentez ChannelAdapterInterface dans un nouvel adaptateur sous libraries/channels/.
    • Enregistrez les champs de configuration dans l'interface de param\u00e9trage des canaux.
    • Mettez \u00e0 jour la gestion de pc_channels si n\u00e9cessaire.

  • Nouvelles Actions IA :

    • Ajoutez une nouvelle m\u00e9thode \u00e0 PulsechatAI.
    • Ajoutez un nouvel endpoint de contr\u00f4leur dans Pulsechat_Channels.
    • C\u00e2blez un nouveau bouton ou contr\u00f4le d'interface dans pulsechat-full.js / pulsechat-channels.js.
    • Pensez \u00e0 journaliser dans pc_ai_logs pour les analytiques.

  • Int\u00e9grations Personnalis\u00e9es :

    • Utilisez Pulsechat_model pour les op\u00e9rations BD plut\u00f4t que d'\u00e9crire du SQL direct.
    • R\u00e9utilisez les utilitaires existants (ex. ContactMatcher) pour \u00e9viter la logique en double.
astuce

PulseChat repose fortement sur les hooks Perfex et les comportements d'App_Controller ; suivez ces patrons pour rester compatible avec les mises \u00e0 jour du noyau. Ajoutez toujours une migration pour les changements de sch\u00e9ma plut\u00f4t que de modifier uniquement install.php.