Zum Hauptinhalt springen

Architektur & Interna

Diese Seite ist eine technische \u00dcbersicht der PulseChat-Architektur: wie das Modul strukturiert ist, Schl\u00fcsselklassen und wichtige Abl\u00e4ufe, die Sie beim Debuggen oder Erweitern des Moduls verstehen m\u00fcssen.

1. Modul-Einstiegspunkt​

Datei: modules/pulsechat/pulsechat.php

Verantwortlichkeiten:

  • Deklariert Modul-Metadaten (Name, Version, Autor).
  • Definiert Konstanten:
    • PULSECHAT_MODULE_NAME, PULSECHAT_VERSION
    • Pfad-/URL-Konstanten: PULSECHAT_MODULE_PATH, PULSECHAT_MODULE_URL, Upload-Pfade.
    • DB-Tabellenkonstanten: TABLE_PC_* (Konversationen, Nachrichten, Teilnehmer, etc.).
  • Registriert 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') (E-Mail-Polling)
  • F\u00fcgt den Admin-Men\u00fceintrag hinzu.
  • F\u00fcgt clientseitige Hooks zum Einbetten des Chat-Widgets im Kundenportal hinzu, wenn aktiviert.

2. Controller​

2.1 controllers/Pulsechat.php​

Haupt-Admin-Controller f\u00fcr die Chat-Oberfl\u00e4che:

  • Erweitert AdminController.
  • Konstruktor:
    • Stellt sicher, dass der Helper geladen ist (pulsechat/pulsechat).
    • Leitet um, wenn das Modul deaktiviert ist.
    • Pr\u00fcft die view-F\u00e4higkeit des Mitarbeiters.
    • L\u00e4dt Pulsechat_model.
    • Bestimmt den Transport (pusher vs. polling).
  • Schl\u00fcsselmethoden:
    • chat() -- rendert die vollst\u00e4ndige Chat-Ansicht (views/admin/chat_view.php).
    • complete_setup() -- verarbeitet den initialen Transport-Assistenten.
    • Zahlreiche AJAX-Endpoints f\u00fcr:
      • Kontakte, Gruppen, Kunden abrufen.
      • Nachrichten senden/empfangen (ohne Kanal).
      • Reaktionen, Markierungen, Anheftungen, Datei-Uploads.
      • Suche, Markierte/Angeheftete/Globale Ansichten.
      • Export und Analyse-Helfer (f\u00fcr In-App-Analysen).

2.2 controllers/Pulsechat_Channels.php​

Verarbeitet Omnichannel- und KI-Endpoints:

  • Kan\u00e4le:
    • conversations, conversation, mark_read, send_channel_message, contact, link_contact, Kanal-CRUD, etc.
  • KI-Endpoints:
    • ai_auto_reply()
    • ai_suggestions()
    • ai_rewrite()
    • ai_spelling()
    • ai_summary()
    • ai_sentiment()
    • ai_translate()
    • Diese delegieren an PulsechatAI und geben normalisiertes JSON zur\u00fcck.
  • Analysen:
    • analytics(), analytics_export() f\u00fcr Kanalmetriken (Nachrichten pro Tag, pro Kanal, KI-Nutzung).

2.3 Webhook-Controller​

  • controllers/webhooks/ChannelWebhook.php

    • Empf\u00e4ngt Webhooks von externen Anbietern (WhatsApp, Telegram, etc.).
    • Dispatcht an den passenden Kanaladapter.

  • Pulsechat_webhook.php / webhook.php

    • Kompatibilit\u00e4ts- oder Komfort-Endpoints f\u00fcr einige Anbieter.

3. Modelle​

3.1 models/Pulsechat_model.php​

Zentrale Datenzugriffsschicht:

  • Erweitert App_Model.
  • Stellt UTF-8mb4-Verbindung sicher (f\u00fcr Emojis).
  • Hauptverantwortlichkeiten:
    • Benutzer & Pr\u00e4senz:
      • get_staff_users(), get_group_users(), get_my_groups(), Statusverwaltung.
    • Konversationen:
      • CRUD f\u00fcr pc_conversations, Teilnehmerverwaltung in pc_participants.
      • Stummschalten, Anheften, Archivieren.
    • Nachrichten:
      • Nachrichten in pc_messages einf\u00fcgen.
      • Reaktionen (pc_reactions), Markierungen (pc_starred_messages), Anheftungen (pc_pinned_messages) anwenden.
      • Paginierte Nachrichten f\u00fcr verschiedene Konversationstypen laden.
    • Dateien:
      • pc_shared_files verwalten, sicherstellen, dass Nachrichten und Dateien synchron bleiben.
    • Omnichannel:
      • pc_channels, pc_external_contacts, pc_contact_identities verarbeiten.
      • Automatisierungsregeln (pc_automation_rules).
      • Analysedaten in pc_analytics_cache, pc_assignments_log.
    • KI-Protokolle:
      • log_ai_usage() schreibt in pc_ai_logs.
      • get_ai_usage_stats() aggregiert KI-Nutzung f\u00fcr Analysen.

Alles SQL verwendet db_prefix() um Perfex' Tabellenpr\u00e4fix zu respektieren.

4. Bibliotheken​

4.1 libraries/PulsechatAI.php​

KI-Engine-Abstraktion:

  • Verarbeitet alle KI-Anwendungsf\u00e4lle:
    • Auto-Antwort, Vorschl\u00e4ge, Umschreibung, Rechtschreibung, Zusammenfassung, Stimmung, \u00dcbersetzung, Chatbot-Modus.
  • Stellt Methoden bereit wie:
    • generateAutoReply()
    • generateSuggestions()
    • rewriteMessage()
    • correctSpelling()
    • summarizeConversation()
    • analyzeSentiment()
    • translate()
    • chatbotReply()
  • Dispatcht intern zwischen:
    • OpenAI Chat Completions API.
    • Anthropic Messages API.
  • Protokolliert Nutzung in pc_ai_logs \u00fcber Pulsechat_model.

4.2 Kanaladapter​

Namespace: libraries/channels/

  • ChannelAdapterInterface.php -- definiert eine gemeinsame Schnittstelle f\u00fcr Kanaladapter.
  • Adapter f\u00fcr spezifische Plattformen:
    • WhatsappAdapter.php
    • TelegramAdapter.php
    • EmailAdapter.php
    • Potenziell andere (SMS, Slack, Viber, etc.).
  • ChannelManager.php:
    • Orchestriert ausgehenden Versand und eingehende Verarbeitung \u00fcber Adapter.
    • Behandelt Ratenlimits, Fehlerprotokollierung, Medien-Downloads und Anhangsverarbeitung.

4.3 Kontaktzuordnung​

  • libraries/ContactMatcher.php:
    • Konvertiert Kanalidentifikatoren (Telefon, E-Mail, Chat-IDs) in pc_external_contacts.
    • Versucht Zuordnung zu Perfex-Kunden/Kontakten/Leads \u00fcber Kerntabellen.

5. Views & Assets​

5.1 Views​

  • views/admin/chat_view.php

    • Haupt-Admin-Chat-Seite (vollst\u00e4ndige Drei-Panel-Oberfl\u00e4che).
    • Rendert:
      • Seitenleiste (Tabs, Suche, Kontaktlisten).
      • Inhalt (Nachrichten und Verfasser).
      • Detailpanel (CRM-Info, Teilnehmer, Analysen).
    • Injiziert das JS-Konfigurationsobjekt pulsechatConfig.

  • views/admin/settings.php

    • Einstellungspanel gerendert unter admin/pulsechat/settings.
    • Organisierte Abschnitte:
      • Allgemein, Benachrichtigungen, Berechtigungen, Funktionen, Limits, Daten.
      • Omnichannel-Optionen.
      • KI-Assistent-Konfiguration.

  • views/admin/settings_page.php

    • Wrapper-Seite f\u00fcr Moduleinstellungen (enth\u00e4lt settings.php in einem Perfex-Panel mit Speichern-Schaltfl\u00e4che).

5.2 JavaScript​

Befindet sich in assets/js/:

  • pulsechat-full.js:

    • Haupt-Frontend-Logik f\u00fcr die Chat-Oberfl\u00e4che.
    • Verwaltet:
      • Zustand (state.activeChat, Kontakte, Gruppen, Kunden).
      • Nachrichtenlisten-Rendering, Endlos-Scrolling.
      • Tipp-Indikatoren, Pr\u00e4senz, Lesebest\u00e4tigungen.
      • Emoji-W\u00e4hler und Reaktionen.
      • Lokale Anzeigeeinstellungen (Theme, Layout).
      • KI-Werkzeugleisten-Handler wenn Kan\u00e4le deaktiviert sind.

  • pulsechat-channels.js:

    • Omnichannel-Frontend.
    • Rendert die Kanalliste, Filter und Kanalverfasser.
    • Verarbeitet KI-Aktionen im Kanalmodus.
    • Implementiert Standardantworten und Automatisierungsregel-Oberfl\u00e4che.

  • pulsechat-analytics.js:

    • Rendert Diagramme und Analysen f\u00fcr Omnichannel-Nutzung.

5.3 CSS​

  • assets/css/pulsechat-full.css
    • Vollst\u00e4ndiges Styling f\u00fcr die Admin-Chat-Oberfl\u00e4che.
    • Beinhaltet:
      • Layout (Seitenleiste, Inhalt, Details).
      • Emoji-W\u00e4hler, Kontextmen\u00fcs, Modals.
      • Dark-Mode-Anpassungen.

6. Migrationen & Installation​

6.1 install.php​

Ausgef\u00fchrt bei Modulaktivierung \u00fcber pulsechat_activation_hook():

  • Erstellt Kerntabellen (initiale Versionen von pc_conversations, pc_participants, pc_messages, etc.).
  • F\u00fcgt Standardoptionen hinzu wie:
    • pulsechat_enabled
    • pulsechat_clients_enabled
    • pulsechat_transport
    • Standards f\u00fcr Benachrichtigungen, Funktionen, Dateilimits, etc.

6.2 Migrationen​

Befinden sich in migrations/:

  • 100_version_100.php und nachfolgende -- Basis und inkrementelle \u00c4nderungen.
  • 122_version_122.php -- Omnichannel-Grundlage:
    • F\u00fcgt pc_channels, pc_external_contacts, pc_contact_identities, pc_automation_rules, pc_ai_logs hinzu, etc.
    • Erweitert bestehende Tabellen f\u00fcr Kanalunterst\u00fctzung (channel_type, subject, delivery_status, ai_suggested, etc.).
    • Initialisiert PulseChat KI-Optionen.
  • 123_version_123.php -- stellt sicher, dass pc_realtime_events existiert.
  • 124_version_124.php -- Multi-Anbieter-KI:
    • F\u00fcgt Optionen hinzu:
      • pulsechat_ai_provider
      • pulsechat_ai_anthropic_api_key

Das Perfex-Migrationssystem stellt sicher, dass diese bei der Modulaktualisierung in der richtigen Reihenfolge ausgef\u00fchrt werden.

7. Erweiterungshinweise​

Bei der Erweiterung von PulseChat:

  • Neue Kanaltypen:

    • Implementieren Sie ChannelAdapterInterface in einem neuen Adapter unter libraries/channels/.
    • Registrieren Sie Konfigurationsfelder in der Kanaleinstellungs-Oberfl\u00e4che.
    • Aktualisieren Sie die pc_channels-Verarbeitung nach Bedarf.

  • Neue KI-Aktionen:

    • F\u00fcgen Sie eine neue Methode zu PulsechatAI hinzu.
    • F\u00fcgen Sie einen neuen Controller-Endpoint in Pulsechat_Channels hinzu.
    • Verkn\u00fcpfen Sie eine neue Schaltfl\u00e4che oder Steuerelement in pulsechat-full.js / pulsechat-channels.js.
    • Erw\u00e4gen Sie die Protokollierung in pc_ai_logs f\u00fcr Analysen.

  • Benutzerdefinierte Integrationen:

    • Verwenden Sie Pulsechat_model f\u00fcr DB-Operationen statt direktes SQL zu schreiben.
    • Verwenden Sie bestehende Hilfsmittel (z.B. ContactMatcher) wieder, um doppelte Logik zu vermeiden.
tipp

PulseChat st\u00fctzt sich stark auf Perfex-Hooks und App_Controller-Verhalten; folgen Sie diesen Mustern, um mit Kern-Updates kompatibel zu bleiben. F\u00fcgen Sie f\u00fcr Schema\u00e4nderungen immer eine Migration hinzu, anstatt nur install.php zu \u00e4ndern.