Update README.md: reorder table of contents and add section on common errors

2026-01-23 21:51:13 +01:00
parent 9f069d1fe2
commit a04d6547b6
1 changed files with 309 additions and 9 deletions
--- 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.