From a04d6547b671083480ca6e2e89ae69c14326fcbe Mon Sep 17 00:00:00 2001 From: bsiggel Date: Fri, 23 Jan 2026 21:51:13 +0100 Subject: [PATCH] Update README.md: reorder table of contents and add section on common errors --- README.md | 318 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 309 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a6a3c6d8..443845fd 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,16 @@ KI-basierte Bearbeitung von EspoCRM: Struktur und Funktionsweise 1. [Überblick](#überblick) 2. [Custom Directory Struktur](#custom-directory-struktur) 3. [Rebuild-Prozess](#rebuild-prozess) -4. [Dateiformate und JSON-Strukturen](#dateiformate-und-json-strukturen) -5. [Workflow-Verwaltung](#workflow-verwaltung) -6. [Internationalisierung (i18n) und Tooltips](#internationalisierung-i18n-und-tooltips) -7. [Formula-Scripts und Custom PHP-Erweiterungen](#formula-scripts-und-custom-php-erweiterungen) -8. [Panel-Labels und Übersetzungen](#panel-labels-und-übersetzungen) -9. [Custom JavaScript & CSS Integration](#custom-javascript--css-integration) -10. [Reports und Report-Panels](#reports-und-report-panels) -11. [Portal-Freigabe-System](#portal-freigabe-system) -12. [Troubleshooting](#troubleshooting) +4. [Häufige Fehler vermeiden](#häufige-fehler-vermeiden) +5. [Dateiformate und JSON-Strukturen](#dateiformate-und-json-strukturen) +6. [Workflow-Verwaltung](#workflow-verwaltung) +7. [Internationalisierung (i18n) und Tooltips](#internationalisierung-i18n-und-tooltips) +8. [Formula-Scripts und Custom PHP-Erweiterungen](#formula-scripts-und-custom-php-erweiterungen) +9. [Panel-Labels und Übersetzungen](#panel-labels-und-übersetzungen) +10. [Custom JavaScript & CSS Integration](#custom-javascript--css-integration) +11. [Reports und Report-Panels](#reports-und-report-panels) +12. [Portal-Freigabe-System](#portal-freigabe-system) +13. [Troubleshooting](#troubleshooting) ## Überblick @@ -117,6 +118,305 @@ sudo find client/custom/ -type f -exec chmod 664 {} \; sudo find client/custom/ -type d -exec chmod 775 {} \; ``` +## Häufige Fehler vermeiden + +Basierend auf der Analyse von Git-Commits und praktischen Erfahrungen treten bestimmte Fehler besonders häufig auf. Diese Sektion hilft, die **5 häufigsten Fehler** zu vermeiden. + +### ⚠️ Top 5 Fehlerquellen + +#### 1. Formula-Scripts falsch platziert + +**Problem:** Formula-Scripts werden in `entityDefs/{Entity}.json` statt in separater `formula/{Entity}.json` abgelegt. + +**Symptome:** +- beforeSaveApiScript wird nicht ausgeführt +- Validierungen greifen nicht +- Keine Fehler in Logs, Script wird einfach ignoriert + +**❌ FALSCH:** +```json +// custom/Espo/Custom/Resources/metadata/entityDefs/CBankverbindungen.json +{ + "fields": { + "iban": {"type": "varchar"} + }, + "formula": { + "beforeSaveApiScript": "..." // ← Funktioniert NICHT! + } +} +``` + +**✅ RICHTIG:** +```json +// custom/Espo/Custom/Resources/metadata/formula/CBankverbindungen.json +{ + "beforeSaveApiScript": "if (iban != null && iban != '') { ... }" +} +``` + +**Zusätzliche Fallstricke:** +- ❌ `string\isEmpty()` verwenden (existiert nicht!) +- ✅ Stattdessen: `field != null && field != ''` + +**Nach Korrektur:** `./custom/scripts/check_and_rebuild.sh` ausführen + +--- + +#### 2. Layout-Strukturfehler + +**Problem:** Unnötige oder falsche Array-Elemente in Layouts, die zu UI-Problemen führen. + +**Symptome:** +- Felder werden nicht korrekt angeordnet +- Leere Bereiche in Detail-Views +- Inkonsistente Spaltenbreiten + +**❌ FALSCH:** +```json +// layouts/Entity/detail.json +{ + "rows": [ + [ + {"name": "field1"} + ], + [ + {"name": "field2"}, + false // ← Unnötiges false-Element! + ] + ] +} +``` + +**✅ RICHTIG:** +```json +{ + "rows": [ + [ + {"name": "field1"}, + {"name": "field2"} // Beide in einer Row + ] + ] +} +``` + +**Häufige Layout-Fehler:** +- ❌ Width-Attribute in Detail-Layouts (nur für List-Layouts!) +- ❌ Leere Objekte `{}` oder `false` in Rows +- ❌ Index nicht angepasst nach Entfernung von Panels (bottomPanelsDetail) + +**Best Practice:** +- Width nur in `list.json` und `listSmall.json` verwenden +- Rows immer vollständig füllen oder Felder kombinieren +- Nach Panel-Entfernung Indices neu nummerieren + +--- + +#### 3. Unvollständige Relationship-Definitionen + +**Problem:** Bei hasMany-Relationships wird nur eine Seite definiert, die Gegenseite fehlt. + +**Symptome:** +- HTTP 404 "Link does not exist"-Fehler in Logs +- Relationship-Panel zeigt keine Daten +- Verknüpfungen können nicht erstellt werden + +**❌ FALSCH - Nur eine Seite definiert:** +```json +// entityDefs/CMietobjekt.json +{ + "links": { + "kontakte": { + "type": "hasMany", + "entity": "Contact", + "foreign": "mietobjekte" // ← Existiert nicht in Contact! + } + } +} + +// entityDefs/Contact.json - FEHLT! +``` + +**✅ RICHTIG - Beide Seiten definiert:** +```json +// entityDefs/CMietobjekt.json +{ + "links": { + "contactsMietobjekt": { + "type": "hasMany", + "relationName": "cMietobjektContactPortal", + "foreign": "cMietobjektContactPortal", + "entity": "Contact" + } + } +} + +// entityDefs/Contact.json +{ + "links": { + "cMietobjektContactPortal": { + "type": "hasMany", + "relationName": "cMietobjektContactPortal", // ← IDENTISCH! + "foreign": "contactsMietobjekt", // ← Zeigt auf Gegenseite + "entity": "CMietobjekt" + } + } +} +``` + +**Kritische Punkte:** +- ✅ `relationName` muss auf **beiden Seiten identisch** sein +- ✅ `foreign` zeigt auf den Link-Namen der **Gegenseite** +- ✅ Beide entityDefs-Dateien müssen erstellt werden + +**Siehe auch:** Abschnitt "Troubleshooting → Link does not exist" + +--- + +#### 4. i18n/Localization-Fehler + +**Problem:** Labels nicht vollständig oder nur in einer Sprache definiert. + +**Symptome:** +- Relationship-Panels zeigen technische Namen statt Labels +- Tooltips zeigen nur Feldnamen +- In manchen Sprachen fehlen Beschriftungen + +**❌ FALSCH - Unvollständig:** +```json +// i18n/de_DE/Entity.json +{ + "fields": { + "mietobjekte": "Mietobjekte" + }, + "links": {} // ← Label fehlt! +} + +// i18n/en_US/Entity.json - FEHLT KOMPLETT! +``` + +**✅ RICHTIG - Vollständig in beiden Sprachen:** +```json +// i18n/de_DE/Entity.json +{ + "fields": { + "mietobjekte": "Mietobjekte" + }, + "links": { + "mietobjekte": "Mietobjekte" // ← BEIDE Sektionen! + }, + "tooltips": { + "mietobjekte": "Verknüpfte Mietobjekte" + } +} + +// i18n/en_US/Entity.json ← IMMER erstellen! +{ + "fields": { + "mietobjekte": "Rental Properties" + }, + "links": { + "mietobjekte": "Rental Properties" + }, + "tooltips": { + "mietobjekte": "Linked rental properties" + } +} +``` + +**Kritische Regeln:** +- ✅ Labels IMMER in `fields` UND `links` definieren +- ✅ en_US ist Fallback-Sprache → MUSS vollständig sein +- ✅ Tooltips in ALLEN Sprachen konsistent definieren +- ✅ Bei neuen Relationships beide Sprachen aktualisieren + +**Warum en_US kritisch ist:** +EspoCRM nutzt en_US als Fallback. Fehlt eine Definition dort, überschreibt sie möglicherweise die deutschen Labels! + +**Siehe auch:** Abschnitt "Internationalisierung (i18n) und Tooltips" + +--- + +#### 5. Dateirechte-Probleme + +**Problem:** Custom-Dateien gehören `root` statt `www-data`, EspoCRM kann nicht darauf zugreifen. + +**Symptome:** +- "Permission denied"-Fehler in Logs +- Layouts können nicht über Admin-UI bearbeitet werden +- HTTP 500-Fehler beim Speichern + +**Ursache:** +Dateien werden als Root-User erstellt (z.B. via sudo, Git-Checkout) und EspoCRM läuft als `www-data`. + +**✅ Lösung:** +Das `check_and_rebuild.sh` Script prüft und korrigiert automatisch: + +```bash +./custom/scripts/check_and_rebuild.sh +``` + +**Manuelle Korrektur (falls nötig):** +```bash +sudo chown -R www-data:www-data custom/ client/custom/ data/ +sudo find custom/ -type f -name "*.json" -exec chmod 664 {} \; +sudo find custom/ -type d -exec chmod 775 {} \; +``` + +**Prävention:** +- Änderungen direkt im Docker-Container vornehmen +- Nach Git-Pull immer `check_and_rebuild.sh` ausführen +- VSCode mit Remote-Development nutzt automatisch korrekte User + +--- + +### 🛡️ Fehler-Prävention: Checkliste + +**Bei neuer Entity-Erstellung:** +- [ ] entityDefs in **beiden** Entities (bei Relationships) +- [ ] `relationName` identisch auf beiden Seiten +- [ ] `foreign` zeigt auf korrekten Link-Namen +- [ ] i18n in **de_DE UND en_US** vollständig +- [ ] Labels in **fields UND links** +- [ ] Formula in `formula/`, **NICHT** in `entityDefs/` +- [ ] Nach Erstellung: `./custom/scripts/check_and_rebuild.sh` + +**Bei Layout-Änderungen:** +- [ ] Keine `false` oder leere Objekte in Rows +- [ ] Width nur in List-Layouts verwenden +- [ ] Indices nach Panel-Entfernung neu nummerieren +- [ ] Nach Änderung: `./custom/scripts/check_and_rebuild.sh` + +**Bei Formula-Scripts:** +- [ ] Separate Datei `formula/{Entity}.json` erstellen +- [ ] `string\isEmpty()` NICHT verwenden → `!= null && != ''` +- [ ] Null-Checks vor String-Operationen +- [ ] Nach Erstellung: `./custom/scripts/check_and_rebuild.sh` + +**Allgemein:** +- [ ] Immer `./custom/scripts/check_and_rebuild.sh` nach Änderungen +- [ ] Browser Hard Refresh (Ctrl+Shift+R) bei Frontend-Änderungen +- [ ] Logs prüfen: `tail -n 100 data/logs/espo-$(date +%Y-%m-%d).log` + +--- + +### 📊 Warum diese Fehler so häufig sind + +**Root Cause:** +1. **EspoCRM Admin-UI** generiert teilweise unvollständige JSON-Definitionen +2. **Bidirektionale Relationships** sind komplex und nicht intuitiv +3. **en_US als Fallback** ist nicht offensichtlich dokumentiert +4. **Formula-Platzierung** wird im Admin-UI falsch vorgeschlagen +5. **Layout-Generierung** erzeugt manchmal ungültige Array-Strukturen + +**Lösung:** +- Diese Dokumentation **VOR** der Entwicklung lesen +- `check_and_rebuild.sh` Script konsequent nutzen +- Bei Unsicherheit: Troubleshooting-Abschnitt konsultieren + +**Siehe auch:** +- [Troubleshooting](#troubleshooting) - Ausführliche Fehlerdiagnose +- [Custom Directory Struktur](/custom/CUSTOM_DIRECTORY.md) - Vollständige Dateiübersicht + ## Dateiformate und JSON-Strukturen Alle Metadata-Dateien sind im JSON-Format. Die Strukturen sind hierarchisch: Objekte für Felder/Links, Arrays für Optionen/Listen.