From c952fc40bc8ddd4ea89f67207c13b1baa3260da7 Mon Sep 17 00:00:00 2001
From: bsiggel <info@bitbylaw.com>
Date: Wed, 11 Mar 2026 20:48:35 +0100
Subject: [PATCH] Update configuration and state files; adjust microtime values
 and add CAIKnowledgeCDokumente junction entity with metadata and API
 documentation

---
 .../Controllers/CAIKnowledgeCDokumente.php    |  24 +
 .../i18n/de_DE/CAIKnowledgeCDokumente.json    |  28 +
 .../i18n/en_US/CAIKnowledgeCDokumente.json    |  28 +
 .../entityDefs/CAIKnowledgeCDokumente.json    |  89 ++
 .../scopes/CAIKnowledgeCDokumente.json        |  10 +
 .../Services/CAIKnowledgeCDokumente.php       |  14 +
 custom/docs/API_ENDPOINTS.md                  | 785 ++++++++++++++++++
 data/config.php                               |   2 +-
 data/state.php                                |   4 +-
 9 files changed, 981 insertions(+), 3 deletions(-)
 create mode 100644 custom/Espo/Custom/Controllers/CAIKnowledgeCDokumente.php
 create mode 100644 custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json
 create mode 100644 custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json
 create mode 100644 custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json
 create mode 100644 custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeCDokumente.json
 create mode 100644 custom/Espo/Custom/Services/CAIKnowledgeCDokumente.php
 create mode 100644 custom/docs/API_ENDPOINTS.md

diff --git a/custom/Espo/Custom/Controllers/CAIKnowledgeCDokumente.php b/custom/Espo/Custom/Controllers/CAIKnowledgeCDokumente.php
new file mode 100644
index 00000000..d187a8ff
--- /dev/null
+++ b/custom/Espo/Custom/Controllers/CAIKnowledgeCDokumente.php
@@ -0,0 +1,24 @@
+<?php
+namespace Espo\Custom\Controllers;
+
+use Espo\Core\Controllers\Record;
+
+/**
+ * Junction Controller: CAIKnowledge ↔ CDokumente
+ * 
+ * Provides REST API access to the junction table with additionalColumns:
+ * - aiDocumentId: External AI document reference
+ * - syncstatus: Sync state tracking (new, unclean, synced, failed)
+ * - lastSync: Last synchronization timestamp
+ */
+class CAIKnowledgeCDokumente extends Record
+{
+    // Inherits all CRUD operations from Record controller
+    // 
+    // Available endpoints:
+    // GET    /api/v1/CAIKnowledgeCDokumente
+    // GET    /api/v1/CAIKnowledgeCDokumente/{id}
+    // POST   /api/v1/CAIKnowledgeCDokumente
+    // PUT    /api/v1/CAIKnowledgeCDokumente/{id}
+    // DELETE /api/v1/CAIKnowledgeCDokumente/{id}
+}
diff --git a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json
new file mode 100644
index 00000000..f7a8af68
--- /dev/null
+++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json
@@ -0,0 +1,28 @@
+{
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "AI Knowledge-Dokument Verknüpfung erstellen",
+        "CAIKnowledgeCDokumente": "AI Knowledge-Dokument Verknüpfung"
+    },
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cAIKnowledgeId": "AI Knowledge ID",
+        "cDokumente": "Dokument",
+        "cDokumenteId": "Dokument ID",
+        "aiDocumentId": "AI Dokument-ID",
+        "syncstatus": "Sync-Status",
+        "lastSync": "Letzte Synchronisation"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "Neu",
+            "unclean": "Unklar",
+            "synced": "Synchronisiert",
+            "failed": "Fehlgeschlagen"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "Externe AI-Dokument-Referenz-ID",
+        "syncstatus": "Status der Synchronisation mit externem AI-System",
+        "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation"
+    }
+}
diff --git a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json
new file mode 100644
index 00000000..430f5ad9
--- /dev/null
+++ b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json
@@ -0,0 +1,28 @@
+{
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "Create AI Knowledge-Document Link",
+        "CAIKnowledgeCDokumente": "AI Knowledge-Document Link"
+    },
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cAIKnowledgeId": "AI Knowledge ID",
+        "cDokumente": "Document",
+        "cDokumenteId": "Document ID",
+        "aiDocumentId": "AI Document ID",
+        "syncstatus": "Sync Status",
+        "lastSync": "Last Sync"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "New",
+            "unclean": "Unclean",
+            "synced": "Synced",
+            "failed": "Failed"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "External AI document reference ID",
+        "syncstatus": "Synchronization status with external AI system",
+        "lastSync": "Timestamp of last successful synchronization"
+    }
+}
diff --git a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json
new file mode 100644
index 00000000..e14e780b
--- /dev/null
+++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json
@@ -0,0 +1,89 @@
+{
+    "fields": {
+        "id": {
+            "type": "id",
+            "dbType": "bigint",
+            "autoincrement": true
+        },
+        "cAIKnowledge": {
+            "type": "link"
+        },
+        "cAIKnowledgeId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "cDokumente": {
+            "type": "link"
+        },
+        "cDokumenteId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "aiDocumentId": {
+            "type": "varchar",
+            "len": 255,
+            "isCustom": true,
+            "tooltip": true
+        },
+        "syncstatus": {
+            "type": "enum",
+            "required": false,
+            "options": [
+                "new",
+                "unclean",
+                "synced",
+                "failed"
+            ],
+            "style": {
+                "new": "info",
+                "unclean": "warning",
+                "synced": "success",
+                "failed": "danger"
+            },
+            "default": "new",
+            "isCustom": true,
+            "tooltip": true
+        },
+        "lastSync": {
+            "type": "datetime",
+            "required": false,
+            "isCustom": true,
+            "tooltip": true
+        },
+        "deleted": {
+            "type": "bool",
+            "default": false
+        }
+    },
+    "links": {
+        "cAIKnowledge": {
+            "type": "belongsTo",
+            "entity": "CAIKnowledge"
+        },
+        "cDokumente": {
+            "type": "belongsTo",
+            "entity": "CDokumente"
+        }
+    },
+    "collection": {
+        "orderBy": "id",
+        "order": "desc"
+    },
+    "indexes": {
+        "cAIKnowledgeId": {
+            "columns": ["cAIKnowledgeId"]
+        },
+        "cDokumenteId": {
+            "columns": ["cDokumenteId"]
+        },
+        "syncstatus": {
+            "columns": ["syncstatus"]
+        },
+        "uniqueRelation": {
+            "type": "unique",
+            "columns": ["cAIKnowledgeId", "cDokumenteId", "deleted"]
+        }
+    }
+}
diff --git a/custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeCDokumente.json
new file mode 100644
index 00000000..f9c1f7a0
--- /dev/null
+++ b/custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeCDokumente.json
@@ -0,0 +1,10 @@
+{
+    "entity": true,
+    "type": "Base",
+    "module": "Custom",
+    "object": true,
+    "isCustom": true,
+    "tab": false,
+    "acl": true,
+    "disabled": false
+}
diff --git a/custom/Espo/Custom/Services/CAIKnowledgeCDokumente.php b/custom/Espo/Custom/Services/CAIKnowledgeCDokumente.php
new file mode 100644
index 00000000..f6606564
--- /dev/null
+++ b/custom/Espo/Custom/Services/CAIKnowledgeCDokumente.php
@@ -0,0 +1,14 @@
+<?php
+namespace Espo\Custom\Services;
+
+use Espo\Services\Record;
+
+/**
+ * Junction Service: CAIKnowledge ↔ CDokumente
+ * 
+ * Handles business logic for the junction table.
+ */
+class CAIKnowledgeCDokumente extends Record
+{
+    // Standard CRUD logic inherited from Record service
+}
diff --git a/custom/docs/API_ENDPOINTS.md b/custom/docs/API_ENDPOINTS.md
new file mode 100644
index 00000000..7d916399
--- /dev/null
+++ b/custom/docs/API_ENDPOINTS.md
@@ -0,0 +1,785 @@
+# REST API Endpunkte - EspoCRM Custom Entities
+
+**Version:** 1.0  
+**Datum:** 11. März 2026  
+**Base URL:** `https://your-crm.com/api/v1`
+
+---
+
+## 🔐 Authentifizierung
+
+Alle API-Requests benötigen einen API-Key im Header:
+
+```bash
+-H "X-Api-Key: your-api-key-here"
+-H "Content-Type: application/json"
+```
+
+**API-Key erstellen:**
+1. Admin → Users → [Your User] → API Users Tab
+2. "Create API User" → Key kopieren
+
+---
+
+## 📋 Inhaltsverzeichnis
+
+1. [CAdvowareAkten (Advoware Akten)](#cadvowareakten-advoware-akten)
+2. [CAIKnowledge (AI Knowledge Base)](#caiknowledge-ai-knowledge-base)
+3. [Junction Tables](#junction-tables)
+   - [CAdvowareAktenCDokumente](#cadvowareaktencdokumente-junction)
+   - [CAIKnowledgeCDokumente](#caiknowledgecdokumente-junction)
+4. [CDokumente (Dokumente)](#cdokumente-dokumente)
+5. [Filtering & Sorting](#filtering--sorting)
+6. [Praktische Beispiele](#praktische-beispiele)
+
+---
+
+## CAdvowareAkten (Advoware Akten)
+
+**Entity:** Verwaltung von Advoware-Akten mit Sync-Status-Tracking
+
+### Standard CRUD Operationen
+
+#### Liste aller Akten abrufen
+```http
+GET /api/v1/CAdvowareAkten
+```
+
+**Query Parameter:**
+- `maxSize` - Max. Anzahl Ergebnisse (default: 20)
+- `offset` - Offset für Pagination (default: 0)
+- `select` - Komma-separierte Feldliste
+- `orderBy` - Sortierfeld
+- `order` - `asc` oder `desc`
+
+**Response:**
+```json
+{
+  "total": 150,
+  "list": [
+    {
+      "id": "64e3f8a1b2c5d",
+      "name": "Akte 2026-001",
+      "aktenzeichen": "123/2026",
+      "aktennummer": 123,
+      "aktenpfad": "/advoware/2026/001",
+      "syncStatus": "unclean",
+      "lastSync": null,
+      "createdAt": "2026-03-11 10:00:00",
+      "modifiedAt": "2026-03-11 15:30:00"
+    }
+  ]
+}
+```
+
+#### Einzelne Akte abrufen
+```http
+GET /api/v1/CAdvowareAkten/{id}
+```
+
+**Response:**
+```json
+{
+  "id": "64e3f8a1b2c5d",
+  "name": "Akte 2026-001",
+  "aktenzeichen": "123/2026",
+  "aktennummer": 123,
+  "aktenpfad": "/advoware/2026/001",
+  "syncStatus": "unclean",
+  "lastSync": null,
+  "vmhRumungsklageId": "64e3f8a1234ab",
+  "vmhRumungsklageName": "Räumungsklage Muster",
+  "assignedUserId": "user-id",
+  "assignedUserName": "Max Mustermann"
+}
+```
+
+#### Neue Akte erstellen
+```http
+POST /api/v1/CAdvowareAkten
+Content-Type: application/json
+
+{
+  "name": "Akte 2026-002",
+  "aktenzeichen": "124/2026",
+  "aktennummer": 124,
+  "aktenpfad": "/advoware/2026/002",
+  "syncStatus": "unclean"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "64e3f8a1b2c5e"
+}
+```
+
+#### Akte aktualisieren
+```http
+PUT /api/v1/CAdvowareAkten/{id}
+Content-Type: application/json
+
+{
+  "syncStatus": "synced",
+  "lastSync": "2026-03-11T20:00:00+00:00"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "64e3f8a1b2c5d"
+}
+```
+
+#### Akte löschen
+```http
+DELETE /api/v1/CAdvowareAkten/{id}
+```
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+### Relationship-Endpunkte
+
+#### Verknüpfte Dokumente abrufen
+```http
+GET /api/v1/CAdvowareAkten/{id}/dokumentes
+```
+
+**Response:**
+```json
+{
+  "total": 5,
+  "list": [
+    {
+      "id": "dok-123",
+      "name": "Vertrag.pdf",
+      "description": "Mietvertrag",
+      "createdAt": "2026-03-10 09:00:00"
+    }
+  ]
+}
+```
+
+**⚠️ WICHTIG:** Diese Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Junction API Endpoint](#cadvowareaktencdokumente-junction).
+
+#### Dokument mit Akte verknüpfen
+```http
+POST /api/v1/CAdvowareAkten/{id}/dokumentes
+Content-Type: application/json
+
+{
+  "id": "dokument-id-789"
+}
+```
+
+**Hooks werden ausgelöst:**
+- `DokumenteSyncStatus` - Setzt Junction `syncstatus = 'new'`
+- `CheckGlobalSyncStatus` - Berechnet globalen `syncStatus`
+- `PropagateDocumentsUp` - Verknüpft mit Räumungsklage/Mietinkasso
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+#### Dokument von Akte entknüpfen
+```http
+DELETE /api/v1/CAdvowareAkten/{id}/dokumentes/{dokumentId}
+```
+
+**Hooks werden ausgelöst:**
+- `PropagateDocumentsUp` - Entknüpft von Räumungsklage/Mietinkasso
+
+#### Verknüpfte Räumungsklage
+```http
+GET /api/v1/CAdvowareAkten/{id}/vmhRumungsklage
+```
+
+#### Verknüpftes Mietinkasso
+```http
+GET /api/v1/CAdvowareAkten/{id}/mietinkasso
+```
+
+### Filterung & Suche
+
+#### Nach syncStatus filtern
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
+```
+
+#### Nach Aktenzeichen suchen
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=aktenzeichen&where[0][value]=2026
+```
+
+#### Mehrere Filter kombinieren
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&where[1][type]=greaterThan&where[1][attribute]=createdAt&where[1][value]=2026-03-01
+```
+
+#### Nur bestimmte Felder
+```http
+GET /api/v1/CAdvowareAkten?select=name,aktenzeichen,syncStatus,lastSync
+```
+
+#### Mit Sortierung
+```http
+GET /api/v1/CAdvowareAkten?orderBy=createdAt&order=desc
+```
+
+---
+
+## CAIKnowledge (AI Knowledge Base)
+
+**Entity:** Verwaltung von AI Knowledge Base Entries mit Sync-Status
+
+### Standard CRUD Operationen
+
+#### Liste aller Knowledge Entries
+```http
+GET /api/v1/CAIKnowledge
+```
+
+**Response:**
+```json
+{
+  "total": 50,
+  "list": [
+    {
+      "id": "kb-123",
+      "name": "Knowledge Base 2026-001",
+      "datenbankId": "kb-external-123",
+      "syncStatus": "synced",
+      "lastSync": "2026-03-11 19:00:00",
+      "createdAt": "2026-03-10 10:00:00"
+    }
+  ]
+}
+```
+
+#### Einzelnen Entry abrufen
+```http
+GET /api/v1/CAIKnowledge/{id}
+```
+
+#### Neuen Entry erstellen
+```http
+POST /api/v1/CAIKnowledge
+Content-Type: application/json
+
+{
+  "name": "Knowledge Base 2026-002",
+  "datenbankId": "kb-external-456",
+  "syncStatus": "unclean"
+}
+```
+
+#### Entry aktualisieren
+```http
+PUT /api/v1/CAIKnowledge/{id}
+Content-Type: application/json
+
+{
+  "syncStatus": "synced",
+  "lastSync": "2026-03-11T20:00:00+00:00"
+}
+```
+
+#### Entry löschen
+```http
+DELETE /api/v1/CAIKnowledge/{id}
+```
+
+### Relationship-Endpunkte
+
+#### Verknüpfte Dokumente abrufen
+```http
+GET /api/v1/CAIKnowledge/{id}/dokumentes
+```
+
+**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [CAIKnowledgeCDokumente Junction API](#caiknowledgecdokumente-junction).
+
+#### Dokument verknüpfen
+```http
+POST /api/v1/CAIKnowledge/{id}/dokumentes
+Content-Type: application/json
+
+{
+  "id": "dokument-id-789"
+}
+```
+
+**Hooks werden ausgelöst:**
+- `DokumenteSyncStatus` - Setzt Junction `syncstatus = 'new'`
+- `CheckGlobalSyncStatus` - Berechnet globalen `syncStatus`
+- `PropagateDocumentsUp` - Verknüpft mit Räumungsklage/Mietinkasso
+
+#### Dokument entknüpfen
+```http
+DELETE /api/v1/CAIKnowledge/{id}/dokumentes/{dokumentId}
+```
+
+### Filterung & Suche
+
+#### Nach datenbankId suchen
+```http
+GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=datenbankId&where[0][value]=kb-123
+```
+
+#### Alle unclean Entries
+```http
+GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
+```
+
+---
+
+## Junction Tables
+
+### CAdvowareAktenCDokumente (Junction)
+
+**Entity:** Junction-Tabelle zwischen CAdvowareAkten und CDokumente mit additionalColumns
+
+**Verfügbare Felder:**
+- `cAdvowareAktenId` - ID der Akte
+- `cDokumenteId` - ID des Dokuments
+- `hnr` - Advoware HNR-Referenz (varchar, 255)
+- `syncStatus` - Sync-Status (enum: new, changed, synced, deleted)
+- `deleted` - Soft-Delete Flag
+
+#### Alle Junction-Einträge
+```http
+GET /api/v1/CAdvowareAktenCDokumente
+```
+
+**Response:**
+```json
+{
+  "total": 150,
+  "list": [
+    {
+      "id": "1",
+      "cAdvowareAktenId": "akte-123",
+      "cDokumenteId": "dok-456",
+      "hnr": "42",
+      "syncStatus": "synced",
+      "deleted": false
+    },
+    {
+      "id": "2",
+      "cAdvowareAktenId": "akte-123",
+      "cDokumenteId": "dok-789",
+      "hnr": "43",
+      "syncStatus": "new",
+      "deleted": false
+    }
+  ]
+}
+```
+
+#### Einzelnen Junction-Eintrag abrufen
+```http
+GET /api/v1/CAdvowareAktenCDokumente/{id}
+```
+
+#### Alle Dokumente einer Akte mit Junction-Spalten
+```http
+GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123
+```
+
+**Response:**
+```json
+{
+  "total": 5,
+  "list": [
+    {
+      "id": "1",
+      "cAdvowareAktenId": "akte-123",
+      "cDokumenteId": "dok-456",
+      "hnr": "42",
+      "syncStatus": "synced"
+    }
+  ]
+}
+```
+
+#### Nach HNR filtern
+```http
+GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=hnr&where[0][value]=42
+```
+
+#### Nach syncStatus filtern
+```http
+GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed
+```
+
+#### Neuen Junction-Eintrag erstellen (Dokument mit Akte + HNR verknüpfen)
+```http
+POST /api/v1/CAdvowareAktenCDokumente
+Content-Type: application/json
+
+{
+  "cAdvowareAktenId": "akte-123",
+  "cDokumenteId": "dok-999",
+  "hnr": "50",
+  "syncStatus": "new"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "15"
+}
+```
+
+#### Junction-Spalten aktualisieren
+```http
+PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
+Content-Type: application/json
+
+{
+  "syncStatus": "synced",
+  "hnr": "51"
+}
+```
+
+#### Junction-Eintrag löschen
+```http
+DELETE /api/v1/CAdvowareAktenCDokumente/{id}
+```
+
+---
+
+### CAIKnowledgeCDokumente (Junction)
+
+**Entity:** Junction-Tabelle zwischen CAIKnowledge und CDokumente mit additionalColumns
+
+**Verfügbare Felder:**
+- `cAIKnowledgeId` - ID des AI Knowledge Entry
+- `cDokumenteId` - ID des Dokuments
+- `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255)
+- `syncstatus` - Sync-Status (enum: new, unclean, synced, failed)
+- `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
+- `deleted` - Soft-Delete Flag
+
+#### Alle Junction-Einträge
+```http
+GET /api/v1/CAIKnowledgeCDokumente
+```
+
+**Response:**
+```json
+{
+  "total": 80,
+  "list": [
+    {
+      "id": "1",
+      "cAIKnowledgeId": "kb-123",
+      "cDokumenteId": "dok-456",
+      "aiDocumentId": "ai-doc-external-789",
+      "syncstatus": "synced",
+      "lastSync": "2026-03-11 19:00:00",
+      "deleted": false
+    }
+  ]
+}
+```
+
+#### Alle Dokumente eines Knowledge Entry mit Junction-Spalten
+```http
+GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=cAIKnowledgeId&where[0][value]=kb-123
+```
+
+#### Nach aiDocumentId suchen
+```http
+GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789
+```
+
+#### Nach syncstatus filtern
+```http
+GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=syncstatus&where[0][value]=unclean
+```
+
+#### Neuen Junction-Eintrag erstellen
+```http
+POST /api/v1/CAIKnowledgeCDokumente
+Content-Type: application/json
+
+{
+  "cAIKnowledgeId": "kb-123",
+  "cDokumenteId": "dok-999",
+  "aiDocumentId": "ai-doc-new-123",
+  "syncstatus": "new"
+}
+```
+
+#### Junction-Spalten aktualisieren
+```http
+PUT /api/v1/CAIKnowledgeCDokumente/{junctionId}
+Content-Type: application/json
+
+{
+  "syncstatus": "synced",
+  "lastSync": "2026-03-11T20:30:00+00:00"
+}
+```
+
+---
+
+## CDokumente (Dokumente)
+
+**Entity:** Dokumentenverwaltung
+
+### Standard CRUD Operationen
+
+#### Liste aller Dokumente
+```http
+GET /api/v1/CDokumente
+```
+
+#### Einzelnes Dokument abrufen
+```http
+GET /api/v1/CDokumente/{id}
+```
+
+#### Neues Dokument erstellen
+```http
+POST /api/v1/CDokumente
+Content-Type: application/json
+
+{
+  "name": "Vertrag.pdf",
+  "description": "Mietvertrag Mustermann"
+}
+```
+
+#### Dokument aktualisieren
+```http
+PUT /api/v1/CDokumente/{id}
+Content-Type: application/json
+
+{
+  "description": "Aktualisierte Beschreibung"
+}
+```
+
+**⚠️ Hooks werden ausgelöst:**
+- `UpdateJunctionSyncStatus` - Markiert alle Junction-Einträge als "unclean"
+
+#### Dokument löschen
+```http
+DELETE /api/v1/CDokumente/{id}
+```
+
+### Relationship-Endpunkte
+
+#### Verknüpfte AdvowareAkten
+```http
+GET /api/v1/CDokumente/{id}/advowareAktens
+```
+
+#### Verknüpfte AIKnowledge Entries
+```http
+GET /api/v1/CDokumente/{id}/aIKnowledges
+```
+
+---
+
+## Filtering & Sorting
+
+### Where-Clause Typen
+
+#### equals (Exakte Übereinstimmung)
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
+```
+
+#### contains (Text-Suche)
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=name&where[0][value]=2026
+```
+
+#### in (Liste von Werten)
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=unclean
+```
+
+#### greaterThan / lessThan
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=greaterThan&where[0][attribute]=createdAt&where[0][value]=2026-03-01
+```
+
+#### isNull / isNotNull
+```http
+GET /api/v1/CAdvowareAkten?where[0][type]=isNull&where[0][attribute]=lastSync
+```
+
+### Sortierung
+
+```http
+GET /api/v1/CAdvowareAkten?orderBy=createdAt&order=desc
+```
+
+### Pagination
+
+```http
+GET /api/v1/CAdvowareAkten?maxSize=50&offset=100
+```
+
+### Feld-Selektion
+
+```http
+GET /api/v1/CAdvowareAkten?select=id,name,syncStatus,lastSync
+```
+
+---
+
+## Praktische Beispiele
+
+### 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" \
+  -H "X-Api-Key: your-api-key"
+```
+
+### Beispiel 2: Alle Dokumente einer Akte mit Junction-Spalten
+
+```bash
+# Schritt 1: Hole Akte
+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" \
+  -H "X-Api-Key: your-api-key"
+```
+
+### Beispiel 3: Dokument mit Akte + HNR verknüpfen
+
+```bash
+# Via Junction API (empfohlen)
+curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "cAdvowareAktenId": "akte-123",
+    "cDokumenteId": "dok-789",
+    "hnr": "42",
+    "syncStatus": "new"
+  }'
+```
+
+### Beispiel 4: Sync-Status aktualisieren nach erfolgreicher Synchronisation
+
+```bash
+# Schritt 1: Finde Junction-Eintrag
+JUNCTION_ID=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&where[1][type]=equals&where[1][attribute]=cDokumenteId&where[1][value]=dok-789&select=id" \
+  -H "X-Api-Key: your-api-key" | jq -r '.list[0].id')
+
+# Schritt 2: Update Junction-Status
+curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_ID" \
+  -H "X-Api-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "syncStatus": "synced"
+  }'
+
+# Schritt 3: Update global status (optional, Hooks machen das automatisch)
+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"
+  }'
+```
+
+### Beispiel 5: Suche AI-Dokument via externe ID
+
+```bash
+# Finde Junction-Eintrag via aiDocumentId
+curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789" \
+  -H "X-Api-Key: your-api-key"
+
+# Response enthält cDokumenteId zum Abrufen des vollen Dokuments
+```
+
+### Beispiel 6: Alle neuen/geänderten Dokumente für Sync
+
+```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" \
+  -H "X-Api-Key: your-api-key"
+```
+
+---
+
+## 🎯 Wichtige Hinweise
+
+### Junction-Spalten via REST API
+
+**✅ RICHTIG:** Nutze Junction-Entity-APIs
+```bash
+GET /api/v1/CAdvowareAktenCDokumente
+GET /api/v1/CAIKnowledgeCDokumente
+```
+
+**❌ FALSCH:** Standard Relationship-Endpoints geben additionalColumns NICHT zurück
+```bash
+GET /api/v1/CAdvowareAkten/{id}/dokumentes  # hnr/syncStatus NICHT in Response!
+```
+
+### Hooks & Automatische Updates
+
+Folgende Operationen lösen automatisch Hooks aus:
+
+**Dokument verknüpfen:**
+```bash
+POST /api/v1/CAdvowareAkten/{id}/dokumentes
+```
+- → `DokumenteSyncStatus`: Setzt Junction `syncstatus = 'new'`
+- → `CheckGlobalSyncStatus`: Berechnet globalen Status
+- → `PropagateDocumentsUp`: Verknüpft mit Räumungsklage/Mietinkasso
+
+**Dokument ändern:**
+```bash
+PUT /api/v1/CDokumente/{id}
+```
+- → `UpdateJunctionSyncStatus`: Markiert alle Junction-Einträge als "unclean"
+
+**Vor Entity speichern:**
+```bash
+PUT /api/v1/CAdvowareAkten/{id}
+```
+- → `CheckGlobalSyncStatus`: Berechnet globalen Status aus Junction-Einträgen
+
+### ACL-Berechtigungen
+
+Für Junction-Entities müssen Rollen explizit Zugriff haben:
+
+```sql
+-- Via Admin UI: Roles → [Your Role] → Add "CAdvowareAktenCDokumente"
+-- Oder via SQL:
+UPDATE role 
+SET data = JSON_SET(data, '$.table.CAdvowareAktenCDokumente', 
+  JSON_OBJECT('create','yes','read','all','edit','all','delete','all')
+) 
+WHERE name = 'Your Role Name';
+```
+
+---
+
+**Letzte Aktualisierung:** 11. März 2026  
+**Version:** 1.0
+
+Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
diff --git a/data/config.php b/data/config.php
index b843a4ed..51e4fc31 100644
--- a/data/config.php
+++ b/data/config.php
@@ -360,7 +360,7 @@ return [
     0 => 'youtube.com',
     1 => 'google.com'
   ],
-  'microtime' => 1773256040.239404,
+  'microtime' => 1773258449.013255,
   'siteUrl' => 'https://crm.bitbylaw.com',
   'fullTextSearchMinLength' => 4,
   'webSocketUrl' => 'ws://api.bitbylaw.com:5000/espocrm/ws',
diff --git a/data/state.php b/data/state.php
index 14d63828..62dbb6ca 100644
--- a/data/state.php
+++ b/data/state.php
@@ -1,7 +1,7 @@
 <?php
 return [
-  'cacheTimestamp' => 1773256148,
-  'microtimeState' => 1773256148.816542,
+  'cacheTimestamp' => 1773258449,
+  'microtimeState' => 1773258449.160853,
   'currencyRates' => [
     'EUR' => 1.0
   ],