Add 'pending_sync' status to syncStatus in CAIKnowledge and CAdvowareAkten entities; update tooltips and API documentation

Add 'syncedHash' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps
Add 'aktivierungsstatus' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps
2026-03-11 22:05:27 +01:00 · 2026-03-11 21:53:35 +01:00 · 2026-03-11 21:49:02 +01:00
15 changed files with 388 additions and 39 deletions
--- a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json
+++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json
@@ -9,9 +9,11 @@
        "datenbankId": "Datenbank-ID",
        "syncStatus": "Sync-Status",
        "lastSync": "Letzte Synchronisation",
+        "aktivierungsstatus": "Aktivierungsstatus",
        "dokumenteAiDocumentId": "AI Document ID",
        "dokumenteSyncstatus": "Sync-Status",
-        "dokumenteLastSync": "Letzter Sync"
+        "dokumenteLastSync": "Letzter Sync",
+        "dokumenteSyncedHash": "Sync-Hash"
    },
    "links": {
        "dokumentes": "Dokumente",
@@ -21,7 +23,14 @@
    "options": {
        "syncStatus": {
            "synced": "Synchronisiert",
-            "unclean": "Nicht synchronisiert"
+            "unclean": "Nicht synchronisiert",
+            "pending_sync": "Synchronisierung ausstehend"
+        },
+        "aktivierungsstatus": {
+            "new": "Neu",
+            "active": "Aktiv",
+            "paused": "Pausiert",
+            "deactivated": "Deaktiviert"
        },
        "dokumenteSyncstatus": {
            "new": "Neu",
@@ -32,8 +41,9 @@
        }
    },
    "tooltips": {
-        "syncStatus": "Globaler Synchronisationsstatus: synced = Alle Dokumente synchronisiert, unclean = Mindestens ein Dokument ist neu oder hat Änderungen. Wird automatisch basierend auf den Dokumenten-Status aktualisiert.",
+        "syncStatus": "Globaler Synchronisationsstatus: synced = Alle Dokumente synchronisiert, unclean = Mindestens ein Dokument ist neu oder hat Änderungen, pending_sync = Synchronisierung wurde gestartet aber noch nicht abgeschlossen. Wird automatisch basierend auf den Dokumenten-Status aktualisiert.",
        "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation aller Dokumente",
+        "aktivierungsstatus": "Aktivierungsstatus des AI Knowledge Entries: new = Neu angelegt, active = Aktiv synchronisiert, paused = Synchronisation pausiert, deactivated = Synchronisation deaktiviert",
        "datenbankId": "Eindeutige ID in der AI-Datenbank"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json
+++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json
@@ -10,7 +10,8 @@
        "cDokumenteId": "Dokument ID",
        "aiDocumentId": "AI Dokument-ID",
        "syncstatus": "Sync-Status",
-        "lastSync": "Letzte Synchronisation"
+        "lastSync": "Letzte Synchronisation",
+        "syncedHash": "Sync-Hash"
    },
    "options": {
        "syncstatus": {
@@ -24,6 +25,7 @@
    "tooltips": {
        "aiDocumentId": "Externe AI-Dokument-Referenz-ID",
        "syncstatus": "Status der Synchronisation mit externem AI-System",
-        "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation"
+        "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation",
+        "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json
+++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json
@@ -17,20 +17,30 @@
        "aktenpfad": "Aktenpfad (Windows)",
        "syncStatus": "Sync-Status",
        "lastSync": "Letzte Synchronisation",
+        "aktivierungsstatus": "Aktivierungsstatus",
        "dokumentes": "Dokumente",
        "dokumenteHnr": "HNR",
        "dokumenteSyncstatus": "Sync-Status",
-        "dokumenteLastSync": "Letzter Sync"
+        "dokumenteLastSync": "Letzter Sync",
+        "dokumenteSyncedHash": "Sync-Hash"
    },
    "options": {
        "syncStatus": {
            "synced": "Synchronisiert",
-            "unclean": "Nicht synchronisiert"
+            "unclean": "Nicht synchronisiert",
+            "pending_sync": "Synchronisierung ausstehend"
+        },
+        "aktivierungsstatus": {
+            "new": "Neu",
+            "active": "Aktiv",
+            "paused": "Pausiert",
+            "deactivated": "Deaktiviert"
        }
    },
    "tooltips": {
-        "syncStatus": "Globaler Synchronisationsstatus: synced = Alle Dokumente synchronisiert, unclean = Mindestens ein Dokument ist neu oder hat Änderungen. Wird automatisch basierend auf den Dokumenten-Status aktualisiert.",
+        "syncStatus": "Globaler Synchronisationsstatus: synced = Alle Dokumente synchronisiert, unclean = Mindestens ein Dokument ist neu oder hat Änderungen, pending_sync = Synchronisierung wurde gestartet aber noch nicht abgeschlossen. Wird automatisch basierend auf den Dokumenten-Status aktualisiert.",
        "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation aller Dokumente",
+        "aktivierungsstatus": "Aktivierungsstatus der Akte: new = Neu angelegt, active = Aktiv synchronisiert, paused = Synchronisation pausiert, deactivated = Synchronisation deaktiviert",
        "aktenpfad": "Windows-Dateipfad zur Akte in Advoware"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json
+++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json
@@ -10,6 +10,7 @@
        "cDokumenteId": "Dokument ID",
        "hnr": "HNR",
        "syncStatus": "Sync-Status",
+        "syncedHash": "Sync-Hash",
        "deleted": "Gelöscht"
    },
    "links": {
@@ -26,6 +27,7 @@
    },
    "tooltips": {
        "hnr": "Advoware HNR Referenz für dieses Dokument",
-        "syncStatus": "Synchronisierungsstatus mit Advoware"
+        "syncStatus": "Synchronisierungsstatus mit Advoware",
+        "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json
+++ b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json
@@ -6,9 +6,11 @@
        "datenbankId": "Database ID",
        "syncStatus": "Sync Status",
        "lastSync": "Last Synchronization",
+        "aktivierungsstatus": "Activation Status",
        "dokumenteAiDocumentId": "AI Document ID",
        "dokumenteSyncstatus": "Sync Status",
-        "dokumenteLastSync": "Last Sync"
+        "dokumenteLastSync": "Last Sync",
+        "dokumenteSyncedHash": "Sync Hash"
    },
    "links": {
        "dokumentes": "Dokumente",
@@ -21,7 +23,14 @@
    "options": {
        "syncStatus": {
            "synced": "Synchronized",
-            "unclean": "Not Synchronized"
+            "unclean": "Not Synchronized",
+            "pending_sync": "Synchronization Pending"
+        },
+        "aktivierungsstatus": {
+            "new": "New",
+            "active": "Active",
+            "paused": "Paused",
+            "deactivated": "Deactivated"
        },
        "dokumenteSyncstatus": {
            "new": "New",
@@ -32,8 +41,9 @@
        }
    },
    "tooltips": {
-        "syncStatus": "Global synchronization status: synced = All documents synchronized, unclean = At least one document is new or has changes. Updated automatically based on document status.",
+        "syncStatus": "Global synchronization status: synced = All documents synchronized, unclean = At least one document is new or has changes, pending_sync = Synchronization started but not yet completed. Updated automatically based on document status.",
        "lastSync": "Timestamp of the last successful synchronization of all documents",
+        "aktivierungsstatus": "Activation status of the AI Knowledge entry: new = Newly created, active = Actively synchronized, paused = Synchronization paused, deactivated = Synchronization deactivated",
        "datenbankId": "Unique ID in the AI database"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json
+++ b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json
@@ -10,7 +10,8 @@
        "cDokumenteId": "Document ID",
        "aiDocumentId": "AI Document ID",
        "syncstatus": "Sync Status",
-        "lastSync": "Last Sync"
+        "lastSync": "Last Synchronization",
+        "syncedHash": "Sync Hash"
    },
    "options": {
        "syncstatus": {
@@ -24,6 +25,7 @@
    "tooltips": {
        "aiDocumentId": "External AI document reference ID",
        "syncstatus": "Synchronization status with external AI system",
-        "lastSync": "Timestamp of last successful synchronization"
+        "lastSync": "Timestamp of the last successful synchronization",
+        "syncedHash": "Hash value of the last synchronized document state (for change detection)"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json
+++ b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json
@@ -7,10 +7,12 @@
        "aktenpfad": "File Path (Windows)",
        "syncStatus": "Sync Status",
        "lastSync": "Last Synchronization",
+        "aktivierungsstatus": "Activation Status",
        "dokumentes": "Dokumente",
        "dokumenteHnr": "HNR",
        "dokumenteSyncstatus": "Sync Status",
-        "dokumenteLastSync": "Last Sync"
+        "dokumenteLastSync": "Last Sync",
+        "dokumenteSyncedHash": "Sync Hash"
    },
    "links": {
        "meetings": "Meetings",
@@ -26,12 +28,20 @@
    "options": {
        "syncStatus": {
            "synced": "Synchronized",
-            "unclean": "Not Synchronized"
+            "unclean": "Not Synchronized",
+            "pending_sync": "Synchronization Pending"
+        },
+        "aktivierungsstatus": {
+            "new": "New",
+            "active": "Active",
+            "paused": "Paused",
+            "deactivated": "Deactivated"
        }
    },
    "tooltips": {
-        "syncStatus": "Global synchronization status: synced = All documents synchronized, unclean = At least one document is new or has changes. Updated automatically based on document status.",
+        "syncStatus": "Global synchronization status: synced = All documents synchronized, unclean = At least one document is new or has changes, pending_sync = Synchronization started but not yet completed. Updated automatically based on document status.",
        "lastSync": "Timestamp of the last successful synchronization of all documents",
+        "aktivierungsstatus": "Activation status of the file: new = Newly created, active = Actively synchronized, paused = Synchronization paused, deactivated = Synchronization deactivated",
        "aktenpfad": "Windows file path to the file in Advoware"
    }
 }
--- a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json
+++ b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json
@@ -10,6 +10,7 @@
        "cDokumenteId": "Document ID",
        "hnr": "HNR",
        "syncStatus": "Sync Status",
+        "syncedHash": "Sync Hash",
        "deleted": "Deleted"
    },
    "links": {
@@ -26,6 +27,7 @@
    },
    "tooltips": {
        "hnr": "Advoware HNR reference for this document",
-        "syncStatus": "Synchronization status with Advoware"
+        "syncStatus": "Synchronization status with Advoware",
+        "syncedHash": "Hash value of the last synchronized document state (for change detection)"
    }
 }
--- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json
+++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json
@@ -52,11 +52,13 @@
            "required": false,
            "options": [
                "synced",
-                "unclean"
+                "unclean",
+                "pending_sync"
            ],
            "style": {
                "synced": "success",
-                "unclean": "warning"
+                "unclean": "warning",
+                "pending_sync": "info"
            },
            "default": "unclean",
            "tooltip": true,
@@ -69,6 +71,25 @@
            "tooltip": true,
            "isCustom": true
        },
+        "aktivierungsstatus": {
+            "type": "enum",
+            "required": false,
+            "options": [
+                "new",
+                "active",
+                "paused",
+                "deactivated"
+            ],
+            "style": {
+                "new": "primary",
+                "active": "success",
+                "paused": "warning",
+                "deactivated": "danger"
+            },
+            "default": "new",
+            "tooltip": true,
+            "isCustom": true
+        },
        "dokumenteAiDocumentId": {
            "type": "varchar",
            "notStorable": true,
@@ -85,6 +106,11 @@
            "notStorable": true,
            "utility": true
        },
+        "dokumenteSyncedHash": {
+            "type": "varchar",
+            "notStorable": true,
+            "utility": true
+        },
        "dokumentes": {
            "type": "linkMultiple",
            "layoutDetailDisabled": false,
@@ -97,7 +123,8 @@
            "columns": {
                "aiDocumentId": "aiKnowledgeAiDocumentId",
                "syncstatus": "aiKnowledgeSyncstatus",
-                "lastSync": "aiKnowledgeLastSync"
+                "lastSync": "aiKnowledgeLastSync",
+                "syncedHash": "aiKnowledgeSyncedHash"
            },
            "additionalAttributeList": [
                "columns"
--- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json
+++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json
@@ -54,6 +54,12 @@
            "isCustom": true,
            "tooltip": true
        },
+        "syncedHash": {
+            "type": "varchar",
+            "len": 64,
+            "isCustom": true,
+            "tooltip": true
+        },
        "deleted": {
            "type": "bool",
            "default": false
--- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json
+++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json
@@ -67,11 +67,13 @@
            "required": false,
            "options": [
                "synced",
-                "unclean"
+                "unclean",
+                "pending_sync"
            ],
            "style": {
                "synced": "success",
-                "unclean": "warning"
+                "unclean": "warning",
+                "pending_sync": "info"
            },
            "default": "unclean",
            "tooltip": true,
@@ -84,6 +86,25 @@
            "tooltip": true,
            "isCustom": true
        },
+        "aktivierungsstatus": {
+            "type": "enum",
+            "required": false,
+            "options": [
+                "new",
+                "active",
+                "paused",
+                "deactivated"
+            ],
+            "style": {
+                "new": "primary",
+                "active": "success",
+                "paused": "warning",
+                "deactivated": "danger"
+            },
+            "default": "new",
+            "tooltip": true,
+            "isCustom": true
+        },
        "dokumenteHnr": {
            "type": "int",
            "notStorable": true,
@@ -100,6 +121,11 @@
            "notStorable": true,
            "utility": true
        },
+        "dokumenteSyncedHash": {
+            "type": "varchar",
+            "notStorable": true,
+            "utility": true
+        },
        "dokumentes": {
            "type": "linkMultiple",
            "layoutDetailDisabled": false,
@@ -112,7 +138,8 @@
            "columns": {
                "hnr": "advowareAktenHnr",
                "syncstatus": "advowareAktenSyncstatus",
-                "lastSync": "advowareAktenLastSync"
+                "lastSync": "advowareAktenLastSync",
+                "syncedHash": "advowareAktenSyncedHash"
            },
            "additionalAttributeList": [
                "columns"
--- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json
+++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json
@@ -46,6 +46,12 @@
            "isCustom": true,
            "tooltip": true
        },
+        "syncedHash": {
+            "type": "varchar",
+            "len": 64,
+            "isCustom": true,
+            "tooltip": true
+        },
        "deleted": {
            "type": "bool",
            "default": false
--- a/custom/docs/API_ENDPOINTS.md
+++ b/custom/docs/API_ENDPOINTS.md
@@ -1,9 +1,15 @@
 # REST API Endpunkte - EspoCRM Custom Entities

-**Version:** 1.0  
+**Version:** 1.3  
 **Datum:** 11. März 2026  
 **Base URL:** `https://your-crm.com/api/v1`

+**Changelog:**
+- v1.3 (11. März 2026): pending_sync Status zu globalem syncStatus hinzugefügt
+- v1.2 (11. März 2026): syncedHash-Feld zu Junction-Tables hinzugefügt
+- v1.1 (11. März 2026): Aktivierungsstatus-Feld hinzugefügt (new, active, paused, deactivated)
+- v1.0 (11. März 2026): Initiale Version
+
 ---

 ## 🔐 Authentifizierung
@@ -63,6 +69,7 @@ GET /api/v1/CAdvowareAkten
      "aktenzeichen": "123/2026",
      "aktennummer": 123,
      "aktenpfad": "/advoware/2026/001",
+      "aktivierungsstatus": "new",
      "syncStatus": "unclean",
      "lastSync": null,
      "createdAt": "2026-03-11 10:00:00",
@@ -85,6 +92,7 @@ GET /api/v1/CAdvowareAkten/{id}
  "aktenzeichen": "123/2026",
  "aktennummer": 123,
  "aktenpfad": "/advoware/2026/001",
+  "aktivierungsstatus": "new",
  "syncStatus": "unclean",
  "lastSync": null,
  "vmhRumungsklageId": "64e3f8a1234ab",
@@ -104,6 +112,7 @@ Content-Type: application/json
  "aktenzeichen": "124/2026",
  "aktennummer": 124,
  "aktenpfad": "/advoware/2026/002",
+  "aktivierungsstatus": "new",
  "syncStatus": "unclean"
 }
 ```
@@ -121,6 +130,7 @@ PUT /api/v1/CAdvowareAkten/{id}
 Content-Type: application/json

 {
+  "aktivierungsstatus": "active",
  "syncStatus": "synced",
  "lastSync": "2026-03-11T20:00:00+00:00"
 }
@@ -211,11 +221,27 @@ GET /api/v1/CAdvowareAkten/{id}/mietinkasso

 ### Filterung & Suche

+#### Nach aktivierungsstatus filtern
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=new
+```
+
+**Verfügbare Werte:**
+- `new` - Neu angelegt (Standard, blaue Badge)
+- `active` - Aktiv synchronisiert (grüne Badge)
+- `paused` - Synchronisation pausiert (gelbe Badge)
+- `deactivated` - Synchronisation deaktiviert (rote Badge)
+
 #### Nach syncStatus filtern
 ```http
 GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
 ```

+**Verfügbare Werte:**
+- `synced` - Alle Dokumente synchronisiert (grüne Badge)
+- `unclean` - Mindestens ein Dokument neu oder geändert (gelbe Badge)
+- `pending_sync` - Synchronisierung läuft (blaue Badge)
+
 #### Nach Aktenzeichen suchen
 ```http
 GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=aktenzeichen&where[0][value]=2026
@@ -228,7 +254,7 @@ GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&

 #### Nur bestimmte Felder
 ```http
-GET /api/v1/CAdvowareAkten?select=name,aktenzeichen,syncStatus,lastSync
+GET /api/v1/CAdvowareAkten?select=id,name,aktivierungsstatus,syncStatus,lastSync
 ```

 #### Mit Sortierung
@@ -258,6 +284,7 @@ GET /api/v1/CAIKnowledge
      "id": "kb-123",
      "name": "Knowledge Base 2026-001",
      "datenbankId": "kb-external-123",
+      "aktivierungsstatus": "active",
      "syncStatus": "synced",
      "lastSync": "2026-03-11 19:00:00",
      "createdAt": "2026-03-10 10:00:00"
@@ -279,6 +306,7 @@ Content-Type: application/json
 {
  "name": "Knowledge Base 2026-002",
  "datenbankId": "kb-external-456",
+  "aktivierungsstatus": "new",
  "syncStatus": "unclean"
 }
 ```
@@ -289,6 +317,7 @@ PUT /api/v1/CAIKnowledge/{id}
 Content-Type: application/json

 {
+  "aktivierungsstatus": "active",
  "syncStatus": "synced",
  "lastSync": "2026-03-11T20:00:00+00:00"
 }
@@ -330,6 +359,17 @@ DELETE /api/v1/CAIKnowledge/{id}/dokumentes/{dokumentId}

 ### Filterung & Suche

+#### Nach aktivierungsstatus filtern
+```http
+GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active
+```
+
+**Verfügbare Werte:**
+- `new` - Neu angelegt (Standard, blaue Badge)
+- `active` - Aktiv synchronisiert (grüne Badge)
+- `paused` - Synchronisation pausiert (gelbe Badge)
+- `deactivated` - Synchronisation deaktiviert (rote Badge)
+
 #### Nach datenbankId suchen
 ```http
 GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=datenbankId&where[0][value]=kb-123
@@ -340,6 +380,11 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=datenbankId&w
 GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
 ```

+**Verfügbare syncStatus Werte:**
+- `synced` - Alle Dokumente synchronisiert (grüne Badge)
+- `unclean` - Mindestens ein Dokument neu oder geändert (gelbe Badge)
+- `pending_sync` - Synchronisierung läuft (blaue Badge)
+
 ---

 ## Junction Tables
@@ -353,6 +398,7 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&wh
 - `cDokumenteId` - ID des Dokuments
 - `hnr` - Advoware HNR-Referenz (varchar, 255)
 - `syncStatus` - Sync-Status (enum: new, changed, synced, deleted)
+- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
 - `deleted` - Soft-Delete Flag

 #### Alle Junction-Einträge
@@ -371,6 +417,7 @@ GET /api/v1/CAdvowareAktenCDokumente
      "cDokumenteId": "dok-456",
      "hnr": "42",
      "syncStatus": "synced",
+      "syncedHash": "a3f5c8b9e2d1...",
      "deleted": false
    },
    {
@@ -379,6 +426,7 @@ GET /api/v1/CAdvowareAktenCDokumente
      "cDokumenteId": "dok-789",
      "hnr": "43",
      "syncStatus": "new",
+      "syncedHash": null,
      "deleted": false
    }
  ]
@@ -405,7 +453,8 @@ GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=c
      "cAdvowareAktenId": "akte-123",
      "cDokumenteId": "dok-456",
      "hnr": "42",
-      "syncStatus": "synced"
+      "syncStatus": "synced",
+      "syncedHash": "a3f5c8b9e2d1..."
    }
  ]
 }
@@ -430,7 +479,8 @@ Content-Type: application/json
  "cAdvowareAktenId": "akte-123",
  "cDokumenteId": "dok-999",
  "hnr": "50",
-  "syncStatus": "new"
+  "syncStatus": "new",
+  "syncedHash": null
 }
 ```

@@ -448,6 +498,7 @@ Content-Type: application/json

 {
  "syncStatus": "synced",
+  "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4",
  "hnr": "51"
 }
 ```
@@ -469,6 +520,7 @@ DELETE /api/v1/CAdvowareAktenCDokumente/{id}
 - `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255)
 - `syncstatus` - Sync-Status (enum: new, unclean, synced, failed, unsupported)
 - `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
+- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
 - `deleted` - Soft-Delete Flag

 #### Alle Junction-Einträge
@@ -488,6 +540,7 @@ GET /api/v1/CAIKnowledgeCDokumente
      "aiDocumentId": "ai-doc-external-789",
      "syncstatus": "synced",
      "lastSync": "2026-03-11 19:00:00",
+      "syncedHash": "b4e2a9c7f3d8...",
      "deleted": false
    }
  ]
@@ -518,7 +571,8 @@ Content-Type: application/json
  "cAIKnowledgeId": "kb-123",
  "cDokumenteId": "dok-999",
  "aiDocumentId": "ai-doc-new-123",
-  "syncstatus": "new"
+  "syncstatus": "new",
+  "syncedHash": null
 }
 ```

@@ -529,7 +583,8 @@ Content-Type: application/json

 {
  "syncstatus": "synced",
-  "lastSync": "2026-03-11T20:30:00+00:00"
+  "lastSync": "2026-03-11T20:30:00+00:00",
+  "syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3"
 }
 ```

@@ -648,7 +703,7 @@ GET /api/v1/CAdvowareAkten?select=id,name,syncStatus,lastSync
 ### Beispiel 1: Alle unsynchronisierten Akten mit Details

 ```bash
-curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&select=id,name,aktenzeichen,syncStatus&orderBy=createdAt&order=desc" \
+curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&select=id,name,aktenzeichen,aktivierungsstatus,syncStatus&orderBy=createdAt&order=desc" \
  -H "X-Api-Key: your-api-key"
 ```

@@ -660,7 +715,7 @@ curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
  -H "X-Api-Key: your-api-key"

 # Schritt 2: Hole Junction-Einträge mit HNR
-curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus" \
+curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus,syncedHash" \
  -H "X-Api-Key: your-api-key"
 ```

@@ -675,7 +730,8 @@ curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
    "cAdvowareAktenId": "akte-123",
    "cDokumenteId": "dok-789",
    "hnr": "42",
-    "syncStatus": "new"
+    "syncStatus": "new",
+    "syncedHash": null
  }'
 ```

@@ -691,7 +747,8 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_I
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
-    "syncStatus": "synced"
+    "syncStatus": "synced",
+    "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4"
  }'

 # Schritt 3: Update global status (optional, Hooks machen das automatisch)
@@ -699,6 +756,7 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
+    "aktivierungsstatus": "active",
    "syncStatus": "synced",
    "lastSync": "2026-03-11T20:00:00+00:00"
  }'
@@ -718,14 +776,191 @@ curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type

 ```bash
 # Finde alle Junction-Einträge die "new" oder "changed" sind
-curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus" \
+curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus,syncedHash" \
  -H "X-Api-Key: your-api-key"
 ```

+### Beispiel 7: Alle aktiven Akten abrufen
+
+```bash
+# Finde alle Akten die aktiv synchronisiert werden
+curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active&select=id,name,aktenzeichen,aktivierungsstatus,syncStatus" \
+  -H "X-Api-Key: your-api-key"
+```
+
+### Beispiel 8: Akte von "new" auf "active" setzen
+
+```bash
+# Aktiviere eine neu angelegte Akte
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "aktivierungsstatus": "active"
+  }'
+```
+
+### Beispiel 9: Synchronisations-Workflow mit pending_sync
+
+```bash
+# Schritt 1: Hole alle Akten mit Status "unclean" die synchronisiert werden müssen
+AKTEN=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&where[1][type]=equals&where[1][attribute]=aktivierungsstatus&where[1][value]=active" \
+  -H "X-Api-Key: your-api-key")
+
+# Schritt 2: Setze Status auf "pending_sync" vor Synchronisation
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "syncStatus": "pending_sync"
+  }'
+
+# Schritt 3: Führe Synchronisation durch...
+# (Hole Junction-Einträge, synchronisiere mit Advoware, etc.)
+
+# Schritt 4: Nach erfolgreicher Synchronisation
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "syncStatus": "synced",
+    "lastSync": "2026-03-11T20:00:00+00:00"
+  }'
+
+# Schritt 5: Bei Fehler während Synchronisation
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "syncStatus": "unclean"
+  }'
+```
+
 ---

 ## 🎯 Wichtige Hinweise

+### syncedHash - Änderungserkennung
+
+**Zweck:** Hash-basierte Versionierung zur Erkennung von Dokumentänderungen zwischen Synchronisationen
+
+**Verwendung:**
+```bash
+# 1. Nach erfolgreicher Synchronisation: Hash berechnen und speichern
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/123" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "syncStatus": "synced",
+    "syncedHash": "sha256:a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
+  }'
+
+# 2. Bei nächster Synchronisation: Aktuellen Hash mit syncedHash vergleichen
+# Wenn unterschiedlich → Dokument wurde geändert → syncStatus = "changed"
+```
+
+**Hash-Berechnung:**
+```python
+import hashlib
+
+# Beispiel: Hash aus Dokument-Metadaten berechnen
+def calculate_document_hash(document):
+    content = f"{document['name']}|{document['modifiedAt']}|{document['size']}"
+    return hashlib.sha256(content.encode()).hexdigest()
+```
+
+**Workflow:**
+1. **Initial Sync:** syncedHash = NULL, syncStatus = "new"
+2. **Sync durchgeführt:** syncedHash = berechnet, syncStatus = "synced"
+3. **Dokument geändert:** Hook setzt syncStatus = "unclean"
+4. **Nächster Sync:** Vergleiche aktuellen Hash mit syncedHash
+   - Gleich → Keine Änderung, skip
+   - Unterschiedlich → Sync durchführen, neuen Hash speichern
+
+**Frontend-Anzeige:**
+Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
+- In CAdvowareAkten: Spalte "Sync-Hash" zeigt den Hash-Wert
+- In CAIKnowledge: Spalte "Sync-Hash" zeigt den Hash-Wert
+- Tooltip: "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
+
+### Aktivierungsstatus
+
+**Zweck:** Steuerung der Synchronisations-Aktivität für Akten und AI Knowledge Entries
+
+**Verfügbare Status:**
+- `new` (Standard) - Neu angelegte Einträge, noch nicht für Sync aktiviert
+- `active` - Aktiv synchronisiert, alle Sync-Prozesse laufen
+- `paused` - Synchronisation temporär pausiert, kann wieder aktiviert werden
+- `deactivated` - Synchronisation dauerhaft deaktiviert
+
+### Globaler syncStatus
+
+**Zweck:** Übersicht über den Synchronisationszustand aller Dokumente einer Akte/eines AI Knowledge Entries
+
+**Verfügbare Status:**
+- `synced` (grün) - Alle Dokumente vollständig synchronisiert
+- `unclean` (gelb) - Mindestens ein Dokument ist neu, geändert oder gelöscht
+- `pending_sync` (blau) - Synchronisierung wurde gestartet aber noch nicht abgeschlossen
+
+**Status-Übergänge:**
+```
+unclean → pending_sync (beim Start der Synchronisation)
+pending_sync → synced (nach erfolgreicher Synchronisation aller Dokumente)
+pending_sync → unclean (bei Fehler oder wenn ein Dokument während Sync geändert wurde)
+synced → unclean (wenn ein Dokument geändert/hinzugefügt/gelöscht wird)
+```
+
+**Verwendung:**
+```bash
+# 1. Vor Synchronisation: Status auf pending_sync setzen
+PUT /api/v1/CAdvowareAkten/{id} { "syncStatus": "pending_sync" }
+
+# 2. Nach erfolgreicher Synchronisation: Status auf synced setzen
+PUT /api/v1/CAdvowareAkten/{id} { 
+  "syncStatus": "synced",
+  "lastSync": "2026-03-11T20:00:00+00:00"
+}
+
+# 3. Bei Fehler: Zurück auf unclean
+PUT /api/v1/CAdvowareAkten/{id} { "syncStatus": "unclean" }
+```
+
+**Filterung:**
+```bash
+# Alle Akten die auf Synchronisation warten
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
+
+# Alle Akten bei denen gerade eine Synchronisation läuft
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=pending_sync
+
+# Alle erfolgreich synchronisierten Akten
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=synced
+```
+
+**Anwendungsfälle:**
+```bash
+# Neue Akte anlegen (automatisch status="new")
+POST /api/v1/CAdvowareAkten { "name": "...", "aktivierungsstatus": "new" }
+
+# Akte für Sync aktivieren
+PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "active" }
+
+# Sync temporär pausieren (z.B. während Wartung)
+PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "paused" }
+
+# Sync permanent deaktivieren
+PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "deactivated" }
+```
+
+**Filterung:**
+```bash
+# Nur aktive Einträge für Sync-Job
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active
+
+# Alle pausierte oder deaktivierte
+GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=aktivierungsstatus&where[0][value][0]=paused&where[0][value][1]=deactivated
+```
+
 ### Junction-Spalten via REST API

 **✅ RICHTIG:** Nutze Junction-Entity-APIs
@@ -780,6 +1015,6 @@ WHERE name = 'Your Role Name';
 ---

 **Letzte Aktualisierung:** 11. März 2026  
-**Version:** 1.0
+**Version:** 1.3

 Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
--- a/data/config.php
+++ b/data/config.php
@@ -360,7 +360,7 @@ return [
    0 => 'youtube.com',
    1 => 'google.com'
  ],
-  'microtime' => 1773259888.998412,
+  'microtime' => 1773262547.930204,
  'siteUrl' => 'https://crm.bitbylaw.com',
  'fullTextSearchMinLength' => 4,
  'webSocketUrl' => 'ws://api.bitbylaw.com:5000/espocrm/ws',
--- a/data/state.php
+++ b/data/state.php
@@ -1,7 +1,7 @@
 <?php
 return [
-  'cacheTimestamp' => 1773259889,
-  'microtimeState' => 1773259889.126431,
+  'cacheTimestamp' => 1773262548,
+  'microtimeState' => 1773262548.062426,
  'currencyRates' => [
    'EUR' => 1.0
  ],
Author	SHA1	Message	Date
bsiggel	e15dd14cab	Add 'pending_sync' status to syncStatus in CAIKnowledge and CAdvowareAkten entities; update tooltips and API documentation	2026-03-11 22:05:27 +01:00
bsiggel	54d66da52d	Add 'syncedHash' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps	2026-03-11 21:53:35 +01:00
bsiggel	ae359048af	Add 'aktivierungsstatus' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps	2026-03-11 21:49:02 +01:00