bsiggel/espocrm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
bsiggel
2026-01-23 21:51:13 +01:00
parent 9f069d1fe2
commit a04d6547b6
1 changed files with 309 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

318
README.md
View File

@@ -4,15 +4,16 @@ KI-basierte Bearbeitung von EspoCRM: Struktur und Funktionsweise
1. [Überblick](#überblick) 1. [Überblick](#überblick)
2. [Custom Directory Struktur](#custom-directory-struktur) 2. [Custom Directory Struktur](#custom-directory-struktur)
3. [Rebuild-Prozess](#rebuild-prozess) 3. [Rebuild-Prozess](#rebuild-prozess)
4. [Dateiformate und JSON-Strukturen](#dateiformate-und-json-strukturen) 4. [Häufige Fehler vermeiden](#häufige-fehler-vermeiden)
5. [Workflow-Verwaltung](#workflow-verwaltung) 5. [Dateiformate und JSON-Strukturen](#dateiformate-und-json-strukturen)
6. [Internationalisierung (i18n) und Tooltips](#internationalisierung-i18n-und-tooltips) 6. [Workflow-Verwaltung](#workflow-verwaltung)
7. [Formula-Scripts und Custom PHP-Erweiterungen](#formula-scripts-und-custom-php-erweiterungen) 7. [Internationalisierung (i18n) und Tooltips](#internationalisierung-i18n-und-tooltips)
8. [Panel-Labels und Übersetzungen](#panel-labels-und-übersetzungen) 8. [Formula-Scripts und Custom PHP-Erweiterungen](#formula-scripts-und-custom-php-erweiterungen)
9. [Custom JavaScript & CSS Integration](#custom-javascript--css-integration) 9. [Panel-Labels und Übersetzungen](#panel-labels-und-übersetzungen)
10. [Reports und Report-Panels](#reports-und-report-panels) 10. [Custom JavaScript & CSS Integration](#custom-javascript--css-integration)
11. [Portal-Freigabe-System](#portal-freigabe-system) 11. [Reports und Report-Panels](#reports-und-report-panels)
12. [Troubleshooting](#troubleshooting) 12. [Portal-Freigabe-System](#portal-freigabe-system)
13. [Troubleshooting](#troubleshooting)
## Überblick ## Überblick
@@ -117,6 +118,305 @@ sudo find client/custom/ -type f -exec chmod 664 {} \;
sudo find client/custom/ -type d -exec chmod 775 {} \; 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 ## 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. Alle Metadata-Dateien sind im JSON-Format. Die Strukturen sind hierarchisch: Objekte für Felder/Links, Arrays für Optionen/Listen.