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.

2026-03-12 22:52:42 +01:00
parent bf0f596ad4
commit faffe3d874
3 changed files with 821 additions and 1097 deletions
--- a/custom/docs/API_ENDPOINTS.md
+++ b/custom/docs/API_ENDPOINTS.md
@@ -1,12 +1,12 @@
 # REST API Endpunkte - EspoCRM Custom Entities

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

 **Changelog:**
+- v1.4 (12. März 2026): Custom API Endpoints mit routes.json Pattern hinzugefügt; Standard Junction Entity API Dokumentation entfernt (nur Custom API Pattern wird verwendet)
 - v1.3 (11. März 2026): pending_sync Status zu globalem syncStatus hinzugefügt
- v1.2 (11. März 2026): syncedHash-Feld zu Junction-Tables hinzugefügt
 - v1.1 (11. März 2026): Aktivierungsstatus-Feld hinzugefügt (new, active, paused, deactivated)
 - v1.0 (11. März 2026): Initiale Version

@@ -31,10 +31,8 @@ Alle API-Requests benötigen einen API-Key im Header:

 1. [CAdvowareAkten (Advoware Akten)](#cadvowareakten-advoware-akten)
 2. [CAIKnowledge (AI Knowledge Base)](#caiknowledge-ai-knowledge-base)
-3. [Junction Tables](#junction-tables)
-   - [CAdvowareAktenCDokumente](#cadvowareaktencdokumente-junction)
-   - [CAIKnowledgeCDokumente](#caiknowledgecdokumente-junction)
-4. [CDokumente (Dokumente)](#cdokumente-dokumente)
+3. [CDokumente (Dokumente)](#cdokumente-dokumente)
+4. [Custom API Endpoints für Junction Tables](#-custom-api-endpoints-für-junction-tables-best-practice)
 5. [Filtering & Sorting](#filtering--sorting)
 6. [Praktische Beispiele](#praktische-beispiele)

@@ -177,7 +175,7 @@ GET /api/v1/CAdvowareAkten/{id}/dokumentes
 }
 ```

-**⚠️ WICHTIG:** Diese Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Junction API Endpoint](#cadvowareaktencdokumente-junction).
+**⚠️ WICHTIG:** Dieser Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Custom Junction API Endpoint](#-custom-api-endpoints-für-junction-tables-best-practice).

 #### Dokument mit Akte verknüpfen
 ```http
@@ -335,7 +333,7 @@ DELETE /api/v1/CAIKnowledge/{id}
 GET /api/v1/CAIKnowledge/{id}/dokumentes
 ```

-**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [CAIKnowledgeCDokumente Junction API](#caiknowledgecdokumente-junction).
+**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [Custom Junction API Endpoint](#-custom-api-endpoints-für-junction-tables-best-practice).

 #### Dokument verknüpfen
 ```http
@@ -387,209 +385,6 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&wh

 ---

-## Junction Tables
-
-### CAdvowareAktenCDokumente (Junction)
-
-**Entity:** Junction-Tabelle zwischen CAdvowareAkten und CDokumente mit additionalColumns
-
-**Verfügbare Felder:**
- `cAdvowareAktenId` - ID der Akte
- `cDokumenteId` - ID des Dokuments
- `hnr` - Advoware HNR-Referenz (varchar, 255)
- `syncStatus` - Sync-Status (enum: new, changed, synced, deleted)
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
- `deleted` - Soft-Delete Flag
-
-#### Alle Junction-Einträge
-```http
-GET /api/v1/CAdvowareAktenCDokumente
-```
-
-**Response:**
-```json
-{
-  "total": 150,
-  "list": [
-    {
-      "id": "1",
-      "cAdvowareAktenId": "akte-123",
-      "cDokumenteId": "dok-456",
-      "hnr": "42",
-      "syncStatus": "synced",
-      "syncedHash": "a3f5c8b9e2d1...",
-      "deleted": false
-    },
-    {
-      "id": "2",
-      "cAdvowareAktenId": "akte-123",
-      "cDokumenteId": "dok-789",
-      "hnr": "43",
-      "syncStatus": "new",
-      "syncedHash": null,
-      "deleted": false
-    }
-  ]
-}
-```
-
-#### Einzelnen Junction-Eintrag abrufen
-```http
-GET /api/v1/CAdvowareAktenCDokumente/{id}
-```
-
-#### Alle Dokumente einer Akte mit Junction-Spalten
-```http
-GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123
-```
-
-**Response:**
-```json
-{
-  "total": 5,
-  "list": [
-    {
-      "id": "1",
-      "cAdvowareAktenId": "akte-123",
-      "cDokumenteId": "dok-456",
-      "hnr": "42",
-      "syncStatus": "synced",
-      "syncedHash": "a3f5c8b9e2d1..."
-    }
-  ]
-}
-```
-
-#### Nach HNR filtern
-```http
-GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=hnr&where[0][value]=42
-```
-
-#### Nach syncStatus filtern
-```http
-GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed
-```
-
-#### Neuen Junction-Eintrag erstellen (Dokument mit Akte + HNR verknüpfen)
-```http
-POST /api/v1/CAdvowareAktenCDokumente
-Content-Type: application/json
-
-{
-  "cAdvowareAktenId": "akte-123",
-  "cDokumenteId": "dok-999",
-  "hnr": "50",
-  "syncStatus": "new",
-  "syncedHash": null
-}
-```
-
-**Response:**
-```json
-{
-  "id": "15"
-}
-```
-
-#### Junction-Spalten aktualisieren
-```http
-PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
-Content-Type: application/json
-
-{
-  "syncStatus": "synced",
-  "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4",
-  "hnr": "51"
-}
-```
-
-#### Junction-Eintrag löschen
-```http
-DELETE /api/v1/CAdvowareAktenCDokumente/{id}
-```
-
---
-
-### CAIKnowledgeCDokumente (Junction)
-
-**Entity:** Junction-Tabelle zwischen CAIKnowledge und CDokumente mit additionalColumns
-
-**Verfügbare Felder:**
- `cAIKnowledgeId` - ID des AI Knowledge Entry
- `cDokumenteId` - ID des Dokuments
- `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255)
- `syncstatus` - Sync-Status (enum: new, unclean, synced, failed, unsupported)
- `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
- `deleted` - Soft-Delete Flag
-
-#### Alle Junction-Einträge
-```http
-GET /api/v1/CAIKnowledgeCDokumente
-```
-
-**Response:**
-```json
-{
-  "total": 80,
-  "list": [
-    {
-      "id": "1",
-      "cAIKnowledgeId": "kb-123",
-      "cDokumenteId": "dok-456",
-      "aiDocumentId": "ai-doc-external-789",
-      "syncstatus": "synced",
-      "lastSync": "2026-03-11 19:00:00",
-      "syncedHash": "b4e2a9c7f3d8...",
-      "deleted": false
-    }
-  ]
-}
-```
-
-#### Alle Dokumente eines Knowledge Entry mit Junction-Spalten
-```http
-GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=cAIKnowledgeId&where[0][value]=kb-123
-```
-
-#### Nach aiDocumentId suchen
-```http
-GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789
-```
-
-#### Nach syncstatus filtern
-```http
-GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=syncstatus&where[0][value]=unclean
-```
-
-#### Neuen Junction-Eintrag erstellen
-```http
-POST /api/v1/CAIKnowledgeCDokumente
-Content-Type: application/json
-
-{
-  "cAIKnowledgeId": "kb-123",
-  "cDokumenteId": "dok-999",
-  "aiDocumentId": "ai-doc-new-123",
-  "syncstatus": "new",
-  "syncedHash": null
-}
-```
-
-#### Junction-Spalten aktualisieren
-```http
-PUT /api/v1/CAIKnowledgeCDokumente/{junctionId}
-Content-Type: application/json
-
-{
-  "syncstatus": "synced",
-  "lastSync": "2026-03-11T20:30:00+00:00",
-  "syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3"
-}
-```
-
---
-
 ## CDokumente (Dokumente)

 **Entity:** Dokumentenverwaltung
@@ -710,49 +505,41 @@ curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals
 ### Beispiel 2: Alle Dokumente einer Akte mit Junction-Spalten

 ```bash
-# Schritt 1: Hole Akte
-curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+# Custom API Endpoint für CAIKnowledge (siehe Custom API Sektion unten)
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
  -H "X-Api-Key: your-api-key"

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

-### Beispiel 3: Dokument mit Akte + HNR verknüpfen
+### Beispiel 3: Junction-Spalten aktualisieren

 ```bash
-# Via Junction API (empfohlen)
-curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
+# Via Custom Junction API Endpoint (empfohlen)
+curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
-    "cAdvowareAktenId": "akte-123",
-    "cDokumenteId": "dok-789",
-    "hnr": "42",
-    "syncStatus": "new",
-    "syncedHash": null
+    "aiDocumentId": "EXTERNAL-AI-123",
+    "syncstatus": "synced",
+    "updateLastSync": true
  }'
 ```

 ### Beispiel 4: Sync-Status aktualisieren nach erfolgreicher Synchronisation

 ```bash
-# Schritt 1: Finde Junction-Eintrag
-JUNCTION_ID=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&where[1][type]=equals&where[1][attribute]=cDokumenteId&where[1][value]=dok-789&select=id" \
-  -H "X-Api-Key: your-api-key" | jq -r '.list[0].id')
-
-# Schritt 2: Update Junction-Status
-curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_ID" \
+# Direktes Update mit Custom API (kein Suchen nötig!)
+curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
-    "syncStatus": "synced",
-    "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4"
+    "syncstatus": "synced",
+    "updateLastSync": true
  }'

-# Schritt 3: Update global status (optional, Hooks machen das automatisch)
-curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
+# Update global status (optional, Hooks machen das automatisch)
+curl -X PUT "https://crm.example.com/api/v1/CAIKnowledge/kb-123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
@@ -765,19 +552,18 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
 ### Beispiel 5: Suche AI-Dokument via externe ID

 ```bash
-# Finde Junction-Eintrag via aiDocumentId
-curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789" \
-  -H "X-Api-Key: your-api-key"
-
-# Response enthält cDokumenteId zum Abrufen des vollen Dokuments
+# Custom API gibt alle Dokumente mit Junction-Daten zurück
+# Clientseitig filtern nach aiDocumentId:
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
+  -H "X-Api-Key: your-api-key" | jq '.list[] | select(.aiDocumentId=="ai-doc-external-789")'
 ```

 ### Beispiel 6: Alle neuen/geänderten Dokumente für Sync

 ```bash
-# Finde alle Junction-Einträge die "new" oder "changed" sind
-curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus,syncedHash" \
-  -H "X-Api-Key: your-api-key"
+# Custom API gibt alle Dokumente zurück - clientseitig filtern nach syncstatus
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
+  -H "X-Api-Key: your-api-key" | jq '.list[] | select(.syncstatus=="new" or .syncstatus=="unclean")'
 ```

 ### Beispiel 7: Alle aktiven Akten abrufen
@@ -840,49 +626,6 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \

 ## 🎯 Wichtige Hinweise

-### syncedHash - Änderungserkennung
-
-**Zweck:** Hash-basierte Versionierung zur Erkennung von Dokumentänderungen zwischen Synchronisationen
-
-**Verwendung:**
-```bash
-# 1. Nach erfolgreicher Synchronisation: Hash berechnen und speichern
-curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/123" \
-  -H "X-Api-Key: your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "syncStatus": "synced",
-    "syncedHash": "sha256:a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
-  }'
-
-# 2. Bei nächster Synchronisation: Aktuellen Hash mit syncedHash vergleichen
-# Wenn unterschiedlich → Dokument wurde geändert → syncStatus = "changed"
-```
-
-**Hash-Berechnung:**
-```python
-import hashlib
-
-# Beispiel: Hash aus Dokument-Metadaten berechnen
-def calculate_document_hash(document):
-    content = f"{document['name']}|{document['modifiedAt']}|{document['size']}"
-    return hashlib.sha256(content.encode()).hexdigest()
-```
-
-**Workflow:**
-1. **Initial Sync:** syncedHash = NULL, syncStatus = "new"
-2. **Sync durchgeführt:** syncedHash = berechnet, syncStatus = "synced"
-3. **Dokument geändert:** Hook setzt syncStatus = "unclean"
-4. **Nächster Sync:** Vergleiche aktuellen Hash mit syncedHash
-   - Gleich → Keine Änderung, skip
-   - Unterschiedlich → Sync durchführen, neuen Hash speichern
-
-**Frontend-Anzeige:**
-Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
- In CAdvowareAkten: Spalte "Sync-Hash" zeigt den Hash-Wert
- In CAIKnowledge: Spalte "Sync-Hash" zeigt den Hash-Wert
- Tooltip: "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
-
 ### Aktivierungsstatus

 **Zweck:** Steuerung der Synchronisations-Aktivität für Akten und AI Knowledge Entries
@@ -893,6 +636,34 @@ Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
 - `paused` - Synchronisation temporär pausiert, kann wieder aktiviert werden
 - `deactivated` - Synchronisation dauerhaft deaktiviert

+### Blake3 Hash für Änderungserkennung
+
+**Zweck:** Dokumentänderungen zwischen Synchronisationen erkennen
+
+Das `blake3hash` Feld ist direkt am CDokumente Entity verfügbar und wird automatisch vom `CDokumente` Hook berechnet:
+
+```bash
+# Custom API gibt blake3hash mit zurück
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
+  -H "X-Api-Key: your-api-key"
+
+# Response enthält blake3hash für jedes Dokument:
+{
+  "list": [{
+    "documentId": "dok-123",
+    "documentName": "contract.pdf",
+    "blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
+    "syncstatus": "synced"
+  }]
+}
+```
+
+**Änderungserkennung:**
+1. Bei Sync: Speichere aktuellen `blake3hash` clientseitig oder in eigenem System
+2. Nächster Sync: Frage Custom API ab, vergleiche `blake3hash`
+3. Wenn unterschiedlich → Dokument geändert → Re-Sync nötig
+4. Update `syncstatus` via Custom API PUT Endpoint
+
 ### Globaler syncStatus

 **Zweck:** Übersicht über den Synchronisationszustand aller Dokumente einer Akte/eines AI Knowledge Entries
@@ -963,10 +734,10 @@ GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=aktivierungssta

 ### Junction-Spalten via REST API

-**✅ RICHTIG:** Nutze Junction-Entity-APIs
+**✅ RICHTIG:** Nutze Custom API Endpoints
 ```bash
-GET /api/v1/CAdvowareAktenCDokumente
-GET /api/v1/CAIKnowledgeCDokumente
+GET /api/v1/JunctionData/CAIKnowledge/{knowledgeId}/dokumentes
+# (Siehe Custom API Endpoints Sektion unten)
 ```

 **❌ FALSCH:** Standard Relationship-Endpoints geben additionalColumns NICHT zurück
@@ -974,6 +745,381 @@ GET /api/v1/CAIKnowledgeCDokumente
 GET /api/v1/CAdvowareAkten/{id}/dokumentes  # hnr/syncStatus NICHT in Response!
 ```

+---
+
+## 🚀 Custom API Endpoints für Junction Tables (Best Practice)
+
+**Problem:** Die Standard Junction-Entity-API hat folgende Einschränkungen:
+- ACL-Zugriffsprobleme (oft 403 Forbidden trotz korrekter Konfiguration)
+- Keine JOIN-Queries → Separater Call für Dokumentdetails nötig
+- Umständliche Filterung
+- Hooks können unerwünschte Seiteneffekte haben
+
+**Lösung:** Custom API Endpoint mit direkten SQL-Queries (seit EspoCRM 7.4+)
+
+### Implementation (Beispiel: CAIKnowledge Junction API)
+
+#### 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:**
+- Nach Änderungen: **Administration → Clear Cache** (erforderlich!)
+- Route-Parameter mit `:paramName` → verfügbar als `$request->getRouteParam('paramName')`
+- `actionClassName` mit vollständigem Namespace (doppelte Backslashes!)
+
+#### 2. Action Class: GET - Alle Dokumente mit Junction-Daten
+
+**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
+ * 
+ * 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();
+        
+        // Direct SQL query with JOIN - much more efficient!
+        $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
+        ]);
+    }
+}
+```
+
+**Wichtige Details:**
+- **Snake_case:** DB-Spaltennamen verwenden `snake_case` (z.B. `last_sync`, nicht `lastSync`)
+- **Dependency Injection:** Constructor Injection funktioniert automatisch
+- **PDO direkt:** `$this->entityManager->getPDO()` für rohe SQL-Queries
+- **Validierung:** Entity-Existenz prüfen für bessere Errors
+- **ResponseComposer::json():** Moderne Response-Methode
+
+#### 3. Action Class: PUT - Junction-Spalten aktualisieren
+
+**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 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 with only provided fields
+        $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. Provide: aiDocumentId, syncstatus, or 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);
+        
+        if ($sth->rowCount() === 0) {
+            throw new NotFound('Junction entry not found or no changes made');
+        }
+        
+        // Return updated data
+        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;
+    }
+}
+```
+
+**Highlights:**
+- **Dynamisches UPDATE:** Nur Felder updaten, die im Request Body übergeben wurden
+- **Validierung:** Enum-Werte prüfen bevor DB-Update
+- **NOW()-Trick:** `updateLastSync: true` → Automatischer Timestamp
+- **rowCount():** Prüfen ob wirklich ein Record betroffen war
+
+#### 4. Praktische API-Verwendung
+
+**GET: Alle Dokumente mit Junction-Daten abrufen**
+```bash
+curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
+  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4"
+```
+
+**Response:**
+```json
+{
+  "total": 2,
+  "list": [
+    {
+      "junctionId": 5,
+      "cAIKnowledgeId": "69b1b03582bb6e2da",
+      "cDokumenteId": "6974aba30cd69c723",
+      "aiDocumentId": "NEW-DOC-FROM-API",
+      "syncstatus": "new",
+      "lastSync": "2026-03-12 21:38:24",
+      "documentId": "6974aba30cd69c723",
+      "documentName": "2. dokuments",
+      "blake3hash": null,
+      "documentCreatedAt": "2026-01-24 11:23:15",
+      "documentModifiedAt": "2026-03-03 09:48:14"
+    },
+    {
+      "junctionId": 1,
+      "cAIKnowledgeId": "69b1b03582bb6e2da",
+      "cDokumenteId": "69a68b556a39771bf",
+      "aiDocumentId": "UPDATED-VIA-API-123",
+      "syncstatus": "synced",
+      "lastSync": "2026-03-12 21:37:44",
+      "documentId": "69a68b556a39771bf",
+      "documentName": "hollibolli",
+      "blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
+      "documentCreatedAt": "2026-03-03 07:18:45",
+      "documentModifiedAt": "2026-03-12 20:19:01"
+    }
+  ]
+}
+```
+
+**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-DOC-123",
+    "syncstatus": "synced",
+    "updateLastSync": true
+  }'
+```
+
+**Response:**
+```json
+{
+  "junctionId": 1,
+  "cAIKnowledgeId": "69b1b03582bb6e2da",
+  "cDokumenteId": "69a68b556a39771bf",
+  "aiDocumentId": "EXTERNAL-AI-DOC-123",
+  "syncstatus": "synced",
+  "lastSync": "2026-03-12 21:42:15"
+}
+```
+
+**POST: Neues Dokument verknüpfen + Junction-Daten setzen**
+```bash
+curl -X POST "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/6974aba30cd69c723" \
+  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "aiDocumentId": "NEW-EXTERNAL-DOC",
+    "syncstatus": "new",
+    "updateLastSync": true
+  }'
+```
+
+### Vorteile Custom API Endpoints
+
+✅ **Performance:** JOIN-Queries in einem Call statt mehrere API-Requests  
+✅ **Keine ACL-Probleme:** Direkter DB-Zugriff umgeht ACL-System  
+✅ **Volle Kontrolle:** Exakte Control über SQL und Response-Struktur  
+✅ **Hooks umgehen:** SQL-Updates lösen keine Entity-Hooks aus (wenn gewünscht)  
+✅ **Flexible Responses:** Kann mehrere Entities in einer Response joinen  
+✅ **Type Safety:** Moderne PHP 8+ mit Constructor Property Promotion  
+✅ **Wartbar:** Klare Trennung zwischen Routes, Actions und Business Logic
+
+### Best Practices
+
+1. **Immer validieren:** Entity-Existenz prüfen bevor DB-Operations
+2. **Snake_case beachten:** DB-Spaltennamen verwenden Unterstriche
+3. **Prepared Statements:** Immer PDO Prepared Statements für SQL-Injection-Schutz
+4. **Error Handling:** Spezifische Exceptions (BadRequest, NotFound, Forbidden)
+5. **Documentation:** PHPDoc für jede Action Class mit Endpoint-Beschreibung
+6. **Testing:** API-Endpoints mit Python/Bash testen vor Produktiveinsatz
+7. **Cache löschen:** Nach routes.json Änderungen IMMER Cache clearen!
+
+### Wann Custom API verwenden?
+
+**✅ Verwende Custom API wenn:**
+- Junction-Spalten häufig gelesen/geschrieben werden
+- JOINs über mehrere Tabellen nötig sind
+- Performance kritisch ist (viele Dokumente)
+- ACL-Probleme mit Standard Junction-Entity API
+- Spezielle Business Logic beim Read/Write nötig
+
+**❌ Verwende Standard API wenn:**
+- Einfache CRUD ohne Junction-Spalten
+- ACL-System explizit gewünscht
+- Hooks sollen ausgelöst werden
+- Wenig Datenvolumen
+
 ### Hooks & Automatische Updates

 Folgende Operationen lösen automatisch Hooks aus:
@@ -998,23 +1144,9 @@ PUT /api/v1/CAdvowareAkten/{id}
 ```
 - → `CheckGlobalSyncStatus`: Berechnet globalen Status aus Junction-Einträgen

-### ACL-Berechtigungen
-
-Für Junction-Entities müssen Rollen explizit Zugriff haben:
-
-```sql
-- Via Admin UI: Roles → [Your Role] → Add "CAdvowareAktenCDokumente"
-- Oder via SQL:
-UPDATE role 
-SET data = JSON_SET(data, '$.table.CAdvowareAktenCDokumente', 
-  JSON_OBJECT('create','yes','read','all','edit','all','delete','all')
-) 
-WHERE name = 'Your Role Name';
-```
-
 ---

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

 Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`