Journal

1. Wofuer ist diese Funktion

Das Journal ist das zentrale Aktivitaetsprotokoll von Octoserv. Es zeichnet saemtliche Vorgaenge im CRM-System auf und stellt sie in einer durchsuchbaren, filterbaren Zeitleiste dar. Jede Aenderung an Kontakten, Tags, Feldern, Aufgaben und E-Mails wird automatisch erfasst -- sowohl durch Octoserv-eigene Aktionen als auch durch das zugrunde liegende CRM-System (Groundhogg).

Das Journal existiert in zwei Auspraegungen:

Globale Journal-Uebersicht: Eine systemweite Ansicht aller Aktivitaeten ueber alle Kontakte hinweg, erreichbar ueber den Navigationspunkt "Journal".
Kontakt-Journal: Eine kontaktbezogene Timeline auf der Kontakt-Detailseite, die nur die Aktivitaeten des jeweiligen Kontakts zeigt.

Screenshot: Globale Journal-Uebersicht mit Statistik-Kacheln und Filtern

Wird in einer zukünftigen Version ergänzt

2. Ziel und Vorteil

Lueckenlose Nachvollziehbarkeit: Jede Aenderung im System wird protokolliert. Wer hat wann was geaendert? Das Journal beantwortet diese Frage zuverlaessig.
Schnelle Fehlersuche: Bei Problemen mit Kontaktdaten oder Prozessen laesst sich anhand des Journals exakt nachverfolgen, welche Aktionen zu einem bestimmten Zustand gefuehrt haben.
Vertriebstransparenz: Manager koennen die Aktivitaeten aller Mitarbeiter im Ueberblick sehen -- welche Kontakte bearbeitet wurden, welche E-Mails versendet wurden, welche Tags gesetzt wurden.
Zwei parallele Systeme fuer maximale Sicherheit: Octoserv fuehrt sowohl ein eigenes Datenbank-Journal (schnelle Abfragen, filterbar) als auch ein dateibasiertes Audit-Log (DCS Logger, unverfaelschbar). Beide Systeme werden automatisch synchronisiert.
CSV-Export: Alle Journal-Eintraege koennen als CSV exportiert werden -- sowohl global als auch pro Kontakt.

3. Detaillierte Funktionsbeschreibung

3.1 Architektur: Zwei parallele Systeme

Das Journal-System besteht aus drei Komponenten:

Octoserv Journal (Datenbank): Speichert Aktivitaeten in der MySQL-Tabelle wp_octo_journal. Optimiert fuer schnelle SQL-Abfragen und Timeline-Darstellung. Wird direkt durch Octoserv-Aktionen (Kampagnen-Toggles, Tasks, Owner-Aenderungen) und durch den Groundhogg-Tracker befuellt.
DCS Logger (Logdatei): Ein eigenstaendiges Plugin, das ALLE Groundhogg-Aktivitaeten in Textdateien protokolliert (/wp-content/uploads/dcs-logs/contact-activity-YYYY-MM.log). Dient als unverfaelschbare Audit-Spur.
Logger-Sync: Ein stuendlicher Cronjob importiert neue Eintraege aus den DCS-Logger-Dateien in die Octoserv-Journal-Datenbank. Dabei werden Duplikate ueber ein +/-5-Sekunden-Zeitfenster erkannt und uebersprungen.

3.2 Erfasste Aktivitaetstypen

Aktivitaetstyp	Beschreibung	Farbcode
`field_change`	Standard-Feld geaendert (Name, E-Mail, etc.)	Blau
`custom_field_change`	Custom Field geaendert	Violett
`owner_change`	Verantwortlicher/Owner geaendert	Lila
`email_sent`	E-Mail an Kontakt versendet	Gruen
`task_created`	Neue Aufgabe erstellt	Gelb
`task_completed`	Aufgabe als erledigt markiert	Hellgruen
`tag_added`	Tag dem Kontakt hinzugefuegt	Tuerkis
`tag_removed`	Tag vom Kontakt entfernt	Rot
`note_added`	Notiz zum Kontakt hinzugefuegt	Indigo
`contact_created`	Neuer Kontakt angelegt	Teal
`contact_deleted`	Kontakt geloescht	Rot

3.3 Datenbank-Schema

Die Tabelle wp_octo_journal speichert jeden Eintrag mit folgenden Feldern:

id -- Eindeutige ID
contact_id -- Zugehoeriger Kontakt
user_id -- Benutzer, der die Aenderung durchgefuehrt hat (NULL bei Systemaktionen)
activity_type -- Typ der Aktivitaet (siehe Tabelle oben)
field_name -- Name des geaenderten Feldes (bei Feldaenderungen)
old_value -- Alter Wert
new_value -- Neuer Wert
description -- Textuelle Beschreibung der Aenderung
ip_address -- IP-Adresse des ausfuehrenden Benutzers (optional)
user_agent -- Browser-Information (optional)
date_created -- Zeitstempel der Aenderung

Indizes auf contact_id, activity_type und date_created sorgen fuer performante Abfragen.

3.4 Deduplizierung

Das System verwendet zwei Deduplizierungsmechanismen:

Request-Hash: Innerhalb eines einzelnen PHP-Requests wird ueber einen Hash aus contact_id + activity_type + field_name sichergestellt, dass identische Eintraege nicht doppelt geschrieben werden.
Zeitfenster-Pruefung beim Sync: Beim Import aus dem DCS Logger wird geprueft, ob innerhalb eines +/-5-Sekunden-Zeitfensters bereits ein identischer Eintrag existiert. Falls ja, wird der Import uebersprungen.

Screenshot: Journal-Timeline mit farbcodierten Aktivitaetstypen

Wird in einer zukünftigen Version ergänzt

3.5 Automatisches Cleanup und Archivierung

Ein taeglicher Cronjob (um 3 Uhr) fuehrt folgende Bereinigungen durch:

Journal-Eintraege aelter als 90 Tage werden in die Archiv-Tabelle wp_octo_journal_archive verschoben.
Archiv-Eintraege aelter als 1 Jahr werden endgueltig geloescht.
DCS-Logger-Dateien bleiben dauerhaft erhalten (Audit-Trail).

3.6 Timestamp-Formatierung

Unix-Timestamps in Journal-Beschreibungen werden automatisch in lesbares deutsches Datumsformat (DD.MM.YYYY HH:MM:SS) umgewandelt. Das betrifft Felder wie Last sent, last_login, date_created und date_optin_status_changed.

3.7 Irrelevante Eintraege

Die globale Journal-Suche filtert automatisch irrelevante Eintraege heraus, darunter:

Interne Tracking-Felder (z.B. octo_contact_views, happyfiles_open_ids)
Leere oder nur aus "-" bestehende Beschreibungen
Interne Plugin-Metadaten (z.B. Google SiteKit Tokens, Media Library Modi)
Array-Werte als Beschreibung

4. Benutzerdokumentation / Anwendung

4.1 Globale Journal-Uebersicht aufrufen

Klicken Sie in der Seitennavigation auf Journal.
Die Seite zeigt vier Statistik-Kacheln: Gesamt-Eintraege, Heute, Letzte 7 Tage, Letzte 30 Tage.
Darunter befindet sich der Bereich "Suche & Filter" mit den Ergebnissen.

4.2 Journal filtern

Im Filterbereich stehen folgende Moeglichkeiten zur Verfuegung:

Kontakt: Tippen Sie mindestens 3 Zeichen ein, um einen Kontakt per Autocomplete zu suchen (Name oder E-Mail). Waehlen Sie den gewuenschten Kontakt aus der Vorschlagsliste.
Beschreibung: Freitextsuche in der Beschreibung, den Feldnamen und den alten/neuen Werten.
Aktivitaetstyp: Dropdown mit allen vorhandenen Typen und deren Anzahl.
Von Datum / Bis Datum: Datumsfilter fuer einen bestimmten Zeitraum.

Klicken Sie auf Suchen, um die Filter anzuwenden. Der Button Zuruecksetzen entfernt alle Filter.

4.3 CSV-Export

Klicken Sie auf den blauen Button CSV Export rechts neben den Filteroptionen. Der Export beruecksichtigt die aktuell gesetzten Filter und ist auf maximal 10.000 Eintraege begrenzt. Die CSV-Datei enthaelt die Spalten: Datum, Kontakt-ID, Kontakt Name, E-Mail, Aktivitaet, Beschreibung, Feld, Alt, Neu, Benutzer.

4.4 Kontakt-Journal (auf der Kontakt-Detailseite)

Auf der Detailseite jedes Kontakts befindet sich eine Journal-Box mit einer Timeline-Darstellung:

Die Eintraege werden chronologisch angezeigt (neueste zuerst).
Jeder Eintrag zeigt Titel, Beschreibung, alte/neue Werte und den ausfuehrenden Benutzer.
Relative Zeitangaben wie "vor 2 Stunden" erleichtern die Einordnung.
Ueber den Filter-Button koennen Aktivitaetstyp und Zeitraum eingeschraenkt werden.
Der Button "Mehr laden" laedt aeltere Eintraege nach (jeweils 50 Stueck).
Ein CSV-Export ist auch auf Kontakt-Ebene moeglich.

Screenshot: Kontakt-Journal mit Timeline und Filteroptionen

Wird in einer zukünftigen Version ergänzt

4.5 Paginierung

Die globale Ansicht zeigt 50 Eintraege pro Seite. Unterhalb der Tabelle werden die aktuelle Seite und die Gesamtzahl der Seiten angezeigt. Mit den Buttons "Zurueck" und "Weiter" navigieren Sie durch die Seiten.

4.6 Journal-Einstellungen

In den Systemeinstellungen koennen folgende Journal-Parameter konfiguriert werden:

Aufbewahrungsdauer (Tage): Wie lange Eintraege in der aktiven Tabelle verbleiben (Standard: 90 Tage).
Archiv-Aufbewahrungsdauer: Wie lange archivierte Eintraege aufbewahrt werden (Standard: 365 Tage).
Loeschbenachrichtigungen: Ob bei automatischen Bereinigungen eine E-Mail-Benachrichtigung versendet wird.
IP-Adresse speichern: Ob die IP-Adresse des Benutzers mitprotokolliert wird.
User-Agent speichern: Ob der Browser/Client des Benutzers mitprotokolliert wird.

5. Anwendungsbeispiele

Beispiel 1: "Wer hat den Status dieses Kontakts geaendert?"

Oeffnen Sie die Kontakt-Detailseite des betreffenden Kontakts.
Scrollen Sie zur Journal-Box.
Setzen Sie den Filter auf Aktivitaetstyp "Feldaenderung".
Suchen Sie nach dem Eintrag mit dem Feld "status". Dort sehen Sie den alten und neuen Wert sowie den Benutzer, der die Aenderung durchgefuehrt hat.

Beispiel 2: "Welche E-Mails wurden heute versendet?"

Oeffnen Sie die globale Journal-Uebersicht.
Setzen Sie den Aktivitaetstyp-Filter auf "email_sent".
Setzen Sie "Von Datum" auf das heutige Datum.
Klicken Sie auf "Suchen".
Die Ergebnisliste zeigt alle heute versendeten E-Mails mit Kontakt, Beschreibung und Absender.

Beispiel 3: "Alle Aktivitaeten eines bestimmten Kontakts exportieren"

Oeffnen Sie die globale Journal-Uebersicht.
Geben Sie im Feld "Kontakt" den Namen oder die E-Mail-Adresse ein.
Waehlen Sie den Kontakt aus der Vorschlagsliste.
Optional: Schraenken Sie den Zeitraum ein.
Klicken Sie auf "CSV Export". Die Datei enthaelt alle passenden Eintraege.

Beispiel 4: "Ueberblick ueber Tag-Aenderungen der letzten Woche"

Oeffnen Sie die globale Journal-Uebersicht.
Setzen Sie den Aktivitaetstyp-Filter auf "tag_added" oder "tag_removed".
Setzen Sie "Von Datum" auf vor 7 Tagen.
Die Statistik-Kachel "Letzte 7 Tage" zeigt zusaetzlich die Gesamtanzahl aller Aktivitaeten in diesem Zeitraum.

Screenshot: CSV-Export und Filteroptionen in der Journal-Uebersicht

Wird in einer zukünftigen Version ergänzt

Beispiel 5: "Journal fuer Compliance-Zwecke archivieren"

Das System archiviert automatisch:

Aktive Journal-Eintraege werden nach 90 Tagen in die Archiv-Tabelle verschoben.
Archiv-Eintraege werden nach 1 Jahr geloescht.
Die DCS-Logger-Dateien (/wp-content/uploads/dcs-logs/) bleiben permanent erhalten und dienen als vollstaendiger, unverfaelschbarer Audit-Trail. Diese Dateien koennen zu Compliance-Zwecken gesichert und externen Pruefern zur Verfuegung gestellt werden.