From 54d66da52d459120302774bf9309021c15000060 Mon Sep 17 00:00:00 2001 From: bsiggel Date: Wed, 11 Mar 2026 21:53:35 +0100 Subject: [PATCH] Add 'syncedHash' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps --- .../Resources/i18n/de_DE/CAIKnowledge.json | 3 +- .../i18n/de_DE/CAIKnowledgeCDokumente.json | 6 +- .../Resources/i18n/de_DE/CAdvowareAkten.json | 3 +- .../i18n/de_DE/CAdvowareAktenCDokumente.json | 4 +- .../Resources/i18n/en_US/CAIKnowledge.json | 3 +- .../i18n/en_US/CAIKnowledgeCDokumente.json | 6 +- .../Resources/i18n/en_US/CAdvowareAkten.json | 3 +- .../i18n/en_US/CAdvowareAktenCDokumente.json | 4 +- .../metadata/entityDefs/CAIKnowledge.json | 8 +- .../entityDefs/CAIKnowledgeCDokumente.json | 6 ++ .../metadata/entityDefs/CAdvowareAkten.json | 8 +- .../entityDefs/CAdvowareAktenCDokumente.json | 6 ++ custom/docs/API_ENDPOINTS.md | 76 ++++++++++++++++--- data/config.php | 2 +- data/state.php | 4 +- 15 files changed, 117 insertions(+), 25 deletions(-) diff --git a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json index 77a34211..aad8d87d 100644 --- a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json +++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledge.json @@ -12,7 +12,8 @@ "aktivierungsstatus": "Aktivierungsstatus", "dokumenteAiDocumentId": "AI Document ID", "dokumenteSyncstatus": "Sync-Status", - "dokumenteLastSync": "Letzter Sync" + "dokumenteLastSync": "Letzter Sync", + "dokumenteSyncedHash": "Sync-Hash" }, "links": { "dokumentes": "Dokumente", diff --git a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json index c06e5aae..2a8fb06f 100644 --- a/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json +++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAIKnowledgeCDokumente.json @@ -10,7 +10,8 @@ "cDokumenteId": "Dokument ID", "aiDocumentId": "AI Dokument-ID", "syncstatus": "Sync-Status", - "lastSync": "Letzte Synchronisation" + "lastSync": "Letzte Synchronisation", + "syncedHash": "Sync-Hash" }, "options": { "syncstatus": { @@ -24,6 +25,7 @@ "tooltips": { "aiDocumentId": "Externe AI-Dokument-Referenz-ID", "syncstatus": "Status der Synchronisation mit externem AI-System", - "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation" + "lastSync": "Zeitpunkt der letzten erfolgreichen Synchronisation", + "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)" } } diff --git a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json index a577a027..27616823 100644 --- a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json +++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAkten.json @@ -21,7 +21,8 @@ "dokumentes": "Dokumente", "dokumenteHnr": "HNR", "dokumenteSyncstatus": "Sync-Status", - "dokumenteLastSync": "Letzter Sync" + "dokumenteLastSync": "Letzter Sync", + "dokumenteSyncedHash": "Sync-Hash" }, "options": { "syncStatus": { diff --git a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json index f3144aad..37510060 100644 --- a/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json +++ b/custom/Espo/Custom/Resources/i18n/de_DE/CAdvowareAktenCDokumente.json @@ -10,6 +10,7 @@ "cDokumenteId": "Dokument ID", "hnr": "HNR", "syncStatus": "Sync-Status", + "syncedHash": "Sync-Hash", "deleted": "Gelöscht" }, "links": { @@ -26,6 +27,7 @@ }, "tooltips": { "hnr": "Advoware HNR Referenz für dieses Dokument", - "syncStatus": "Synchronisierungsstatus mit Advoware" + "syncStatus": "Synchronisierungsstatus mit Advoware", + "syncedHash": "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)" } } diff --git a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json index ce7ba3db..84e71b1c 100644 --- a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json +++ b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledge.json @@ -9,7 +9,8 @@ "aktivierungsstatus": "Activation Status", "dokumenteAiDocumentId": "AI Document ID", "dokumenteSyncstatus": "Sync Status", - "dokumenteLastSync": "Last Sync" + "dokumenteLastSync": "Last Sync", + "dokumenteSyncedHash": "Sync Hash" }, "links": { "dokumentes": "Dokumente", diff --git a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json index 273ae52b..282d56be 100644 --- a/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json +++ b/custom/Espo/Custom/Resources/i18n/en_US/CAIKnowledgeCDokumente.json @@ -10,7 +10,8 @@ "cDokumenteId": "Document ID", "aiDocumentId": "AI Document ID", "syncstatus": "Sync Status", - "lastSync": "Last Sync" + "lastSync": "Last Synchronization", + "syncedHash": "Sync Hash" }, "options": { "syncstatus": { @@ -24,6 +25,7 @@ "tooltips": { "aiDocumentId": "External AI document reference ID", "syncstatus": "Synchronization status with external AI system", - "lastSync": "Timestamp of last successful synchronization" + "lastSync": "Timestamp of the last successful synchronization", + "syncedHash": "Hash value of the last synchronized document state (for change detection)" } } diff --git a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json index 0bc96498..26ce0d29 100644 --- a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json +++ b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAkten.json @@ -11,7 +11,8 @@ "dokumentes": "Dokumente", "dokumenteHnr": "HNR", "dokumenteSyncstatus": "Sync Status", - "dokumenteLastSync": "Last Sync" + "dokumenteLastSync": "Last Sync", + "dokumenteSyncedHash": "Sync Hash" }, "links": { "meetings": "Meetings", diff --git a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json index 6a7a8d77..6e41623f 100644 --- a/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json +++ b/custom/Espo/Custom/Resources/i18n/en_US/CAdvowareAktenCDokumente.json @@ -10,6 +10,7 @@ "cDokumenteId": "Document ID", "hnr": "HNR", "syncStatus": "Sync Status", + "syncedHash": "Sync Hash", "deleted": "Deleted" }, "links": { @@ -26,6 +27,7 @@ }, "tooltips": { "hnr": "Advoware HNR reference for this document", - "syncStatus": "Synchronization status with Advoware" + "syncStatus": "Synchronization status with Advoware", + "syncedHash": "Hash value of the last synchronized document state (for change detection)" } } diff --git a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json index 5dd8a9dd..2788e70e 100644 --- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json +++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledge.json @@ -104,6 +104,11 @@ "notStorable": true, "utility": true }, + "dokumenteSyncedHash": { + "type": "varchar", + "notStorable": true, + "utility": true + }, "dokumentes": { "type": "linkMultiple", "layoutDetailDisabled": false, @@ -116,7 +121,8 @@ "columns": { "aiDocumentId": "aiKnowledgeAiDocumentId", "syncstatus": "aiKnowledgeSyncstatus", - "lastSync": "aiKnowledgeLastSync" + "lastSync": "aiKnowledgeLastSync", + "syncedHash": "aiKnowledgeSyncedHash" }, "additionalAttributeList": [ "columns" diff --git a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json index bcced0fe..8041bb02 100644 --- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json +++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAIKnowledgeCDokumente.json @@ -54,6 +54,12 @@ "isCustom": true, "tooltip": true }, + "syncedHash": { + "type": "varchar", + "len": 64, + "isCustom": true, + "tooltip": true + }, "deleted": { "type": "bool", "default": false diff --git a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json index abc90148..ea0d3de1 100644 --- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json +++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAkten.json @@ -119,6 +119,11 @@ "notStorable": true, "utility": true }, + "dokumenteSyncedHash": { + "type": "varchar", + "notStorable": true, + "utility": true + }, "dokumentes": { "type": "linkMultiple", "layoutDetailDisabled": false, @@ -131,7 +136,8 @@ "columns": { "hnr": "advowareAktenHnr", "syncstatus": "advowareAktenSyncstatus", - "lastSync": "advowareAktenLastSync" + "lastSync": "advowareAktenLastSync", + "syncedHash": "advowareAktenSyncedHash" }, "additionalAttributeList": [ "columns" diff --git a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json index 9973ed2b..5530e613 100644 --- a/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json +++ b/custom/Espo/Custom/Resources/metadata/entityDefs/CAdvowareAktenCDokumente.json @@ -46,6 +46,12 @@ "isCustom": true, "tooltip": true }, + "syncedHash": { + "type": "varchar", + "len": 64, + "isCustom": true, + "tooltip": true + }, "deleted": { "type": "bool", "default": false diff --git a/custom/docs/API_ENDPOINTS.md b/custom/docs/API_ENDPOINTS.md index d65c67f9..271ce538 100644 --- a/custom/docs/API_ENDPOINTS.md +++ b/custom/docs/API_ENDPOINTS.md @@ -1,10 +1,11 @@ # REST API Endpunkte - EspoCRM Custom Entities -**Version:** 1.1 +**Version:** 1.2 **Datum:** 11. März 2026 **Base URL:** `https://your-crm.com/api/v1` **Changelog:** +- 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 @@ -386,6 +387,7 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&wh - `cDokumenteId` - ID des Dokuments - `hnr` - Advoware HNR-Referenz (varchar, 255) - `syncStatus` - Sync-Status (enum: new, changed, synced, deleted) +- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64) - `deleted` - Soft-Delete Flag #### Alle Junction-Einträge @@ -404,6 +406,7 @@ GET /api/v1/CAdvowareAktenCDokumente "cDokumenteId": "dok-456", "hnr": "42", "syncStatus": "synced", + "syncedHash": "a3f5c8b9e2d1...", "deleted": false }, { @@ -412,6 +415,7 @@ GET /api/v1/CAdvowareAktenCDokumente "cDokumenteId": "dok-789", "hnr": "43", "syncStatus": "new", + "syncedHash": null, "deleted": false } ] @@ -438,7 +442,8 @@ GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=c "cAdvowareAktenId": "akte-123", "cDokumenteId": "dok-456", "hnr": "42", - "syncStatus": "synced" + "syncStatus": "synced", + "syncedHash": "a3f5c8b9e2d1..." } ] } @@ -463,7 +468,8 @@ Content-Type: application/json "cAdvowareAktenId": "akte-123", "cDokumenteId": "dok-999", "hnr": "50", - "syncStatus": "new" + "syncStatus": "new", + "syncedHash": null } ``` @@ -481,6 +487,7 @@ Content-Type: application/json { "syncStatus": "synced", + "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4", "hnr": "51" } ``` @@ -502,6 +509,7 @@ DELETE /api/v1/CAdvowareAktenCDokumente/{id} - `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255) - `syncstatus` - Sync-Status (enum: new, unclean, synced, failed, unsupported) - `lastSync` - Zeitpunkt der letzten Synchronisation (datetime) +- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64) - `deleted` - Soft-Delete Flag #### Alle Junction-Einträge @@ -521,6 +529,7 @@ GET /api/v1/CAIKnowledgeCDokumente "aiDocumentId": "ai-doc-external-789", "syncstatus": "synced", "lastSync": "2026-03-11 19:00:00", + "syncedHash": "b4e2a9c7f3d8...", "deleted": false } ] @@ -551,7 +560,8 @@ Content-Type: application/json "cAIKnowledgeId": "kb-123", "cDokumenteId": "dok-999", "aiDocumentId": "ai-doc-new-123", - "syncstatus": "new" + "syncstatus": "new", + "syncedHash": null } ``` @@ -562,7 +572,8 @@ Content-Type: application/json { "syncstatus": "synced", - "lastSync": "2026-03-11T20:30:00+00:00" + "lastSync": "2026-03-11T20:30:00+00:00", + "syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3" } ``` @@ -693,7 +704,7 @@ curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \ -H "X-Api-Key: your-api-key" # Schritt 2: Hole Junction-Einträge mit HNR -curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus" \ +curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus,syncedHash" \ -H "X-Api-Key: your-api-key" ``` @@ -708,7 +719,8 @@ curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \ "cAdvowareAktenId": "akte-123", "cDokumenteId": "dok-789", "hnr": "42", - "syncStatus": "new" + "syncStatus": "new", + "syncedHash": null }' ``` @@ -724,7 +736,8 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_I -H "X-Api-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ - "syncStatus": "synced" + "syncStatus": "synced", + "syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4" }' # Schritt 3: Update global status (optional, Hooks machen das automatisch) @@ -752,7 +765,7 @@ curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type ```bash # Finde alle Junction-Einträge die "new" oder "changed" sind -curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus" \ +curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus,syncedHash" \ -H "X-Api-Key: your-api-key" ``` @@ -780,6 +793,49 @@ 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 @@ -868,6 +924,6 @@ WHERE name = 'Your Role Name'; --- **Letzte Aktualisierung:** 11. März 2026 -**Version:** 1.1 +**Version:** 1.2 Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md` diff --git a/data/config.php b/data/config.php index 3ec557cb..964bcf06 100644 --- a/data/config.php +++ b/data/config.php @@ -360,7 +360,7 @@ return [ 0 => 'youtube.com', 1 => 'google.com' ], - 'microtime' => 1773260767.92155, + 'microtime' => 1773262342.780449, 'siteUrl' => 'https://crm.bitbylaw.com', 'fullTextSearchMinLength' => 4, 'webSocketUrl' => 'ws://api.bitbylaw.com:5000/espocrm/ws', diff --git a/data/state.php b/data/state.php index 83862fab..a2a65502 100644 --- a/data/state.php +++ b/data/state.php @@ -1,7 +1,7 @@ 1773260768, - 'microtimeState' => 1773260768.04608, + 'cacheTimestamp' => 1773262342, + 'microtimeState' => 1773262342.914738, 'currencyRates' => [ 'EUR' => 1.0 ],