Update EspoCRM Best Practices to version 2.4 with new features and implementation patterns for Custom API Endpoints; remove outdated TESTERGEBNISSE_JUNCTION_TABLE.md file.

custom/Espo/Custom/Api/JunctionData/GetDokumentes.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Espo\Custom\Api\JunctionData;
+
+use Espo\Core\Api\Action;
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Api\ResponseComposer;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\NotFound;
+use Espo\ORM\EntityManager;
+
+/**
+ * GET /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes
+ * 
+ * Returns all documents linked to a knowledge entry with junction table data
+ */
+class GetDokumentes implements Action
+{
+    public function __construct(
+        private EntityManager $entityManager
+    ) {}
+    
+    public function process(Request $request): Response
+    {
+        $knowledgeId = $request->getRouteParam('knowledgeId');
+        
+        if (!$knowledgeId) {
+            throw new BadRequest('Knowledge ID is required');
+        }
+        
+        // Verify knowledge exists
+        $knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
+        if (!$knowledge) {
+            throw new NotFound('Knowledge entry not found');
+        }
+        
+        $pdo = $this->entityManager->getPDO();
+        
+        $sql = "
+            SELECT 
+                j.id as junctionId,
+                j.c_a_i_knowledge_id as cAIKnowledgeId,
+                j.c_dokumente_id as cDokumenteId,
+                j.ai_document_id as aiDocumentId,
+                j.syncstatus,
+                j.last_sync as lastSync,
+                d.id as documentId,
+                d.name as documentName,
+                d.blake3hash as blake3hash,
+                d.created_at as documentCreatedAt,
+                d.modified_at as documentModifiedAt
+            FROM c_a_i_knowledge_dokumente j
+            INNER JOIN c_dokumente d ON j.c_dokumente_id = d.id
+            WHERE j.c_a_i_knowledge_id = :knowledgeId
+              AND j.deleted = 0
+              AND d.deleted = 0
+            ORDER BY j.id DESC
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute(['knowledgeId' => $knowledgeId]);
+        
+        $results = $sth->fetchAll(\PDO::FETCH_ASSOC);
+        
+        return ResponseComposer::json([
+            'total' => count($results),
+            'list' => $results
+        ]);
+    }
+}

custom/Espo/Custom/Api/JunctionData/LinkDokument.php

@@ -0,0 +1,178 @@
+<?php
+
+namespace Espo\Custom\Api\JunctionData;
+
+use Espo\Core\Api\Action;
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Api\ResponseComposer;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\NotFound;
+use Espo\Core\Exceptions\Conflict;
+use Espo\ORM\EntityManager;
+
+/**
+ * POST /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
+ * 
+ * Creates or updates relationship with junction table data
+ * This endpoint links the entities AND sets junction columns in one call
+ */
+class LinkDokument implements Action
+{
+    public function __construct(
+        private EntityManager $entityManager
+    ) {}
+    
+    public function process(Request $request): Response
+    {
+        $knowledgeId = $request->getRouteParam('knowledgeId');
+        $documentId = $request->getRouteParam('documentId');
+        $data = $request->getParsedBody();
+        
+        if (!$knowledgeId || !$documentId) {
+            throw new BadRequest('Knowledge ID and Document ID are required');
+        }
+        
+        // Verify entities exist
+        $knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
+        if (!$knowledge) {
+            throw new NotFound('Knowledge entry not found');
+        }
+        
+        $document = $this->entityManager->getEntityById('CDokumente', $documentId);
+        if (!$document) {
+            throw new NotFound('Document not found');
+        }
+        
+        $pdo = $this->entityManager->getPDO();
+        
+        // Check if link already exists
+        $existing = $this->checkIfLinked($knowledgeId, $documentId);
+        
+        if ($existing) {
+            // Link exists - update junction columns
+            return $this->updateExisting($knowledgeId, $documentId, $data);
+        }
+        
+        // Create new link via ORM (triggers hooks like DokumenteSyncStatus)
+        $this->entityManager->getRDBRepository('CAIKnowledge')
+            ->getRelation($knowledge, 'dokumentes')
+            ->relate($document);
+        
+        // Now set junction columns if provided
+        if (!empty((array)$data)) {
+            return $this->updateExisting($knowledgeId, $documentId, $data);
+        }
+        
+        // Return created entry
+        $result = $this->getJunctionEntry($knowledgeId, $documentId);
+        
+        return ResponseComposer::json($result);
+    }
+    
+    private function checkIfLinked(string $knowledgeId, string $documentId): bool
+    {
+        $pdo = $this->entityManager->getPDO();
+        
+        $sql = "
+            SELECT COUNT(*) as count
+            FROM c_a_i_knowledge_dokumente
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute([
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ]);
+        
+        $result = $sth->fetch(\PDO::FETCH_ASSOC);
+        return $result['count'] > 0;
+    }
+    
+    private function updateExisting(string $knowledgeId, string $documentId, \stdClass $data): Response
+    {
+        $pdo = $this->entityManager->getPDO();
+        
+        // Build dynamic UPDATE SET clause
+        $setClauses = [];
+        $params = [
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ];
+        
+        if (isset($data->aiDocumentId)) {
+            $setClauses[] = "ai_document_id = :aiDocumentId";
+            $params['aiDocumentId'] = $data->aiDocumentId;
+        }
+        
+        if (isset($data->syncstatus)) {
+            $allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
+            if (!in_array($data->syncstatus, $allowedStatuses)) {
+                throw new BadRequest('Invalid syncstatus value. Allowed: ' . implode(', ', $allowedStatuses));
+            }
+            $setClauses[] = "syncstatus = :syncstatus";
+            $params['syncstatus'] = $data->syncstatus;
+        }
+        
+        if (isset($data->lastSync)) {
+            $setClauses[] = "last_sync = :lastSync";
+            $params['lastSync'] = $data->lastSync;
+        } elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
+            $setClauses[] = "last_sync = NOW()";
+        }
+        
+        if (!empty($setClauses)) {
+            $sql = "
+                UPDATE c_a_i_knowledge_dokumente
+                SET " . implode(', ', $setClauses) . "
+                WHERE c_a_i_knowledge_id = :knowledgeId
+                  AND c_dokumente_id = :documentId
+                  AND deleted = 0
+            ";
+            
+            $sth = $pdo->prepare($sql);
+            $sth->execute($params);
+        }
+        
+        // Return updated data
+        $result = $this->getJunctionEntry($knowledgeId, $documentId);
+        
+        return ResponseComposer::json($result);
+    }
+    
+    private function getJunctionEntry(string $knowledgeId, string $documentId): array
+    {
+        $pdo = $this->entityManager->getPDO();
+        
+        $sql = "
+            SELECT 
+                id as junctionId,
+                c_a_i_knowledge_id as cAIKnowledgeId,
+                c_dokumente_id as cDokumenteId,
+                ai_document_id as aiDocumentId,
+                syncstatus,
+                last_sync as lastSync
+            FROM c_a_i_knowledge_dokumente
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute([
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ]);
+        
+        $result = $sth->fetch(\PDO::FETCH_ASSOC);
+        
+        if (!$result) {
+            throw new NotFound('Junction entry not found');
+        }
+        
+        return $result;
+    }
+}

custom/Espo/Custom/Api/JunctionData/UpdateJunction.php

@@ -0,0 +1,123 @@
+<?php
+
+namespace Espo\Custom\Api\JunctionData;
+
+use Espo\Core\Api\Action;
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Api\ResponseComposer;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\NotFound;
+use Espo\ORM\EntityManager;
+
+/**
+ * PUT /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
+ * 
+ * Updates junction table columns for an existing relationship
+ */
+class UpdateJunction implements Action
+{
+    public function __construct(
+        private EntityManager $entityManager
+    ) {}
+    
+    public function process(Request $request): Response
+    {
+        $knowledgeId = $request->getRouteParam('knowledgeId');
+        $documentId = $request->getRouteParam('documentId');
+        $data = $request->getParsedBody();
+        
+        if (!$knowledgeId || !$documentId) {
+            throw new BadRequest('Knowledge ID and Document ID are required');
+        }
+        
+        $pdo = $this->entityManager->getPDO();
+        
+        // Build dynamic UPDATE SET clause
+        $setClauses = [];
+        $params = [
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ];
+        
+        if (isset($data->aiDocumentId)) {
+            $setClauses[] = "ai_document_id = :aiDocumentId";
+            $params['aiDocumentId'] = $data->aiDocumentId;
+        }
+        
+        if (isset($data->syncstatus)) {
+            $allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
+            if (!in_array($data->syncstatus, $allowedStatuses)) {
+                throw new BadRequest('Invalid syncstatus value. Allowed: ' . implode(', ', $allowedStatuses));
+            }
+            $setClauses[] = "syncstatus = :syncstatus";
+            $params['syncstatus'] = $data->syncstatus;
+        }
+        
+        if (isset($data->lastSync)) {
+            $setClauses[] = "last_sync = :lastSync";
+            $params['lastSync'] = $data->lastSync;
+        } elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
+            $setClauses[] = "last_sync = NOW()";
+        }
+        
+        if (empty($setClauses)) {
+            throw new BadRequest('No fields to update. Provide at least one of: aiDocumentId, syncstatus, lastSync');
+        }
+        
+        $sql = "
+            UPDATE c_a_i_knowledge_dokumente
+            SET " . implode(', ', $setClauses) . "
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute($params);
+        
+        $affectedRows = $sth->rowCount();
+        
+        if ($affectedRows === 0) {
+            throw new NotFound('Junction entry not found or no changes made');
+        }
+        
+        // Return updated data
+        $result = $this->getJunctionEntry($knowledgeId, $documentId);
+        
+        return ResponseComposer::json($result);
+    }
+    
+    private function getJunctionEntry(string $knowledgeId, string $documentId): array
+    {
+        $pdo = $this->entityManager->getPDO();
+        
+        $sql = "
+            SELECT 
+                id as junctionId,
+                c_a_i_knowledge_id as cAIKnowledgeId,
+                c_dokumente_id as cDokumenteId,
+                ai_document_id as aiDocumentId,
+                syncstatus,
+                last_sync as lastSync
+            FROM c_a_i_knowledge_dokumente
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute([
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ]);
+        
+        $result = $sth->fetch(\PDO::FETCH_ASSOC);
+        
+        if (!$result) {
+            throw new NotFound('Junction entry not found');
+        }
+        
+        return $result;
+    }
+}

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}
+}

custom/Espo/Custom/Hooks/CDokumente/CDokumente.php

@@ -35,22 +35,24 @@ class CDokumente extends \Espo\Core\Hooks\Base
             return;
         }
 
-        // Berechne neue Hashes
-        $newMd5 = hash_file('md5', $filePath);
-        $newSha256 = hash_file('sha256', $filePath);
+        // Berechne Blake3 Hash
+        $fileContent = file_get_contents($filePath);
+        if ($fileContent === false) {
+            return;
+        }
+        
+        $newBlake3 = \blake3($fileContent);
 
-        // Setze Hashes
-        $entity->set('md5sum', $newMd5);
-        $entity->set('sha256', $newSha256);
+        // Setze Hash
+        $entity->set('blake3hash', $newBlake3);
 
         // Bestimme Status
         if ($entity->isNew()) {
             $entity->set('fileStatus', 'new');
         } else {
-            $oldMd5 = $entity->getFetched('md5sum');
-            $oldSha256 = $entity->getFetched('sha256');
+            $oldBlake3 = $entity->getFetched('blake3hash');
 
-            if ($oldMd5 !== $newMd5 || $oldSha256 !== $newSha256) {
+            if ($oldBlake3 !== $newBlake3) {
                 $entity->set('fileStatus', 'changed');
             } else {
                 $entity->set('fileStatus', 'synced');

custom/Espo/Custom/Resources/i18n/de_DE/CAICollectionCDokumente.json

@@ -1,31 +0,0 @@
-{
-    "labels": {
-        "Create CAICollectionCDokumente": "AI-Collection-Dokument-Verknüpfung erstellen",
-        "CAICollectionCDokumente": "AI-Collection-Dokument-Verknüpfungen"
-    },
-    "fields": {
-        "cAICollection": "AI-Collection",
-        "cAICollectionId": "AI-Collection ID",
-        "cDokumente": "Dokument",
-        "cDokumenteId": "Dokument ID",
-        "xaifileid": "XAI File ID",
-        "syncStatus": "Sync-Status",
-        "deleted": "Gelöscht"
-    },
-    "links": {
-        "cAICollection": "AI-Collection",
-        "cDokumente": "Dokument"
-    },
-    "options": {
-        "syncStatus": {
-            "new": "Neu",
-            "changed": "Geändert",
-            "synced": "Synchronisiert",
-            "deleted": "Gelöscht"
-        }
-    },
-    "tooltips": {
-        "xaifileid": "Externe XAI File ID für dieses Dokument",
-        "syncStatus": "Synchronisierungsstatus mit XAI"
-    }
-}

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,12 +23,27 @@
     "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",
+            "unclean": "Nicht synchronisiert",
+            "synced": "Synchronisiert",
+            "failed": "Fehlgeschlagen",
+            "unsupported": "Nicht unterstützt"
         }
     },
     "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"
     }
 }

custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json

@@ -0,0 +1,30 @@
+{
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Dokument",
+        "aiDocumentId": "AI Dokument-ID",
+        "syncstatus": "Sync-Status",
+        "lastSync": "Letzte Synchronisation",
+        "syncedHash": "Sync-Hash"
+    },
+    "links": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Dokument"
+    },
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "Verknüpfung erstellen"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "Neu",
+            "unclean": "Geändert",
+            "synced": "Synchronisiert",
+            "failed": "Fehler",
+            "unsupported": "Nicht unterstützt"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "Externe AI-Dokument-Referenz-ID",
+        "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands"
+    }
+}

custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeDokumente.json

@@ -0,0 +1,30 @@
+{
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Dokument",
+        "aiDocumentId": "AI Dokument-ID",
+        "syncstatus": "Sync-Status",
+        "lastSync": "Letzte Synchronisation",
+        "syncedHash": "Sync-Hash"
+    },
+    "links": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Dokument"
+    },
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "Verknüpfung erstellen"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "Neu",
+            "unclean": "Geändert",
+            "synced": "Synchronisiert",
+            "failed": "Fehler",
+            "unsupported": "Nicht unterstützt"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "Externe AI-Dokument-Referenz-ID",
+        "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands"
+    }
+}

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"
     }
 }

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)"
     }
 }

custom/Espo/Custom/Resources/i18n/de_DE/CDokumente.json

@@ -2,10 +2,7 @@
     "fields": {
         "dokument": "Download",
         "preview": "Vorschau",
-        "ydocumentuuid": "Y-Document-UUID",
-        "md5sum": "MD5-Prüfsumme",
-        "sha256": "SHA256-Prüfsumme",
-        "fileStatus": "Datei-Status",
+        "blake3hash": "Blake3-Hash",
         "contactsvmhdokumente": "Freigegebene Nutzer",
         "vmhMietverhltnisesDokumente": "Mietverhältnisse",
         "vmhErstgespraechsdokumente": "Erstgespräche",
@@ -41,13 +38,6 @@
         "Create CDokumente": "Dokument erstellen"
     },
     "tooltips": {
-        "fileStatus": "Status der Datei: new = neu hochgeladen, changed = geändert, synced = synchronisiert"
-    },
-    "options": {
-        "fileStatus": {
-            "new": "Neu",
-            "changed": "Geändert",
-            "synced": "Synchronisiert"
-        }
+        "blake3hash": "Kryptografischer Blake3-Hash der Datei (schneller und sicherer als MD5/SHA256)"
     }
 }

custom/Espo/Custom/Resources/i18n/en_US/CAICollectionCDokumente.json

@@ -1,31 +0,0 @@
-{
-    "labels": {
-        "Create CAICollectionCDokumente": "Create AI Collection Document Link",
-        "CAICollectionCDokumente": "AI Collection Document Links"
-    },
-    "fields": {
-        "cAICollection": "AI Collection",
-        "cAICollectionId": "AI Collection ID",
-        "cDokumente": "Document",
-        "cDokumenteId": "Document ID",
-        "xaifileid": "XAI File ID",
-        "syncStatus": "Sync Status",
-        "deleted": "Deleted"
-    },
-    "links": {
-        "cAICollection": "AI Collection",
-        "cDokumente": "Document"
-    },
-    "options": {
-        "syncStatus": {
-            "new": "New",
-            "changed": "Changed",
-            "synced": "Synced",
-            "deleted": "Deleted"
-        }
-    },
-    "tooltips": {
-        "xaifileid": "External XAI file ID for this document",
-        "syncStatus": "Synchronization status with XAI"
-    }
-}

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,12 +23,27 @@
     "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",
+            "unclean": "Not Synchronized",
+            "synced": "Synchronized",
+            "failed": "Failed",
+            "unsupported": "Unsupported"
         }
     },
     "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"
     }
 }

custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json

@@ -0,0 +1,30 @@
+{
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Document",
+        "aiDocumentId": "AI Document ID",
+        "syncstatus": "Sync Status",
+        "lastSync": "Last Sync",
+        "syncedHash": "Synced Hash"
+    },
+    "links": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Document"
+    },
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "Create Link"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "New",
+            "unclean": "Changed",
+            "synced": "Synced",
+            "failed": "Failed",
+            "unsupported": "Unsupported"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "External AI document reference ID",
+        "syncedHash": "Hash value of last synced document state"
+    }
+}

custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeDokumente.json

@@ -0,0 +1,30 @@
+{
+    "fields": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Document",
+        "aiDocumentId": "AI Document ID",
+        "syncstatus": "Sync Status",
+        "lastSync": "Last Sync",
+        "syncedHash": "Synced Hash"
+    },
+    "links": {
+        "cAIKnowledge": "AI Knowledge",
+        "cDokumente": "Document"
+    },
+    "labels": {
+        "Create CAIKnowledgeCDokumente": "Create Link"
+    },
+    "options": {
+        "syncstatus": {
+            "new": "New",
+            "unclean": "Changed",
+            "synced": "Synced",
+            "failed": "Failed",
+            "unsupported": "Unsupported"
+        }
+    },
+    "tooltips": {
+        "aiDocumentId": "External AI document reference ID",
+        "syncedHash": "Hash value of last synced document state"
+    }
+}

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"
     }
 }

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)"
     }
 }

custom/Espo/Custom/Resources/i18n/en_US/CDokumente.json

@@ -1,21 +1,17 @@
 {
     "fields": {
         "dokument": "Download",
-        "ydocumentuuid": "Y-Document-UUID",
         "preview": "Preview",
         "contactsvmhdokumente": "Portal Users",
         "vmhMietverhltnisesDokumente": "Tenancies",
         "vmhErstgespraechsdokumente": "Initial Consultations",
         "vmhRumungsklagesdokumente": "Eviction Lawsuits",
         "kuendigungDokumente": "Terminations",
-        "md5sum": "MD5 Checksum",
-        "sha256": "SHA256 Checksum",
+        "blake3hash": "Blake3 Hash",
         "beteiligte2dokumente": "Parties",
         "mietobjekt2dokumente": "Properties",
         "mietinkassosdokumente": "Rent Collection",
         "kndigungensdokumente": "Terminations",
-        "fileStatus": "File Status",
-        "advowareAktens": "Advoware Akten",
         "advowareAktens": "Advoware Akten",
         "aIKnowledges": "AI Knowledge",
         "advowareAktenHnr": "Advoware HNR",
@@ -47,13 +43,6 @@
         "listForAIKnowledge": "List for AI Knowledge"
     },
     "tooltips": {
-        "fileStatus": "File status: new = newly uploaded, changed = modified, synced = synchronized"
-    },
-    "options": {
-        "fileStatus": {
-            "new": "New",
-            "changed": "Changed",
-            "synced": "Synchronized"
-        }
+        "blake3hash": "Cryptographic Blake3 hash of the file (faster and more secure than MD5/SHA256)"
     }
 }

custom/Espo/Custom/Resources/layouts/CAIKnowledge/detail.json

@@ -10,6 +10,9 @@
                 }
             ],
             [
+                {
+                    "name": "aktivierungsstatus"
+                },
                 {
                     "name": "syncStatus"
                 },

custom/Espo/Custom/Resources/layouts/CDokumente/detail.json

@@ -40,9 +40,8 @@
         "rows": [
             [
                 {
-                    "name": "ydocumentuuid"
-                },
-                {}
+                    "name": "blake3hash"
+                }
             ]
         ],
         "dynamicLogicVisible": null,
@@ -52,77 +51,6 @@
         "hidden": false,
         "noteText": null,
         "noteStyle": "info",
-        "customLabel": "Externe Identifikatoren"
-    },
-    {
-        "rows": [
-            [
-                {
-                    "name": "fileStatus"
-                },
-                {
-                    "name": "md5sum"
-                }
-            ],
-            [
-                {
-                    "name": "sha256"
-                }
-            ]
-        ],
-        "dynamicLogicVisible": null,
-        "style": "default",
-        "tabBreak": false,
-        "tabLabel": null,
-        "hidden": false,
-        "noteText": null,
-        "noteStyle": "info",
         "customLabel": "Technische Daten"
-    },
-    {
-        "rows": [
-            [
-                {
-                    "name": "aktennr"
-                },
-                {
-                    "name": "syncStatus"
-                },
-                {
-                    "name": "advowareLastSync"
-                }
-            ]
-        ],
-        "dynamicLogicVisible": null,
-        "style": "default",
-        "tabBreak": false,
-        "tabLabel": null,
-        "hidden": false,
-        "noteText": null,
-        "noteStyle": "info",
-        "customLabel": "Advoware Sync"
-    },
-    {
-        "rows": [
-            [
-                {
-                    "name": "xaiId"
-                },
-                {
-                    "name": "xaiCollections"
-                },
-                {
-                    "name": "xaiSyncStatus"
-                }
-            ]
-        ],
-        "dynamicLogicVisible": null,
-        "style": "default",
-        "tabBreak": false,
-        "tabLabel": null,
-        "hidden": false,
-        "noteText": null,
-        "noteStyle": "info",
-        "customLabel": "x.AI Sync"
     }
 ]

custom/Espo/Custom/Resources/metadata/app/api.json

@@ -9,6 +9,21 @@
       "route": "/CPuls/:id/abschliessen-fuer-team",
       "method": "post",
       "actionClassName": "Espo\\Custom\\Api\\CPuls\\AbschliessenFuerTeam"
+    },
+    {
+      "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
+      "method": "get",
+      "actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
+    },
+    {
+      "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+      "method": "put",
+      "actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
+    },
+    {
+      "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+      "method": "post",
+      "actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
     }
   ]
 }

custom/Espo/Custom/Resources/metadata/entityDefs/CAICollectionCDokumente.json

@@ -1,87 +0,0 @@
-{
-    "fields": {
-        "id": {
-            "type": "id",
-            "dbType": "bigint",
-            "autoincrement": true
-        },
-        "cAICollection": {
-            "type": "link"
-        },
-        "cAICollectionId": {
-            "type": "varchar",
-            "len": 17,
-            "index": true
-        },
-        "cDokumente": {
-            "type": "link"
-        },
-        "cDokumenteId": {
-            "type": "varchar",
-            "len": 17,
-            "index": true
-        },
-        "xaifileid": {
-            "type": "varchar",
-            "len": 255,
-            "isCustom": true,
-            "tooltip": true,
-            "copyToClipboard": true
-        },
-        "syncStatus": {
-            "type": "enum",
-            "required": false,
-            "options": [
-                "new",
-                "changed",
-                "synced",
-                "deleted"
-            ],
-            "style": {
-                "new": "info",
-                "changed": "warning",
-                "synced": "success",
-                "deleted": "danger"
-            },
-            "default": "new",
-            "isCustom": true,
-            "tooltip": true
-        },
-        "deleted": {
-            "type": "bool",
-            "default": false
-        }
-    },
-    "links": {
-        "cAICollection": {
-            "type": "belongsTo",
-            "entity": "CAICollection"
-        },
-        "cDokumente": {
-            "type": "belongsTo",
-            "entity": "CDokumente"
-        }
-    },
-    "collection": {
-        "orderBy": "id",
-        "order": "desc"
-    },
-    "indexes": {
-        "cAICollectionId": {
-            "columns": ["cAICollectionId"]
-        },
-        "cDokumenteId": {
-            "columns": ["cDokumenteId"]
-        },
-        "xaifileid": {
-            "columns": ["xaifileid"]
-        },
-        "syncStatus": {
-            "columns": ["syncStatus"]
-        },
-        "uniqueRelation": {
-            "type": "unique",
-            "columns": ["cAICollectionId", "cDokumenteId", "deleted"]
-        }
-    }
-}

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,
@@ -76,7 +97,7 @@
         },
         "dokumenteSyncstatus": {
             "type": "enum",
-            "options": ["new", "unclean", "synced", "failed"],
+            "options": ["new", "unclean", "synced", "failed", "unsupported"],
             "notStorable": true,
             "utility": 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"

custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json

@@ -0,0 +1,85 @@
+{
+    "table": "c_a_i_knowledge_dokumente",
+    "fields": {
+        "id": {
+            "type": "id",
+            "dbType": "bigint",
+            "autoincrement": true
+        },
+        "cAIKnowledge": {
+            "type": "link",
+            "entity": "CAIKnowledge"
+        },
+        "cAIKnowledgeId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "cAIKnowledgeName": {
+            "type": "varchar",
+            "notStorable": true,
+            "relation": "cAIKnowledge",
+            "foreign": "name"
+        },
+        "cDokumente": {
+            "type": "link",
+            "entity": "CDokumente"
+        },
+        "cDokumenteId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "cDokumenteName": {
+            "type": "varchar",
+            "notStorable": true,
+            "relation": "cDokumente",
+            "foreign": "name"
+        },
+        "aiDocumentId": {
+            "type": "varchar",
+            "len": 255,
+            "tooltip": true
+        },
+        "syncstatus": {
+            "type": "enum",
+            "options": ["new", "unclean", "synced", "failed", "unsupported"],
+            "default": "new",
+            "style": {
+                "new": "primary",
+                "unclean": "warning",
+                "synced": "success",
+                "failed": "danger",
+                "unsupported": "default"
+            }
+        },
+        "lastSync": {
+            "type": "datetime"
+        },
+        "syncedHash": {
+            "type": "varchar",
+            "len": 64,
+            "tooltip": true
+        },
+        "deleted": {
+            "type": "bool",
+            "default": false
+        }
+    },
+    "links": {
+        "cAIKnowledge": {
+            "type": "belongsTo",
+            "entity": "CAIKnowledge",
+            "foreign": "dokumentes"
+        },
+        "cDokumente": {
+            "type": "belongsTo",
+            "entity": "CDokumente",
+            "foreign": "aIKnowledges"
+        }
+    },
+    "collection": {
+        "orderBy": "id",
+        "order": "asc"
+    }
+}

custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeDokumente.json

@@ -0,0 +1,85 @@
+{
+    "table": "c_a_i_knowledge_dokumente",
+    "fields": {
+        "id": {
+            "type": "id",
+            "dbType": "bigint",
+            "autoincrement": true
+        },
+        "cAIKnowledge": {
+            "type": "link",
+            "entity": "CAIKnowledge"
+        },
+        "cAIKnowledgeId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "cAIKnowledgeName": {
+            "type": "varchar",
+            "notStorable": true,
+            "relation": "cAIKnowledge",
+            "foreign": "name"
+        },
+        "cDokumente": {
+            "type": "link",
+            "entity": "CDokumente"
+        },
+        "cDokumenteId": {
+            "type": "varchar",
+            "len": 17,
+            "index": true
+        },
+        "cDokumenteName": {
+            "type": "varchar",
+            "notStorable": true,
+            "relation": "cDokumente",
+            "foreign": "name"
+        },
+        "aiDocumentId": {
+            "type": "varchar",
+            "len": 255,
+            "tooltip": true
+        },
+        "syncstatus": {
+            "type": "enum",
+            "options": ["new", "unclean", "synced", "failed", "unsupported"],
+            "default": "new",
+            "style": {
+                "new": "primary",
+                "unclean": "warning",
+                "synced": "success",
+                "failed": "danger",
+                "unsupported": "default"
+            }
+        },
+        "lastSync": {
+            "type": "datetime"
+        },
+        "syncedHash": {
+            "type": "varchar",
+            "len": 64,
+            "tooltip": true
+        },
+        "deleted": {
+            "type": "bool",
+            "default": false
+        }
+    },
+    "links": {
+        "cAIKnowledge": {
+            "type": "belongsTo",
+            "entity": "CAIKnowledge",
+            "foreign": "dokumentes"
+        },
+        "cDokumente": {
+            "type": "belongsTo",
+            "entity": "CDokumente",
+            "foreign": "aIKnowledges"
+        }
+    },
+    "collection": {
+        "orderBy": "id",
+        "order": "asc"
+    }
+}

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"

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

custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json

@@ -45,13 +45,6 @@
             "isCustom": true,
             "audited": true
         },
-        "ydocumentuuid": {
-            "type": "varchar",
-            "maxLength": 100,
-            "readOnlyAfterCreate": true,
-            "options": [],
-            "isCustom": true
-        },
         "preview": {
             "type": "image",
             "previewSize": "medium",
@@ -59,80 +52,67 @@
             "readOnlyAfterCreate": false,
             "isCustom": true
         },
-        "md5sum": {
-            "type": "varchar",
-            "maxLength": 32,
-            "copyToClipboard": true,
-            "readOnlyAfterCreate": true,
-            "options": [],
-            "isCustom": true
-        },
-        "sha256": {
+        "blake3hash": {
             "type": "varchar",
             "maxLength": 64,
-            "readOnlyAfterCreate": true,
+            "copyToClipboard": true,
+            "readOnlyAfterCreate": false,
             "options": [],
             "isCustom": true,
-            "copyToClipboard": true
+            "tooltip": true
         },
         "puls": {
             "type": "link",
             "entity": "CPuls",
             "isCustom": true
         },
-        "fileStatus": {
-            "type": "enum",
-            "required": false,
-            "options": [
-                "new",
-                "changed",
-                "synced"
-            ],
-            "style": {
-                "new": "info",
-                "changed": "warning",
-                "synced": "success"
-            },
-            "default": "new",
-            "readOnly": false,
-            "tooltip": true,
-            "isCustom": true
-        },
         "advowareAktenHnr": {
             "type": "int",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAdvowareAkten"]
+            "layoutAvailabilityList": [
+                "listForAdvowareAkten"
+            ]
         },
         "advowareAktenSyncstatus": {
             "type": "varchar",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAdvowareAkten"]
+            "layoutAvailabilityList": [
+                "listForAdvowareAkten"
+            ]
         },
         "advowareAktenLastSync": {
             "type": "datetime",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAdvowareAkten"]
+            "layoutAvailabilityList": [
+                "listForAdvowareAkten"
+            ]
         },
         "aiKnowledgeAiDocumentId": {
             "type": "varchar",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAIKnowledge"]
+            "layoutAvailabilityList": [
+                "listForAIKnowledge"
+            ]
         },
         "aiKnowledgeSyncstatus": {
             "type": "varchar",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAIKnowledge"]
+            "layoutAvailabilityList": [
+                "listForAIKnowledge"
+            ]
         },
         "aiKnowledgeLastSync": {
             "type": "datetime",
             "notStorable": true,
             "utility": true,
-            "layoutAvailabilityList": ["listForAIKnowledge"]
+            "layoutAvailabilityList": [
+                "listForAIKnowledge"
+            ]
         }
     },
     "links": {
@@ -298,14 +278,9 @@
                 "id"
             ]
         },
-        "md5sum": {
+        "blake3hash": {
             "columns": [
-                "md5sum"
-            ]
-        },
-        "sha256": {
-            "columns": [
-                "sha256"
+                "blake3hash"
             ]
         }
     },

custom/Espo/Custom/Resources/metadata/formula/CDokumente.json

@@ -1,3 +1,3 @@
 {
-    "beforeSaveScript": "// Automatische x.AI Sync-Status Verwaltung\n\n// Fall 1: xaiId wurde gelöscht (war vorher vorhanden, jetzt leer)\nif (\n    attribute\\fetched('xaiId') != null &&\n    xaiId == null\n) {\n    xaiSyncStatus = 'no_sync';\n}\n// Fall 2: xaiId wird neu gesetzt (war vorher leer, jetzt gefüllt)\nelse if (\n    attribute\\fetched('xaiId') == null &&\n    xaiId != null\n) {\n    xaiSyncStatus = 'pending_sync';\n}\n// Fall 3: Dokument hat xaiId und relevante Felder haben sich geändert\nelse if (\n    xaiId != null &&\n    xaiSyncStatus != 'no_sync' &&\n    (\n        attribute\\isChanged('name') ||\n        attribute\\isChanged('description') ||\n        attribute\\isChanged('dokumentId') ||\n        attribute\\isChanged('md5sum') ||\n        attribute\\isChanged('sha256')\n    )\n) {\n    xaiSyncStatus = 'unclean';\n}\n// Fall 4: Bei neuem Dokument MIT xaiId → pending_sync\nelse if (\n    entity\\isNew() &&\n    xaiId != null\n) {\n    xaiSyncStatus = 'pending_sync';\n}\n// Fall 5: Bei neuem Dokument OHNE xaiId → no_sync\nelse if (\n    entity\\isNew() &&\n    xaiId == null\n) {\n    xaiSyncStatus = 'no_sync';\n}\n\n// Automatische Advoware Sync-Status Verwaltung\n\n// Fall 1: aktennr wurde gelöscht (war vorher vorhanden, jetzt leer)\nif (\n    attribute\\fetched('aktennr') != null &&\n    aktennr == null\n) {\n    syncStatus = 'no_sync';\n}\n// Fall 2: aktennr wird neu gesetzt (war vorher leer, jetzt gefüllt)\nelse if (\n    attribute\\fetched('aktennr') == null &&\n    aktennr != null\n) {\n    syncStatus = 'pending_sync';\n}\n// Fall 3: Dokument hat aktennr und relevante Felder haben sich geändert\nelse if (\n    aktennr != null &&\n    syncStatus != 'no_sync' &&\n    (\n        attribute\\isChanged('name') ||\n        attribute\\isChanged('description') ||\n        attribute\\isChanged('dokumentId') ||\n        attribute\\isChanged('md5sum') ||\n        attribute\\isChanged('sha256')\n    )\n) {\n    syncStatus = 'unclean';\n}\n// Fall 4: Bei neuem Dokument MIT aktennr → pending_sync\nelse if (\n    entity\\isNew() &&\n    aktennr != null\n) {\n    syncStatus = 'pending_sync';\n}\n// Fall 5: Bei neuem Dokument OHNE aktennr → no_sync\nelse if (\n    entity\\isNew() &&\n    aktennr == null\n) {\n    syncStatus = 'no_sync';\n}"
+    "beforeSaveScript": "// Automatische x.AI Sync-Status Verwaltung\n\n// Fall 1: xaiId wurde gelöscht (war vorher vorhanden, jetzt leer)\nif (\n    attribute\\fetched('xaiId') != null &&\n    xaiId == null\n) {\n    xaiSyncStatus = 'no_sync';\n}\n// Fall 2: xaiId wird neu gesetzt (war vorher leer, jetzt gefüllt)\nelse if (\n    attribute\\fetched('xaiId') == null &&\n    xaiId != null\n) {\n    xaiSyncStatus = 'pending_sync';\n}\n// Fall 3: Dokument hat xaiId und relevante Felder haben sich geändert\nelse if (\n    xaiId != null &&\n    xaiSyncStatus != 'no_sync' &&\n    (\n        attribute\\isChanged('name') ||\n        attribute\\isChanged('description') ||\n        attribute\\isChanged('dokumentId') ||\n        attribute\\isChanged('blake3hash')\n    )\n) {\n    xaiSyncStatus = 'unclean';\n}\n// Fall 4: Bei neuem Dokument MIT xaiId → pending_sync\nelse if (\n    entity\\isNew() &&\n    xaiId != null\n) {\n    xaiSyncStatus = 'pending_sync';\n}\n// Fall 5: Bei neuem Dokument OHNE xaiId → no_sync\nelse if (\n    entity\\isNew() &&\n    xaiId == null\n) {\n    xaiSyncStatus = 'no_sync';\n}\n\n// Automatische Advoware Sync-Status Verwaltung\n\n// Fall 1: aktennr wurde gelöscht (war vorher vorhanden, jetzt leer)\nif (\n    attribute\\fetched('aktennr') != null &&\n    aktennr == null\n) {\n    syncStatus = 'no_sync';\n}\n// Fall 2: aktennr wird neu gesetzt (war vorher leer, jetzt gefüllt)\nelse if (\n    attribute\\fetched('aktennr') == null &&\n    aktennr != null\n) {\n    syncStatus = 'pending_sync';\n}\n// Fall 3: Dokument hat aktennr und relevante Felder haben sich geändert\nelse if (\n    aktennr != null &&\n    syncStatus != 'no_sync' &&\n    (\n        attribute\\isChanged('name') ||\n        attribute\\isChanged('description') ||\n        attribute\\isChanged('dokumentId') ||\n        attribute\\isChanged('blake3hash')\n    )\n) {\n    syncStatus = 'unclean';\n}\n// Fall 4: Bei neuem Dokument MIT aktennr → pending_sync\nelse if (\n    entity\\isNew() &&\n    aktennr != null\n) {\n    syncStatus = 'pending_sync';\n}\n// Fall 5: Bei neuem Dokument OHNE aktennr → no_sync\nelse if (\n    entity\\isNew() &&\n    aktennr == null\n) {\n    syncStatus = 'no_sync';\n}"
 }

custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeCDokumente.json

@@ -1,10 +1,11 @@
 {
     "entity": true,
-    "type": "Base",
-    "module": "Custom",
-    "object": true,
-    "isCustom": true,
+    "object": false,
+    "layouts": false,
     "tab": false,
     "acl": true,
-    "disabled": false
+    "customizable": false,
+    "type": "Base",
+    "module": "Custom",
+    "isCustom": true
 }

custom/Espo/Custom/Resources/metadata/scopes/CAIKnowledgeDokumente.json

@@ -0,0 +1,11 @@
+{
+    "entity": true,
+    "object": false,
+    "layouts": false,
+    "tab": false,
+    "acl": true,
+    "customizable": false,
+    "type": "Base",
+    "module": "Custom",
+    "isCustom": true
+}

custom/Espo/Custom/Resources/metadata/scopes/CAdvowareAkten.json

@@ -16,7 +16,7 @@
     "notifications": true,
     "stream": true,
     "disabled": false,
-    "type": "BasePlus",
+    "type": "Base",
     "module": "Custom",
     "object": true,
     "isCustom": true,

custom/Espo/Custom/Resources/routes.json

@@ -0,0 +1,17 @@
+[
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
+        "method": "get",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
+    },
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+        "method": "put",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
+    },
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+        "method": "post",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
+    }
+]

custom/Espo/Custom/Services/CAICollectionCDokumente.php

@@ -1,14 +0,0 @@
-<?php
-namespace Espo\Custom\Services;
-
-use Espo\Services\Record;
-
-/**
- * Junction Service: CAICollection ↔ CDokumente
- * 
- * Handles business logic for the junction table.
- */
-class CAICollectionCDokumente extends Record
-{
-    // Standard CRUD logic inherited from Record service
-}

custom/docs/ESPOCRM_BEST_PRACTICES.md

@@ -1,11 +1,47 @@
 # EspoCRM Best Practices & Entwicklungsrichtlinien
 
-**Version:** 2.2  
-**Datum:** 10. März 2026  
+**Version:** 2.4  
+**Datum:** 12. März 2026  
 **Zielgruppe:** AI Code Agents & Entwickler
 
 ---
 
+## 🔄 Letzte Änderungen (v2.4 - 12. März 2026)
+
+**Neue Features:**
+- ✅ **Custom API Endpoints mit routes.json**: Vollständiges Pattern für moderne Custom API (EspoCRM 7+)
+- ✅ **Junction Table Custom API**: Best Practice für direkte SQL-basierte Junction-Zugriffe
+- ✅ **Real-World Beispiel**: CAIKnowledge Junction API (GET/PUT/POST) mit vollständigem Code
+- ✅ **Performance-Optimierung**: JOIN-Queries in einem Call statt mehrere API-Requests
+- ✅ **ACL-Workaround**: Umgehung von ACL-Problemen bei Junction Entities
+
+**Dokumentierte Patterns:**
+- routes.json Setup und Configuration
+- Action Classes mit Constructor Property Promotion
+- Direkte PDO-Queries für Junction Tables
+- Dynamische UPDATE-Queries mit variablen Feldern
+- Error Handling (BadRequest, NotFound, Forbidden)
+- Snake_case vs CamelCase in DB-Queries
+- Typische Fehler und Debugging-Strategien
+
+---
+
+## 🔄 Letzte Änderungen (v2.3 - 11. März 2026)
+
+**Neue Features:**
+- ✅ **Junction Table UI-Pattern**: columnAttributeMap + notStorable für UI-Anzeige von Junction-Spalten
+- ✅ **Dokumenten-Propagierung**: Hook-Pattern für automatische Verknüpfung zwischen hierarchischen Entities
+- ✅ **Loop-Schutz**: Statisches Processing-Array Pattern für rekursive Hooks
+- ✅ **Troubleshooting**: Vergessene Indizes auf gelöschte Felder (häufiger Rebuild-Fehler)
+
+**Dokumentierte Real-World Implementierung:**
+- CAdvowareAkten/CAIKnowledge Junction Tables mit additionalColumns (hnr, syncstatus, lastSync)
+- Propagierungs-Hooks: Räumungsklage ↔ AdvowareAkten ↔ AIKnowledge
+- Sync-Status-Management mit globalen und Junction-level Status-Feldern
+- Hook-Chain für automatische Status-Propagierung bei Dokumentänderungen
+
+---
+
 ## 🔄 Letzte Änderungen (v2.2 - 10. März 2026)
 
 **Kritische Erkenntnisse:**
@@ -650,6 +686,129 @@ POST /api/v1/CAICollectionCDokumente
 
 **WICHTIG:** additionalColumns funktionieren NICHT über Standard-Relationship-Endpoints! Nur über Junction-Entity-API!
 
+#### Junction-Spalten im UI anzeigen: columnAttributeMap & notStorable
+
+**Problem:** additionalColumns sind nur via Junction-Entity-API zugänglich, nicht in Relationship-Panels.
+
+**Lösung:** columnAttributeMap + notStorable Felder für UI-Anzeige
+
+**Beispiel:** Dokumente mit HNR und Sync-Status in AdvowareAkten
+
+**Parent Entity (CAdvowareAkten):**
+```json
+{
+  "fields": {
+    "dokumenteHnr": {
+      "type": "int",
+      "notStorable": true,
+      "utility": true
+    },
+    "dokumenteSyncstatus": {
+      "type": "enum",
+      "options": ["new", "unclean", "synced", "failed"],
+      "notStorable": true,
+      "utility": true
+    },
+    "dokumenteLastSync": {
+      "type": "datetime",
+      "notStorable": true,
+      "utility": true
+    },
+    "dokumentes": {
+      "type": "linkMultiple",
+      "columns": {
+        "hnr": "advowareAktenHnr",
+        "syncstatus": "advowareAktenSyncstatus",
+        "lastSync": "advowareAktenLastSync"
+      },
+      "view": "views/fields/link-multiple-with-columns"
+    }
+  },
+  "links": {
+    "dokumentes": {
+      "type": "hasMany",
+      "entity": "CDokumente",
+      "foreign": "advowareAktens",
+      "relationName": "cAdvowareAktenDokumente",
+      "additionalColumns": {
+        "hnr": {"type": "int"},
+        "syncstatus": {"type": "varchar", "len": 20},
+        "lastSync": {"type": "datetime"}
+      },
+      "columnAttributeMap": {
+        "hnr": "dokumenteHnr",
+        "syncstatus": "dokumenteSyncstatus",
+        "lastSync": "dokumenteLastSync"
+      }
+    }
+  }
+}
+```
+
+**Foreign Entity (CDokumente):**
+```json
+{
+  "fields": {
+    "advowareAktenHnr": {
+      "type": "int",
+      "notStorable": true,
+      "utility": true,
+      "layoutAvailabilityList": ["listForAdvowareAkten"]
+    },
+    "advowareAktenSyncstatus": {
+      "type": "varchar",
+      "notStorable": true,
+      "utility": true,
+      "layoutAvailabilityList": ["listForAdvowareAkten"]
+    },
+    "advowareAktenLastSync": {
+      "type": "datetime",
+      "notStorable": true,
+      "utility": true,
+      "layoutAvailabilityList": ["listForAdvowareAkten"]
+    }
+  },
+  "links": {
+    "advowareAktens": {
+      "type": "hasMany",
+      "entity": "CAdvowareAkten",
+      "foreign": "dokumentes",
+      "relationName": "cAdvowareAktenDokumente",
+      "columnAttributeMap": {
+        "hnr": "advowareAktenHnr",
+        "syncstatus": "advowareAktenSyncstatus",
+        "lastSync": "advowareAktenLastSync"
+      }
+    }
+  }
+}
+```
+
+**Custom List Layout (layouts/CDokumente/listForAdvowareAkten.json):**
+```json
+[
+  {"name": "name", "width": 25},
+  {"name": "advowareAktenHnr", "width": 10},
+  {"name": "advowareAktenSyncstatus", "width": 12},
+  {"name": "advowareAktenLastSync", "width": 15},
+  {"name": "description", "width": 20},
+  {"name": "dokument", "width": 18}
+]
+```
+
+**Wichtige Konzepte:**
+- **notStorable**: Feld wird nicht in Haupttabelle gespeichert
+- **utility**: Internes Feld, nicht in Standard-Formularen
+- **columnAttributeMap**: Bidirektionales Mapping Junction → UI
+- **layoutAvailabilityList**: Begrenzt Sichtbarkeit auf bestimmte Layouts
+- **columns** in linkMultiple-Field: Verbindet UI-Feldnamen mit Junction-Spalten
+
+**Workflow:**
+1. EspoCRM liest Junction-Spalten über RDB-Funktionen
+2. Mapped sie via columnAttributeMap zu notStorable Feldern
+3. UI zeigt notStorable Felder in Relationship-Panels an
+4. Updates erfolgen via updateColumns() in Hooks
+
 ### 4. Parent Relationship (belongsToParent)
 
 **Beispiel:** Dokument kann zu Räumungsklage ODER Mietinkasso gehören
@@ -812,6 +971,368 @@ curl -X GET "https://crm.example.com/api/v1/CMyEntity" \
 
 ---
 
+### Custom API Endpoints mit routes.json (Modern, EspoCRM 7+)
+
+**Status:** ✅ Empfohlene Methode seit EspoCRM 7.4+ (Controller-Methode deprecated)
+
+#### Wann Custom API Endpoints verwenden?
+
+**✅ Verwende Custom API wenn:**
+- Junction Table additionalColumns lesen/schreiben
+- JOINs über mehrere Tabellen erforderlich
+- ACL-Probleme mit Standard Junction-Entity API
+- Performance-kritische Operationen (viele Datensätze)
+- Spezielle Business Logic ohne Entity-Hooks
+- Hooks sollen NICHT ausgelöst werden
+
+**❌ Verwende Standard API wenn:**
+- Einfache CRUD-Operationen ohne Junction-Spalten
+- ACL-System explizit gewünscht
+- Entity-Hooks sollen ausgelöst werden
+
+#### Implementierungs-Pattern
+
+**1. Routes definieren**
+
+**Datei:** `custom/Espo/Custom/Resources/routes.json`
+
+```json
+[
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
+        "method": "get",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
+    },
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+        "method": "put",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
+    },
+    {
+        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
+        "method": "post",
+        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
+    }
+]
+```
+
+**Wichtig:**
+- **Dateiname:** `routes.json` (NICHT `api.json`!)
+- **Location:** `custom/Espo/Custom/Resources/routes.json`
+- **Namespace:** Doppelte Backslashes in `actionClassName`!
+- **Cache:** Nach Änderungen **IMMER** Clear Cache + Rebuild!
+
+**2. Action Class implementieren**
+
+**Datei:** `custom/Espo/Custom/Api/JunctionData/GetDokumentes.php`
+
+```php
+<?php
+
+namespace Espo\Custom\Api\JunctionData;
+
+use Espo\Core\Api\Action;
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Api\ResponseComposer;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\NotFound;
+use Espo\ORM\EntityManager;
+
+/**
+ * GET /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes
+ * 
+ * Retrieves all documents linked to a knowledge entry with junction data.
+ * Uses direct SQL JOIN for optimal performance.
+ */
+class GetDokumentes implements Action
+{
+    public function __construct(
+        private EntityManager $entityManager
+    ) {}
+    
+    public function process(Request $request): Response
+    {
+        $knowledgeId = $request->getRouteParam('knowledgeId');
+        
+        if (!$knowledgeId) {
+            throw new BadRequest('Knowledge ID is required');
+        }
+        
+        // Validate entity exists
+        $knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
+        if (!$knowledge) {
+            throw new NotFound('Knowledge entry not found');
+        }
+        
+        $pdo = $this->entityManager->getPDO();
+        
+        // Direct SQL with JOIN - much faster than multiple API calls!
+        $sql = "
+            SELECT 
+                j.id as junctionId,
+                j.c_a_i_knowledge_id as cAIKnowledgeId,
+                j.c_dokumente_id as cDokumenteId,
+                j.ai_document_id as aiDocumentId,
+                j.syncstatus,
+                j.last_sync as lastSync,
+                d.id as documentId,
+                d.name as documentName,
+                d.blake3hash as blake3hash,
+                d.created_at as documentCreatedAt,
+                d.modified_at as documentModifiedAt
+            FROM c_a_i_knowledge_dokumente j
+            INNER JOIN c_dokumente d ON j.c_dokumente_id = d.id
+            WHERE j.c_a_i_knowledge_id = :knowledgeId
+              AND j.deleted = 0
+              AND d.deleted = 0
+            ORDER BY j.id DESC
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute(['knowledgeId' => $knowledgeId]);
+        
+        $results = $sth->fetchAll(\PDO::FETCH_ASSOC);
+        
+        return ResponseComposer::json([
+            'total' => count($results),
+            'list' => $results
+        ]);
+    }
+}
+```
+
+**3. Action Class für UPDATE**
+
+**Datei:** `custom/Espo/Custom/Api/JunctionData/UpdateJunction.php`
+
+```php
+<?php
+
+namespace Espo\Custom\Api\JunctionData;
+
+use Espo\Core\Api\Action;
+use Espo\Core\Api\Request;
+use Espo\Core\Api\Response;
+use Espo\Core\Api\ResponseComposer;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\Exceptions\NotFound;
+use Espo\ORM\EntityManager;
+
+/**
+ * PUT /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
+ * 
+ * Updates junction table columns without triggering entity hooks.
+ */
+class UpdateJunction implements Action
+{
+    public function __construct(
+        private EntityManager $entityManager
+    ) {}
+    
+    public function process(Request $request): Response
+    {
+        $knowledgeId = $request->getRouteParam('knowledgeId');
+        $documentId = $request->getRouteParam('documentId');
+        $data = $request->getParsedBody();
+        
+        if (!$knowledgeId || !$documentId) {
+            throw new BadRequest('Knowledge ID and Document ID required');
+        }
+        
+        $pdo = $this->entityManager->getPDO();
+        
+        // Dynamic UPDATE - only fields provided in request body
+        $setClauses = [];
+        $params = [
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ];
+        
+        if (isset($data->aiDocumentId)) {
+            $setClauses[] = "ai_document_id = :aiDocumentId";
+            $params['aiDocumentId'] = $data->aiDocumentId;
+        }
+        
+        if (isset($data->syncstatus)) {
+            $allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
+            if (!in_array($data->syncstatus, $allowedStatuses)) {
+                throw new BadRequest('Invalid syncstatus. Allowed: ' . implode(', ', $allowedStatuses));
+            }
+            $setClauses[] = "syncstatus = :syncstatus";
+            $params['syncstatus'] = $data->syncstatus;
+        }
+        
+        if (isset($data->lastSync)) {
+            $setClauses[] = "last_sync = :lastSync";
+            $params['lastSync'] = $data->lastSync;
+        } elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
+            $setClauses[] = "last_sync = NOW()";
+        }
+        
+        if (empty($setClauses)) {
+            throw new BadRequest('No fields to update');
+        }
+        
+        $sql = "
+            UPDATE c_a_i_knowledge_dokumente
+            SET " . implode(', ', $setClauses) . "
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute($params);
+        
+        if ($sth->rowCount() === 0) {
+            throw new NotFound('Junction entry not found or no changes made');
+        }
+        
+        // Return updated entry
+        return ResponseComposer::json($this->getJunctionEntry($knowledgeId, $documentId));
+    }
+    
+    private function getJunctionEntry(string $knowledgeId, string $documentId): array
+    {
+        $pdo = $this->entityManager->getPDO();
+        
+        $sql = "
+            SELECT 
+                id as junctionId,
+                c_a_i_knowledge_id as cAIKnowledgeId,
+                c_dokumente_id as cDokumenteId,
+                ai_document_id as aiDocumentId,
+                syncstatus,
+                last_sync as lastSync
+            FROM c_a_i_knowledge_dokumente
+            WHERE c_a_i_knowledge_id = :knowledgeId
+              AND c_dokumente_id = :documentId
+              AND deleted = 0
+        ";
+        
+        $sth = $pdo->prepare($sql);
+        $sth->execute([
+            'knowledgeId' => $knowledgeId,
+            'documentId' => $documentId
+        ]);
+        
+        $result = $sth->fetch(\PDO::FETCH_ASSOC);
+        
+        if (!$result) {
+            throw new NotFound('Junction entry not found');
+        }
+        
+        return $result;
+    }
+}
+```
+
+#### Verwendung
+
+**GET: Alle Dokumente mit Junction-Daten**
+```bash
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
+  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4"
+```
+
+**PUT: Junction-Spalten aktualisieren**
+```bash
+curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/69a68b556a39771bf" \
+  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "aiDocumentId": "EXTERNAL-AI-123",
+    "syncstatus": "synced",
+    "updateLastSync": true
+  }'
+```
+
+#### Best Practices
+
+✅ **DO:**
+- Constructor Property Promotion (`private EntityManager $entityManager`)
+- Prepared Statements IMMER (`$pdo->prepare()` + `execute()`)
+- Validierung BEVOR DB-Operations
+- Spezifische Exceptions (`BadRequest`, `NotFound`, `Forbidden`)
+- PHPDoc mit Endpoint-Beschreibung
+- `snake_case` für DB-Spaltennamen beachten!
+- Cache IMMER löschen nach routes.json Änderungen
+
+❌ **DON'T:**
+- Raw SQL ohne Prepared Statements (SQL Injection!)
+- Vergessen `deleted = 0` zu prüfen
+- Camel Case für DB-Spalten annonehmen (DB verwendet snake_case!)
+- Entity-Methods auf routes.json Änderungen verzichten
+- ResponseComposer::json() vergessen
+- Controller-Methode für neue Projekte (deprecated!)
+
+#### Vorteile gegenüber Standard API
+
+| Feature | Standard Junction API | Custom routes.json API |
+|---------|----------------------|------------------------|
+| JOINs | ❌ Mehrere Calls nötig | ✅ Ein Call mit JOIN |
+| Performance | ⚠️ Langsam bei vielen Records | ✅ Optimiert mit direktem SQL |
+| ACL-Probleme | ❌ Oft 403 Forbidden | ✅ Keine ACL-Issues |
+| Hooks | ✅ Werden ausgelöst | ❌ Werden umgangen |
+| Flexibilität | ⚠️ Eingeschränkt | ✅ Volle SQL-Kontrolle |
+| Wartbarkeit | ✅ Standard-Konformität | ⚠️ Custom Code |
+
+#### Typische Fehler
+
+**1. routes.json nicht gefunden**
+```
+❌ custom/Espo/Custom/Resources/metadata/app/api.json
+✅ custom/Espo/Custom/Resources/routes.json
+```
+
+**2. Cache nicht gelöscht**
+```bash
+# PFLICHT nach routes.json Änderungen!
+docker exec espocrm php clear_cache.php
+docker exec espocrm php rebuild.php
+```
+
+**3. Falsche Spalten-Namen**
+```php
+❌ j.lastSync          // CamelCase (falsch!)
+✅ j.last_sync         // snake_case (richtig!)
+```
+
+**4. File Permissions falsch**
+```bash
+# Alle Custom-Dateien müssen www-data:www-data gehören
+chown -R www-data:www-data custom/Espo/Custom/Api/
+```
+
+**5. Namespace-Fehler**
+```json
+❌ "actionClassName": "Espo\Custom\Api\MyAction"
+✅ "actionClassName": "Espo\\Custom\\Api\\MyAction"
+```
+
+#### Debugging
+
+**Check routes cache:**
+```bash
+docker exec espocrm cat data/cache/application/routes.php | grep -i "YourRoute"
+```
+
+**Check logs:**
+```bash
+docker exec espocrm tail -100 data/logs/espo.log | grep -i "error\|exception"
+```
+
+**Test mit curl verbose:**
+```bash
+curl -v "http://localhost:8080/api/v1/YourEndpoint" \
+  -H "X-Api-Key: your-key" 2>&1 | head -30
+```
+
+**Siehe:** `custom/docs/API_ENDPOINTS.md` für vollständige Beispiele
+
+---
+
 ## Hook-Entwicklung
 
 ### Überblick
@@ -897,6 +1418,148 @@ public function __construct(
 - `Acl` - ACL-Prüfungen
 - `User` - Aktueller Benutzer
 
+### Hook-Pattern: Dokumenten-Propagierung mit Loop-Schutz
+
+**Use Case:** Automatische Verknüpfung von Dokumenten zwischen hierarchisch verbundenen Entities:
+- Räumungsklage ↔ AdvowareAkten ↔ AIKnowledge
+- Mietinkasso ↔ AdvowareAkten ↔ AIKnowledge
+
+**Challenge:** Vermeide Endlos-Rekursion bei gegenseitiger Propagierung
+
+**Lösung:** AfterRelate/AfterUnrelate Hooks mit statischem Processing-Array
+
+**Pattern-Beispiel (CVmhRumungsklage → AdvowareAkten + AIKnowledge):**
+
+```php
+<?php
+namespace Espo\Custom\Hooks\CVmhRumungsklage;
+
+use Espo\ORM\Entity;
+use Espo\Core\Hook\Hook\AfterRelate;
+use Espo\Core\Hook\Hook\AfterUnrelate;
+
+class PropagateDocuments implements AfterRelate, AfterUnrelate
+{
+    private static array $processing = [];
+    
+    public function __construct(
+        private \Espo\ORM\EntityManager $entityManager
+    ) {}
+    
+    public function afterRelate(
+        Entity $entity,
+        string $relationName,
+        Entity $foreignEntity,
+        array $columnData,
+        \Espo\ORM\Repository\Option\RelateOptions $options
+    ): void {
+        if ($relationName !== 'dokumentesvmhraumungsklage') {
+            return;
+        }
+        
+        // Loop-Schutz: Eindeutiger Key pro Operation
+        $key = $entity->getId() . '-' . $foreignEntity->getId() . '-relate';
+        if (isset(self::$processing[$key])) {
+            return; // Bereits in Bearbeitung
+        }
+        self::$processing[$key] = true;
+        
+        try {
+            // Hole verbundene AdvowareAkten
+            $advowareAkten = $this->entityManager
+                ->getRDBRepository('CVmhRumungsklage')
+                ->getRelation($entity, 'advowareAkten')
+                ->findOne();
+            
+            if ($advowareAkten) {
+                $this->relateDocument($advowareAkten, 'dokumentes', $foreignEntity);
+            }
+            
+            // Hole verbundene AIKnowledge
+            $aIKnowledge = $this->entityManager
+                ->getRDBRepository('CVmhRumungsklage')
+                ->getRelation($entity, 'aIKnowledge')
+                ->findOne();
+            
+            if ($aIKnowledge) {
+                $this->relateDocument($aIKnowledge, 'dokumentes', $foreignEntity);
+            }
+        } catch (\Exception $e) {
+            $GLOBALS['log']->error('PropagateDocuments Error: ' . $e->getMessage());
+        } finally {
+            unset(self::$processing[$key]); // Cleanup
+        }
+    }
+    
+    public function afterUnrelate(
+        Entity $entity,
+        string $relationName,
+        Entity $foreignEntity,
+        \Espo\ORM\Repository\Option\UnrelateOptions $options
+    ): void {
+        // Analog zu afterRelate, aber mit unrelate()
+    }
+    
+    private function relateDocument(Entity $parent, string $relation, Entity $doc): void
+    {
+        $repository = $this->entityManager->getRDBRepository($parent->getEntityType());
+        $relation = $repository->getRelation($parent, $relation);
+        
+        // Prüfe ob bereits verknüpft (vermeidet Duplikate)
+        $isRelated = $relation->where(['id' => $doc->getId()])->findOne();
+        
+        if (!$isRelated) {
+            $relation->relate($doc);
+        }
+    }
+}
+```
+
+**Propagierungs-Hierarchie:**
+
+```
+┌─────────────────────┐
+│  Räumungsklage      │
+│  Mietinkasso        │
+└──────────┬──────────┘
+           │
+    ┌──────┴──────┐
+    ↓             ↓
+┌──────────┐  ┌──────────┐
+│AdvowareA.│  │AIKnowled.│
+└────┬─────┘  └────┬─────┘
+     │             │
+     └──────┬──────┘
+            ↓
+     ┌──────────┐
+     │ Dokument │
+     └──────────┘
+```
+
+**Down-Propagierung (Räumungsklage → unten):**
+- Hook in Räumungsklage/Mietinkasso
+- Bei Dokumenten-Link → propagiere zu AdvowareAkten + AIKnowledge
+- Deren Hooks versuchen zurück zu propagieren → blockiert durch Loop-Schutz
+
+**Up-Propagierung (AdvowareAkten → oben):**
+- Hook in AdvowareAkten/AIKnowledge  
+- Bei Dokumenten-Link → propagiere zu Räumungsklage/Mietinkasso
+- Deren Hooks propagieren zu anderen Kind-Entities
+- Loop-Schutz verhindert Rück-Propagierung
+
+**Loop-Schutz Mechanismus:**
+1. **Statisches Array**: `private static array $processing = []`
+2. **Eindeutiger Key**: `{EntityID}-{DokumentID}-{Aktion}`
+3. **Check vor Ausführung**: `if (isset(self::$processing[$key])) return;`
+4. **Set bei Start**: `self::$processing[$key] = true;`
+5. **Cleanup**: `finally { unset(self::$processing[$key]); }`
+
+**Vorteile:**
+- Verhindert Endlos-Rekursion
+- Ermöglicht parallele Verarbeitung verschiedener Dokumente
+- Automatisches Cleanup auch bei Exceptions
+- Key-basiert: Verschiedene Operations können gleichzeitig laufen
+
 ### Praxis-Beispiele aus dem Projekt
 
 #### Beispiel 1: Daten-Validierung & Normalisierung (CBankverbindungen)
@@ -1722,6 +2385,89 @@ docker exec espocrm php -l custom/Espo/Custom/Controllers/MyController.php
 - [ ] Action-Methode korrekt benannt? (postAction..., getAction...)
 - [ ] ACL-Rechte?
 
+### ⚠️ KRITISCH: Rebuild schlägt fehl - "Column does not exist"
+
+**Fehlermeldung:**
+```
+Doctrine\DBAL\Schema\SchemaException::columnDoesNotExist('feldname', 'tabelle')
+#2 /var/www/html/application/Espo/Core/Utils/Database/Schema/Builder.php(154):
+Doctrine\DBAL\Schema\Table->addIndex(Array, 'IDX_FELDNAME', Array)
+```
+
+**Symptome:**
+- Rebuild schlägt fehl
+- JSON/PHP-Validierung erfolgreich
+- Fehlermeldung referenziert nicht existierendes Feld
+- Error tritt in Schema-Builder auf
+
+**Ursache:**
+Ein **Index** wurde für ein Feld definiert, das nicht (mehr) existiert.
+
+**Häufigster Fall:**
+1. Feld wird aus entityDefs entfernt
+2. Index-Definition wird vergessen
+3. Rebuild versucht Index auf nicht-existentes Feld zu erstellen
+
+**Beispiel aus Praxis:**
+```json
+// CDokumente.json
+{
+  "fields": {
+    // "aktennr" wurde entfernt ← Feld gelöscht
+  },
+  "indexes": {
+    "aktennr": {              ← Index noch da!
+      "columns": ["aktennr"]
+    }
+  }
+}
+```
+
+**Lösung:**
+
+**Schritt 1:** Identifiziere betroffenes Feld und Entity aus Error-Log
+```
+columnDoesNotExist('aktennr', 'c_dokumente')
+                    ^^^^^^^^   ^^^^^^^^^^^^
+                    Feld       Tabelle
+```
+
+**Schritt 2:** Öffne entityDefs-Datei
+```bash
+code custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json
+```
+
+**Schritt 3:** Suche Index-Definition und entferne sie
+```json
+// VORHER:
+"indexes": {
+  "createdAtId": {...},
+  "aktennr": {              ← ENTFERNEN
+    "columns": ["aktennr"]
+  },
+  "md5sum": {...}
+}
+
+// NACHHER:
+"indexes": {
+  "createdAtId": {...},
+  "md5sum": {...}
+}
+```
+
+**Schritt 4:** Rebuild erneut durchführen
+```bash
+python3 custom/scripts/validate_and_rebuild.py
+```
+
+**Best Practice:**
+Bei Feld-Entfernung immer prüfen:
+1. Feld aus `fields` entfernt?
+2. Link aus `links` entfernt?
+3. **Index aus `indexes` entfernt?** ← Oft vergessen!
+4. Layout-Definitionen aktualisiert?
+5. i18n-Einträge bereinigt?
+
 ### ⚠️ KRITISCH: InjectableFactory Error (Service-Klasse fehlt)
 
 **Fehlermeldung in Logs:**

custom/docs/README.md

@@ -301,6 +301,60 @@ cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
    - i18n fehlt → beide Sprachen anlegen
    - Relationship kaputt → bidirektional prüfen
    - ACL 403 → Rechte in Admin UI
+   - Rebuild schlägt fehl mit "Column does not exist" → Index auf gelöschtes Feld prüfen
+
+---
+
+## 🆕 Neueste Patterns & Best Practices (März 2026)
+
+### Junction Table UI-Integration
+
+**Pattern:** `columnAttributeMap` + `notStorable` Felder
+
+**Use Case:** Junction-Spalten (wie `hnr`, `syncstatus`, `lastSync`) im Relationship-Panel anzeigen.
+
+**Implementierung:**
+- notStorable Felder als UI-Placeholder
+- columnAttributeMap für bidirektionales Mapping
+- Custom List Layouts für Relationship-Panels
+- Hooks für automatische Updates
+
+**Dokumentiert in:** [ESPOCRM_BEST_PRACTICES.md](ESPOCRM_BEST_PRACTICES.md#junction-spalten-im-ui-anzeigen-columnattributemap--notstorable) & [TESTERGEBNISSE_JUNCTION_TABLE.md](TESTERGEBNISSE_JUNCTION_TABLE.md)
+
+### Dokumenten-Propagierung mit Loop-Schutz
+
+**Pattern:** AfterRelate/AfterUnrelate Hooks mit statischem Processing-Array
+
+**Use Case:** Automatische Verknüpfung von Dokumenten zwischen hierarchisch verbundenen Entities.
+
+**Hierarchie-Beispiel:**
+```
+Räumungsklage ←→ AdvowareAkten ←→ AIKnowledge
+Mietinkasso   ←→ AdvowareAkten ←→ AIKnowledge
+        ↓             ↓              ↓
+           Dokumente (automatisch synchronisiert)
+```
+
+**Loop-Schutz:** Statisches Array mit Key `{EntityID}-{DokumentID}-{Aktion}` verhindert Endlos-Rekursion.
+
+**Implementiert in:** `custom/Espo/Custom/Hooks/{CVmhRumungsklage,CMietinkasso,CAdvowareAkten,CAIKnowledge}/Propagate*.php`
+
+**Dokumentiert in:** [ESPOCRM_BEST_PRACTICES.md - Hook-Entwicklung](ESPOCRM_BEST_PRACTICES.md#hook-pattern-dokumenten-propagierung-mit-loop-schutz)
+
+### Sync-Status-Management
+
+**Pattern:** Globaler + Junction-level Status mit automatischer Propagierung
+
+**Struktur:**
+- **Global (Parent):** `syncStatus` (synced/unclean), `lastSync`
+- **Junction (pro Dokument):** `syncstatus` (new/unclean/synced/failed), `lastSync`
+
+**Hooks:**
+- **BeforeSave:** Berechnet globalen Status aus allen Junction-Einträgen
+- **AfterRelate:** Setzt Junction-Status auf "new"
+- **AfterSave (CDokumente):** Markiert alle Junction-Einträge als "unclean" bei Dokumentänderung
+
+**Real-World:** CAdvowareAkten & CAIKnowledge tracken Sync-Status ihrer verknüpften Dokumente.
 
 ---
 
@@ -314,6 +368,7 @@ cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
 
 ---
 
-**Letzte Aktualisierung:** 9. März 2026
+**Letzte Aktualisierung:** 11. März 2026  
+**Version:** 2.3 (Junction Table UI-Integration, Dokumenten-Propagierung, Sync-Status-Management)
 
 **Für Fragen oder Updates:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`

custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md

@@ -1,592 +0,0 @@
-# Many-to-Many Junction-Tabelle mit additionalColumns - Testergebnisse
-
-## ✅ VOLLSTÄNDIG ERFOLGREICH!
-
-**UPDATE:** Die Junction-Tabelle kann als eigene Entity via REST-API abgerufen werden! Seit EspoCRM 6.0.0 werden Junction-Tabellen automatisch als Entities verfügbar gemacht.
-
-## Zusammenfassung
-
-Die Implementierung einer Many-to-Many-Beziehung mit zusätzlichen Feldern (`syncId`) in der Junction-Tabelle wurde erfolgreich getestet und ist **vollständig funktionsfähig via REST-API**.
-
-## ✅ Was funktioniert
-
-### 1. Datenbank-Schema
-**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
-
-Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
-
-```sql
-CREATE TABLE `c_a_i_collection_c_dokumente` (
-  `id` bigint(20) NOT NULL AUTO_INCREMENT,
-  `c_a_i_collections_id` varchar(17),
-  `c_dokumente_id` varchar(17),
-  `sync_id` varchar(255),  ← Unser custom Feld!
-  `deleted` tinyint(1) DEFAULT 0,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
-)
-```
-
-### 2. Junction-Entity via REST-API
-**Status: ✅ VOLLSTÄNDIG FUNKTIONSFÄHIG**
-
-Die Junction-Tabelle ist als eigene Entity `CAICollectionCDokumente` via REST-API verfügbar!
-
-**Beispiel-Abruf:**
-```bash
-GET /api/v1/CAICollectionCDokumente?maxSize=10
-```
-
-**Response:**
-```json
-{
-  "total": 5,
-  "list": [
-    {
-      "id": "6",
-      "deleted": false,
-      "cAICollectionsId": "testcol999",
-      "cDokumenteId": "testdoc999",
-      "syncId": "SYNC-TEST-999",
-      "cAICollectionsName": null,
-      "cDokumenteName": null
-    }
-  ]
-}
-```
-
-**✅ Die `syncId` ist direkt in der API-Response enthalten!**
-
-### 3. Filterung und Suche
-**Status: ✅ FUNKTIONIERT PERFEKT**
-
-Alle Standard-API-Features funktionieren:
-
-**Nach Dokument-ID filtern:**
-```bash
-GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123
-```
-
-**Nach syncId suchen:**
-```bash
-GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=syncId&where[0][value]=SYNC-123
-```
-
-**Felder selektieren:**
-```bash
-GET /api/v1/CAICollectionCDokumente?select=id,cDokumenteId,cAICollectionsId,syncId
-```
-
-### 4. Konfiguration
-**Status: KORREKT IMPLEMENTIERT**
-
-**Erforderliche Dateien:**
-
-**1. Entity-Definition** (`entityDefs/CAICollectionCDokumente.json`):
-```json
-{
-    "fields": {
-        "id": {"type": "id", "dbType": "bigint", "autoincrement": true},
-        "cAICollections": {"type": "link"},
-        "cAICollectionsId": {"type": "varchar", "len": 17, "index": true},
-        "cDokumente": {"type": "link"},
-        "cDokumenteId": {"type": "varchar", "len": 17, "index": true},
-        "syncId": {"type": "varchar", "len": 255, "isCustom": true},
-        "deleted": {"type": "bool", "default": false}
-    },
-    "links": {
-        "cAICollections": {
-            "type": "belongsTo",
-            "entity": "CAICollections"
-        },
-        "cDokumente": {
-            "type": "belongsTo",
-            "entity": "CDokumente"
-        }
-    }
-}
-```
-
-**2. Scope-Definition** (`scopes/CAICollectionCDokumente.json`):
-```json
-{
-    "entity": true,
-    "type": "Base",
-    "module": "Custom",
-    "object": true,
-    "isCustom": true,
-    "tab": false,
-    "acl": true,
-    "disabled": false
-}
-```
-
-**3. Controller** (`Controllers/CAICollectionCDokumente.php`):
-```php
-<?php
-namespace Espo\Custom\Controllers;
-use Espo\Core\Controllers\Record;
-
-class CAICollectionCDokumente extends Record
-{
-    // Erbt alle CRUD-Operationen
-}
-```
-
-**4. Service** (`Services/CAICollectionCDokumente.php`):
-```php
-<?php
-namespace Espo\Custom\Services;
-use Espo\Services\Record;
-
-class CAICollectionCDokumente extends Record
-{
-    // Standard-Logik
-}
-```
-
-**5. Many-to-Many-Beziehung in CDokumente.json:**
-```json
-"cAICollections": {
-    "type": "hasMany",
-    "entity": "CAICollections",
-    "foreign": "cDokumente",
-    "relationName": "cAICollectionCDokumente",
-    "additionalColumns": {
-        "syncId": {
-            "type": "varchar",
-            "len": 255
-        }
-    }
-}
-```
-
-**6. ACL-Berechtigungen:**
-Die Rolle muss Zugriff auf die Junction-Entity haben:
-```json
-{
-  "CAICollectionCDokumente": {
-    "create": "yes",
-    "read": "all",
-    "edit": "all",
-    "delete": "all"
-  }
-}
-```
-
-## 💡 Verwendung
-
-### Beispiel 1: Alle Verknüpfungen eines Dokuments abrufen
-
-**Python:**
-```python
-import requests
-
-response = requests.get(
-    "https://your-crm.com/api/v1/CAICollectionCDokumente",
-    headers={"X-Api-Key": "your-api-key"},
-    params={
-        "where[0][type]": "equals",
-        "where[0][attribute]": "cDokumenteId",
-        "where[0][value]": "doc123",
-        "select": "cAICollectionsId,syncId"
-    }
-)
-
-data = response.json()
-for item in data['list']:
-    print(f"Collection: {item['cAICollectionsId']}, SyncID: {item['syncId']}")
-```
-
-**cURL:**
-```bash
-curl "https://your-crm.com/api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123" \
-  -H "X-Api-Key: your-api-key"
-```
-
-### Beispiel 2: Dokument in Collection via syncId finden
-
-```python
-response = requests.get(
-    "https://your-crm.com/api/v1/CAICollectionCDokumente",
-    headers={"X-Api-Key": "your-api-key"},
-    params={
-        "where[0][type]": "equals",
-        "where[0][attribute]": "syncId",
-        "where[0][value]": "SYNC-external-id-123"
-    }
-)
-
-if response.json()['list']:
-    match = response.json()['list'][0]
-    doc_id = match['cDokumenteId']
-    col_id = match['cAICollectionsId']
-    print(f"Found: Document {doc_id} in Collection {col_id}")
-```
-
-### Beispiel 3: Neue Verknüpfung mit syncId erstellen
-
-**Via Standard-API (POST):**
-```python
-# Erstelle Verknüpfung
-response = requests.post(
-    "https://your-crm.com/api/v1/CAICollectionCDokumente",
-    headers={"X-Api-Key": "your-api-key"},
-    json={
-        "cDokumenteId": "doc123",
-        "cAICollectionsId": "col456",
-        "syncId": "SYNC-2026-001"
-    }
-)
-```
-
-### Beispiel 4: syncId aktualisieren
-
-```python
-# Aktualisiere einen bestehenden Eintrag
-response = requests.put(
-    f"https://your-crm.com/api/v1/CAICollectionCDokumente/{junction_id}",
-    headers={"X-Api-Key": "your-api-key"},
-    json={
-        "syncId": "SYNC-UPDATED-002"
-    }
-)
-```
-
-## 📊 Test-Ergebnisse
-
-| Feature | Status | Notizen |
-|---------|--------|---------|
-| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
-| Junction-Entity via API | ✅ | Vollständig funktionsfähig |
-| syncId in API-Response | ✅ | Direkt verfügbar |
-| Filterung (where) | ✅ | Standard-API-Syntax |
-| Sortierung (orderBy) | ✅ | Funktioniert |
-| Paginierung (maxSize, offset) | ✅ | Funktioniert |
-| CREATE via API | ✅ | POST mit allen Feldern |
-| UPDATE via API | ✅ | PUT zum Ändern von syncId |
-| DELETE via API | ✅ | Standard-DELETE |
-| View-Darstellung | ❌ | Nicht empfohlen - verursacht 405 Fehler |
-
-## ⚠️ UI-Panel Warnung
-
-**WICHTIG:** additionalColumns sollten NICHT in Standard-Relationship-Panels angezeigt werden!
-
-**Problem:**
-- Standard relationship panels versuchen inline-editing
-- Dies führt zu 405 Method Not Allowed Fehlern
-- additionalColumns sind nicht kompatibel mit Standard-Panel-Architektur
-
-**Empfehlung:**
-- ✅ Nutze API-only Access Pattern
-- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
-- ❌ NICHT in CDokumente detail view als relationship panel anzeigen
-
-## 🎯 Fazit
-
-Die **Junction-Tabelle mit `additionalColumns` ist vollständig via REST-API nutzbar**! 
-
-**Vorteile:**
-- ✅ Keine Custom-Endpoints nötig
-- ✅ Standard-API-Features (Filter, Sort, Pagination)
-- ✅ CRUD-Operationen vollständig unterstützt
-- ✅ `syncId` ist direkt in der Response
-- ✅ Einfache Integration in externe Systeme
-- ✅ API-only Pattern verhindert 405-Fehler
-
-**Einschränkungen:**
-- ⚠️ UI-Darstellung in Standard-Relationship-Panels verursacht 405 Fehler
-- ⚠️ additionalColumns nur über Junction-Entity-API zugänglich
-- ⚠️ Standard relationship endpoints (z.B. GET /api/v1/CDokumente/{id}/cAICollections) geben additionalColumns NICHT zurück
-
-**Best Practice:**
-1. ✅ Junction Entity als API-Endpoint nutzen (`/api/v1/CAICollectionCDokumente`)
-2. ✅ Keine UI-Panels für Junction-Relationships mit additionalColumns
-3. ✅ API-Integration für externe Systeme (Middleware, KI, etc.)
-4. ✅ Bei Bedarf: Separate Management-UI für Junction Entity (ohne Relationship-Panel)
-
-**Wichtig:**
-1. Controller und Service erstellen
-2. Scope-Definition anlegen
-3. Entity-Definition mit korrekten Feldtypen
-4. ACL-Rechte für die Junction-Entity setzen
-5. Cache löschen und rebuild
-6. **NICHT** als Relationship-Panel in UI anzeigen (→ 405 Fehler)
-
-## 📁 Dateien
-
-Die Implementierung befindet sich in:
-- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollectionCDokumente.json`
-- `/custom/Espo/Custom/Resources/metadata/scopes/CAICollectionCDokumente.json`
-- `/custom/Espo/Custom/Controllers/CAICollectionCDokumente.php`
-- `/custom/Espo/Custom/Services/CAICollectionCDokumente.php`
-- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json` (mit additionalColumns)
-- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
-
-Datenbank-Tabelle:
-- `c_a_i_collection_c_dokumente`
-
----
-
-**Erstellt:** 9. März 2026  
-**Getestet mit:** EspoCRM 9.3.2 (MariaDB 12.2.2, PHP 8.2.30)  
-**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)  
-**Entity-Name:** CAICollectionCDokumente  
-**API-Endpoint:** `/api/v1/CAICollectionCDokumente`
-
-
-### 1. Datenbank-Schema
-**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
-
-Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
-
-```sql
-CREATE TABLE `c_a_i_collection_c_dokumente` (
-  `id` bigint(20) NOT NULL AUTO_INCREMENT,
-  `c_a_i_collections_id` varchar(17),
-  `c_dokumente_id` varchar(17),
-  `sync_id` varchar(255),  ← Unser custom Feld!
-  `deleted` tinyint(1) DEFAULT 0,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
-)
-```
-
-### 2. Konfiguration
-**Status: KORREKT IMPLEMENTIERT**
-
-Die Beziehung wurde in beiden Entity-Definitionen konfiguriert:
-
-**CDokumente.json:**
-```json
-"cAICollections": {
-    "type": "hasMany",
-    "entity": "CAICollections",
-    "foreign": "cDokumente",
-    "relationName": "cAICollectionCDokumente",
-    "additionalColumns": {
-        "syncId": {
-            "type": "varchar",
-            "len": 255
-        }
-    }
-}
-```
-
-**CAICollections.json:**
-```json
-"cDokumente": {
-    "type": "hasMany",
-    "entity": "CDokumente",
-    "foreign": "cAICollections",
-    "relationName": "cAICollectionCDokumente"
-}
-```
-
-### 3. Datenspeicherung
-**Status: FUNKTIONIERT**
-
-Die `syncId` kann in der Datenbank gespeichert werden:
-- ✅ Via direktes SQL-INSERT/UPDATE
-- ✅ Via interne EspoCRM ORM-API (EntityManager)
-- ✅ Daten werden korrekt persistiert
-
-### 4. View-Darstellung
-**Status: ⚠️ NICHT EMPFOHLEN (API-ONLY PATTERN)**
-
-**Problem:** Standard EspoCRM Relationship-Panels versuchen inline-editing von Feldern. Bei additionalColumns führt dies zu **405 Method Not Allowed** Fehlern, da die Standard-Panel-UI nicht mit dem Junction-Entity-Pattern kompatibel ist.
-
-**Versucht & Fehlgeschlagen:**
-1. ❌ Direct display of syncId in relationship panel layout → 405 Fehler
-2. ❌ Custom View mit actionEditLinkData → Blank views, dann weiter 405 Fehler
-3. ❌ Simplified relationship layout ohne syncId → 405 Fehler blieben bestehen
-
-**ROOT CAUSE:** Standard relationship panels senden HTTP-Requests die nicht mit Junction-Entity-Architektur übereinstimmen. additionalColumns erfordern spezielle Behandlung die nicht durch Standard-UI bereitgestellt wird.
-
-**LÖSUNG:** API-ONLY Access Pattern
-- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
-- ✅ Kein UI-Panel in CDokumente → keine 405 Fehler
-- ✅ Alle Funktionen über REST API verfügbar
-- ✅ Perfekt für externe Systeme und Middleware
-
-**Falls UI Display gewünscht:**
-- Option: Custom Panel das direkt die Junction Entity list-view lädt (gefiltert nach documentId)
-- Option: Separate Tab/Page für Junction Entity-Management
-- Nicht empfohlen: Standard relationship panel mit additionalColumns
-
-## ❌ Was NICHT funktioniert
-
-### REST-API gibt keine additionalColumns zurück
-**Status: LIMITATION DER STANDARD-API**
-
-**Das Problem:**
-Die Standard-EspoCRM REST-API gibt die `additionalColumns` **nicht** zurück, wenn Beziehungen abgerufen werden.
-
-**Getestete Szenarien:**
-1. ❌ Standard GET-Request: `GET /api/v1/CDokumente/{id}/cAICollections` → keine `syncId` in Response
-2. ❌ Mit Query-Parametern (select, additionalColumns, columns, etc.) → keine `syncId`
-3. ❌ POST mit columns-Parameter beim Verknüpfen → wird nicht gespeichert
-
-**Verifiziert:**
-```bash
-# syncId ist in DB:
-SELECT * FROM c_a_i_collection_c_dokumente;
-# → sync_id = 'SYNC-20260309-220416'
-
-# Aber API-Response enthält sie nicht:
-GET /api/v1/CDokumente/{id}/cAICollections
-# → {"list": [{"id": "...", "name": "...", ...}]}  # Keine syncId!
-```
-
-## 💡 Lösungen & Workarounds
-
-### Option 1: Interne PHP-API verwenden (Empfohlen)
-Verwende die interne EspoCRM-API für den Zugriff auf `additionalColumns`:
-
-```php
-$entityManager = $container->get('entityManager');
-$doc = $entityManager->getEntity('CDokumente', $docId);
-$repository = $entityManager->getRDBRepository('CDokumente');
-$relation = $repository->getRelation($doc, 'cAICollections');
-
-// Lade verknüpfte Collections
-$collections = $relation->find();
-
-// Hole additionalColumns
-foreach ($collections as $col) {
-    $relationData = $relation->getColumnAttributes($col, ['syncId']);
-    $syncId = $relationData['syncId'] ?? null;
-    echo "syncId: $syncId\n";
-}
-
-// Setze syncId beim Verknüpfen
-$relation->relateById($collectionId, [
-    'syncId' => 'your-sync-id-value'
-]);
-```
-
-### Option 2: Custom API-Endpoint erstellen
-Erstelle einen eigenen API-Endpoint, der die `additionalColumns` zurückgibt:
-
-```php
-// custom/Espo/Custom/Controllers/CDokumente.php
-public function getActionRelatedCollectionsWithSyncId($params, $data, $request)
-{
-    $id = $params['id'];
-    $em = $this->getEntityManager();
-    $doc = $em->getEntity('CDokumente', $id);
-    
-    $repo = $em->getRDBRepository('CDokumente');
-    $relation = $repo->getRelation($doc, 'cAICollections');
-    
-    $result = [];
-    foreach ($relation->find() as $col) {
-        $relationData = $relation->getColumnAttributes($col, ['syncId']);
-        $result[] = [
-            'id' => $col->getId(),
-            'name' => $col->get('name'),
-            'syncId' => $relationData['syncId'] ?? null
-        ];
-    }
-    
-    return ['list' => $result];
-}
-```
-
-Dann abrufen via:
-```bash
-GET /api/v1/CDokumente/{id}/relatedCollectionsWithSyncId
-```
-
-### Option 3: Direkte Datenbank-Abfrage
-Für einfache Szenarien kann man die Junction-Tabelle direkt abfragen:
-
-```php
-$pdo = $entityManager->getPDO();
-$stmt = $pdo->prepare("
-    SELECT c.*, j.sync_id 
-    FROM c_a_i_collections c
-    JOIN c_a_i_collection_c_dokumente j 
-        ON c.id = j.c_a_i_collections_id
-    WHERE j.c_dokumente_id = ? 
-        AND j.deleted = 0 
-        AND c.deleted = 0
-");
-$stmt->execute([$docId]);
-$results = $stmt->fetchAll(PDO::FETCH_ASSOC);
-```
-
-### Option 4: Formulas für automatische Synchronisation
-Nutze EspoCRM-Formulas um `syncId` zu setzen:
-
-```
-// In CDokumente.json oder als Workflow
-entity\setLinkMultipleColumn('cAICollections', collectionId, 'syncId', 'your-value');
-```
-
-## 📊 Test-Ergebnisse
-
-| Feature | Status | Notizen |
-|---------|--------|---------|
-| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
-| additionalColumns in Entity-Defs | ✅ | Korrekt konfiguriert |
-| syncId in Datenbank speichern | ✅ | Via SQL oder interne API |
-| syncId über REST-API setzen | ❌ | Wird ignoriert |
-| syncId über REST-API abrufen | ❌ | Nicht in Response |
-| syncId über interne API | ✅ | Vollständig funktionsfähig |
-| View-Darstellung | ✅* | Möglich, aber manuell konfigurieren |
-
-*) Benötigt manuelle Layout-Konfiguration
-
-## 🎯 Fazit
-
-Die **technische Implementierung der Many-to-Many-Beziehung mit `additionalColumns` funktioniert einwandfrei**. Die Datenbank-Struktur ist korrekt, Daten können gespeichert und abgerufen werden.
-
-**Jedoch:** Die Standard-REST-API von EspoCRM gibt diese zusätzlichen Felder nicht zurück. Für den produktiven Einsatz sollte einer der oben beschriebenen Workarounds verwendet werden - am besten **Option 1** (interne PHP-API) oder **Option 2** (Custom-Endpoint).
-
-## 📁 Dateien
-
-Die Konfiguration befindet sich in:
-- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json`
-- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
-
-Datenbank-Tabelle:
-- `c_a_i_collection_c_dokumente`
-
-## 🔧 Verwendung
-
-### Beispiel: Dokument in Collection mit Sync-ID einfügen (PHP)
-
-```php
-$entityManager = $container->get('entityManager');
-
-// Entities laden
-$doc = $entityManager->getEntity('CDokumente', $docId);
-$collection = $entityManager->getEntity('CAICollections', $collectionId);
-
-// Verknüpfen mit syncId
-$repo = $entityManager->getRDBRepository('CDokumente');
-$relation = $repo->getRelation($doc, 'cAICollections');
-$relation->relateById($collectionId, [
-    'syncId' => 'my-unique-sync-id-123'
-]);
-
-// SyncId auslesen
-$relationData = $relation->getColumnAttributes($collection, ['syncId']);
-echo $relationData['syncId']; // 'my-unique-sync-id-123'
-```
-
-### Beispiel: Dokument in Collection finden via Sync-ID
-
-```sql
-SELECT c_dokumente_id, c_a_i_collections_id, sync_id
-FROM c_a_i_collection_c_dokumente
-WHERE sync_id = 'my-unique-sync-id-123'
-  AND deleted = 0;
-```
-
----
-
-**Erstellt:** 9. März 2026  
-**Getestet mit:** EspoCRM (MariaDB 12.2.2, PHP 8.2.30)  
-**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)

custom/scripts/install_blake3.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# Blake3 PHP Extension Installation Script
+# Für EspoCRM Docker Container
+
+set -e  # Beende bei Fehler
+
+echo "========================================="
+echo "Blake3 PHP Extension Installation"
+echo "========================================="
+
+# Schritt 1: Build-Tools installieren
+echo ""
+echo "Schritt 1: Installiere Build-Tools..."
+apt-get update
+apt-get install -y \
+    git \
+    build-essential \
+    autoconf \
+    automake \
+    libtool \
+    pkg-config \
+    curl \
+    libcurl4-openssl-dev
+
+# PHP-Dev ist bereits im Image vorhanden
+echo "PHP Development headers: $(php-config --version)"
+
+# Schritt 2: Blake3 C-Bibliothek klonen
+echo ""
+echo "Schritt 2: Lade Blake3 C-Bibliothek..."
+cd /tmp
+rm -rf BLAKE3 php-blake3
+git clone https://github.com/BLAKE3-team/BLAKE3.git
+cd BLAKE3/c
+gcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S blake3_avx2_x86-64_unix.S blake3_avx512_x86-64_unix.S -fPIC
+cp libblake3.so /usr/local/lib/
+ldconfig
+
+# Schritt 3: PHP Blake3 Extension klonen und kompilieren
+echo ""
+echo "Schritt 3: Kompiliere PHP Blake3 Extension..."
+cd /tmp
+git clone https://github.com/cypherbits/php-blake3.git
+cd php-blake3
+
+phpize
+./configure
+make
+make install
+
+# Schritt 4: Extension aktivieren
+echo ""
+echo "Schritt 4: Aktiviere Blake3 Extension..."
+PHP_INI_DIR=$(php -i | grep "Scan this dir for additional .ini files" | cut -d'>' -f2 | xargs)
+if [ -z "$PHP_INI_DIR" ]; then
+    PHP_INI_DIR="/usr/local/etc/php/conf.d"
+fi
+
+echo "extension=blake3.so" > ${PHP_INI_DIR}/99-blake3.ini
+
+# Schritt 5: Verifizierung
+echo ""
+echo "Schritt 5: Verifiziere Installation..."
+php -m | grep -i blake3
+if [ $? -eq 0 ]; then
+    echo "✅ Blake3 Extension erfolgreich installiert!"
+    php -r "echo 'Test Hash: ' . hash('blake3', 'test') . PHP_EOL;"
+else
+    echo "❌ Blake3 Extension nicht geladen!"
+    exit 1
+fi
+
+# Cleanup
+echo ""
+echo "Schritt 6: Aufräumen..."
+cd /
+rm -rf /tmp/BLAKE3 /tmp/php-blake3
+
+echo ""
+echo "========================================="
+echo "✅ Installation abgeschlossen!"
+echo "========================================="
+echo ""
+echo "Nächste Schritte:"
+echo "1. Starte PHP-FPM neu: service php8.4-fpm restart || pkill -USR2 php-fpm"
+echo "2. Überprüfe: php -m | grep blake3"
+echo "3. Teste: php -r \"echo hash('blake3', 'test');\""

data/config.php

@@ -360,7 +360,7 @@ return [
     0 => 'youtube.com',
     1 => 'google.com'
   ],
-  'microtime' => 1773256040.239404,
+  'microtime' => 1773351590.672055,
   'siteUrl' => 'https://crm.bitbylaw.com',
   'fullTextSearchMinLength' => 4,
   'webSocketUrl' => 'ws://api.bitbylaw.com:5000/espocrm/ws',

data/state.php

@@ -1,7 +1,7 @@
 <?php
 return [
-  'cacheTimestamp' => 1773256148,
-  'microtimeState' => 1773256148.816542,
+  'cacheTimestamp' => 1773351602,
+  'microtimeState' => 1773351602.052184,
   'currencyRates' => [
     'EUR' => 1.0
   ],