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

Update documentation for EspoCRM Best Practices and Validator Tool

Browse Source
This commit is contained in:
bsiggel
2026-03-10 12:46:14 +01:00
parent 9b18a63acf
commit c2766ec66a
2 changed files with 616 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

461
custom/docs/tools/VALIDATOR_README.md
View File

@@ -1,12 +1,69 @@
# EspoCRM Validator & Rebuild Tool
# EspoCRM Validator & Rebuild Tool v2.0
**Letzte Aktualisierung:** 10. März 2026
**Tool:** `custom/scripts/validate_and_rebuild.py`
## Übersicht
Das neue Python-basierte Validierungs-Tool `validate_and_rebuild.py` ersetzt das bisherige Bash-Script und bietet erweiterte Prüfungen für EspoCRM Custom-Entities.
Erweiterte Python-Tool zur Validierung von EspoCRM Custom-Entities mit intelligenter Log-Prüfung und CRUD-Tests. Version 2.0 bietet minimalen/verbose Output, Live-Entity-Tests und KI-freundliches Feedback.
## Features
## 🆕 Neue Features in v2.0
### ✅ Automatische Validierungen
### 1. Intelligenter Output-Modus
- **Standard-Modus:** Minimale Ausgabe, nur Ergebnisse
- **Verbose-Modus (`-v`):** Detaillierte Informationen mit Timing
### 2. Log-Prüfung mit präzisen Zeitstempeln
- Prüft Logs nach **jedem** API-Request
- Nur Logs seit Request-Start
- Test bricht ab bei Fehler in Logs
- Filtert bekannte unwichtige Meldungen
### 3. CRUD-Tests für alle Entities
- CREATE, READ, UPDATE, LIST, DELETE
- Log-Check nach jeder Operation
- Automatisches Cleanup
- Detektiert fehlende Service-Klassen
### 4. KI-freundliches JSON-Feedback
- Strukturierte Fehleranalyse
- Konkrete Empfehlungen
- Maschinenlesbar
## Verwendung
### Basis-Befehle
```bash
# Standard: Minimaler Output, vollständige Tests
python3 custom/scripts/validate_and_rebuild.py
# Verbose: Detaillierte Ausgabe für Debugging
python3 custom/scripts/validate_and_rebuild.py -v
# Nur Validierung (kein Rebuild)
python3 custom/scripts/validate_and_rebuild.py --dry-run
# Ohne Entity-Tests (schneller)
python3 custom/scripts/validate_and_rebuild.py --skip-tests
```
### Erweiterte Parameter
```bash
# Custom Base-URL
python3 custom/scripts/validate_and_rebuild.py --base-url http://my-espo.local
# Custom Credentials
python3 custom/scripts/validate_and_rebuild.py --username admin --password secret
# Kombination
python3 custom/scripts/validate_and_rebuild.py -v --skip-tests --dry-run
```
## Validierungsphasen
### Phase 1: Statische Validierung
1. **JSON-Syntax-Prüfung**
- Validiert alle `.json` Dateien im `custom/` Verzeichnis
@@ -15,182 +72,310 @@ Das neue Python-basierte Validierungs-Tool `validate_and_rebuild.py` ersetzt das
2. **Relationship-Konsistenz**
- Prüft bidirektionale Relationships (hasMany/hasOne)
- Validiert `foreign`-Links zwischen Entities
- Überprüft `relationName`-Konsistenz
- Überprüft `relationName`-Konsistenz bei M2M
- Erkennt fehlende Gegenseiten-Definitionen
3. **Formula-Script Platzierung**
- Prüft ob Formula-Scripts in `/formula/` statt `/entityDefs/` liegen
- Warnt vor leeren Formula-Definitionen
3. **Erforderliche Dateien**
- Prüft Vorhandensein von scopes-Dateien
- Validiert i18n-Dateien (de_DE + en_US)
- Warnt bei fehlenden Translations
4. **i18n-Vollständigkeit**
- Findet fehlende Übersetzungen (de_DE / en_US)
- Prüft Link-Labels für alle Custom-Relationships
- Warnt bei komplett fehlenden i18n-Dateien
4. **Dateirechte**
- Prüft Owner (www-data:www-data) in:
- `custom/Espo/Custom/Resources/`
- `client/custom/`
- `data/` (inkl. config.php)
- Korrigiert automatisch (664/775)
5. **Layout-Struktur**
- Validiert clientDefs und bottomPanels
- Findet unnötige `false`-Elemente
5. **PHP-Syntax-Validierung**
- Validiert alle Custom-PHP-Klassen
- Nutzt `php -l` für Syntax-Check
6. **Dateirechte** (✨ ERWEITERT)
- Prüft Owner (www-data:www-data) in DREI Bereichen:
- `custom/Espo/Custom/Resources/` - Custom Metadata
- `client/custom/` - Frontend JavaScript & CSS
- `data/` - **INKL. config.php & config-internal.php**
- Korrigiert Permissions automatisch (664 für Dateien, 775 für Verzeichnisse)
- **Hebt kritische System-Dateien hervor** (config.php, config-internal.php)
### Phase 2: Rebuild mit Log-Prüfung
7. **CSS-Validierung**
- Validiert Syntax aller CSS-Dateien
- Prüft Klammer-Balance und grundlegende Struktur
6. **Cache-Clearing**
- Löscht EspoCRM-Cache vor Rebuild
8. **JavaScript-Validierung**
- Prüft Syntax aller JS-Dateien in `client/custom/src/`
7. **EspoCRM Rebuild**
- Führt `php command.php rebuild` aus
- **Prüft Logs direkt nach Rebuild**
- Bricht ab bei Fehlern in Logs
9. **PHP-Validierung**
- Validiert PHP-Syntax aller Custom-Klassen
### Phase 3: Live Entity-Tests (optional)
10. **Rebuild-Ausführung**
- Führt `rebuild.php` nur aus, wenn keine kritischen Fehler vorliegen
Für jede Custom Entity (außer Junction Tables):
## Verwendung
8. **CREATE Test**
- Erstellt Test-Record via API
- Prüft Logs nach Request
- Validiert Response
### Direkt ausführen
```bash
cd /path/to/espocrm
python3 custom/scripts/validate_and_rebuild.py
9. **READ Test**
- Liest erstellten Record
- Prüft Logs
- Validiert Daten
10. **UPDATE Test**
- Aktualisiert Record
- Prüft Logs
- Validiert Änderung
11. **LIST Test**
- Ruft Entity-Liste ab
- Prüft Logs
- Validiert Response
12. **DELETE Test**
- Löscht Test-Record
- Prüft Logs
- Entfernt aus Cleanup-Liste
13. **Automatisches Cleanup**
- Löscht alle verbliebenen Test-Records
## Output-Beispiele
### Standard-Modus (Minimal)
```
EspoCRM Validator & Rebuild Tool v2.0
1. JSON-SYNTAX VALIDIERUNG
✓ Alle 746 JSON-Dateien valide
2. RELATIONSHIP-KONSISTENZ
✓ 51 Relationships geprüft
3. ERFORDERLICHE DATEIEN
✗ 1 fehlende Dateien
CVMHBeteiligte: scopes/CVMHBeteiligte.json fehlt
4. DATEIRECHTE-PRÜFUNG
✓ Alle Dateirechte korrekt (www-data:www-data)
5. PHP-SYNTAX VALIDIERUNG
✓ Alle 353 PHP-Dateien valide
6. ESPOCRM REBUILD
✓ Rebuild erfolgreich abgeschlossen
7. ENTITY CRUD-TESTS
Ergebnis: 18 erfolgreich, 0 fehlgeschlagen
✓ Alle 18 Entities getestet
ZUSAMMENFASSUNG
WARNUNGEN: 1
⚠ CVMHBeteiligte: scopes/CVMHBeteiligte.json fehlt
✓ ERFOLGREICH ABGESCHLOSSEN
```
### Verbose-Modus (`-v`)
```
EspoCRM Validator & Rebuild Tool v2.0
Verbose-Modus aktiviert
================================================================================
1. JSON-SYNTAX VALIDIERUNG
================================================================================
ℹ Prüfe 746 JSON-Dateien...
✓ Alle 746 JSON-Dateien valide
================================================================================
6. ESPOCRM REBUILD
================================================================================
ℹ Container: espocrm
ℹ Lösche Cache...
ℹ Starte Rebuild...
✓ Rebuild erfolgreich abgeschlossen
================================================================================
7. ENTITY CRUD-TESTS
================================================================================
ℹ Teste 18 Custom-Entities...
▶ CAICollection: Create... ✓ 0.042s
ID: 69b00123456789abc
▶ CAICollection: Read... ✓ 0.028s
Name: Test CAICollection 1710065432
▶ CAICollection: Update... ✓ 0.035s
▶ CAICollection: List... ✓ 0.031s
12 Einträge
▶ CAICollection: Delete... ✓ 0.029s
[... weitere Entities ...]
ℹ Ergebnis: 18 erfolgreich, 0 fehlgeschlagen
✓ Alle 18 Entities getestet
```
### Bei Fehlern (mit Log-Analyse)
```
7. ENTITY CRUD-TESTS
▶ CAICollection: Create... ✗ 0.018s
Logs enthalten Fehler!
✗ Log-Fehler bei CREATE:
[2026-03-10 12:34:56] CRITICAL: InjectableFactory: Class 'Espo\Custom\Services\CAICollection' does not exist.
:: GET /CAICollection :: /var/www/html/application/Espo/Core/InjectableFactory.php(164)
ZUSAMMENFASSUNG
KI-FEEDBACK:
{
"status": "failed",
"summary": {
"errors": 1,
"warnings": 0,
"entities_checked": 28
},
"errors": ["InjectableFactory: Class 'Espo\\Custom\\Services\\CAICollection' does not exist"],
"recommendations": [
"KRITISCH: Service-Klassen fehlen! Erstelle Services in custom/Espo/Custom/Services/"
]
}
⚠ TESTS FEHLGESCHLAGEN
```
## Exit Codes
- `0` - Erfolg: Alle Validierungen bestanden, Rebuild erfolgreich
- `1` - Fehler: Kritische Fehler gefunden oder Rebuild fehlgeschlagen
## Output-Format
Das Script verwendet farbcodierte Ausgaben:
- 🟢 **Grün (✓)**: Erfolgreich / OK
- 🟡 **Gelb (⚠)**: Warnungen (nicht kritisch)
- 🔴 **Rot (✗)**: Fehler (kritisch, Rebuild wird abgebrochen)
- 🔵 **Blau (ℹ)**: Informationen
- `1` - Fehler: Kritische Fehler gefunden oder Rebuild/Tests fehlgeschlagen
## Fehlertypen
### Kritische Fehler (Rebuild-Abbruch)
- JSON-Syntax-Fehler
- PHP-Syntax-Fehler
- Fehlende Relationship-Definitionen
- Falsch platzierte Formula-Scripts
- Rebuild-Fehler
- **Log-Fehler nach Rebuild**
### Warnungen (kein Abbruch)
- Fehlende i18n-Übersetzungen
- Layout-Strukturprobleme
- Dateirechte-Probleme
- Fehlende scopes-Dateien
- Dateirechte-Probleme (werden auto-korrigiert)
## Beispiel-Output
### Test-Fehler (kein Abbruch bei --skip-tests)
- Entity-Tests schlagen fehl
- API-Authentifizierung fehlgeschlagen
- Service-Klassen fehlen (wird erkannt!)
## Häufige Fehler und Lösungen
### 1. InjectableFactory: Service-Klasse fehlt
**Symptom:**
```
EspoCRM Custom Entity Validator & Rebuild Tool
Arbeitsverzeichnis: /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
======================================================================
1. JSON-SYNTAX VALIDIERUNG
======================================================================
✓ Alle 547 JSON-Dateien sind syntaktisch korrekt
======================================================================
2. RELATIONSHIP-KONSISTENZ
======================================================================
✗ 4 Relationship-Fehler gefunden:
• Contact.cBankverbindungenContact: Ziel-Entity 'CBankverbindung' existiert nicht
• CMietobjekt.vmhRumungsklages → CVmhRumungsklage: Foreign link 'mietobjekte' fehlt
======================================================================
ZUSAMMENFASSUNG
======================================================================
FEHLER: 4
✗ Contact.cBankverbindungenContact: Ziel-Entity 'CBankverbindung' existiert nicht
...
REBUILD ABGEBROCHEN: Kritische Fehler müssen behoben werden!
CRITICAL: InjectableFactory: Class 'Espo\Custom\Services\{Entity}' does not exist
```
## Erweiterung
Das Script ist modular aufgebaut. Neue Validierungen können einfach hinzugefügt werden:
```python
def validate_custom_check(self) -> bool:
"""Eigene Validierung."""
print_header("X. CUSTOM CHECK")
# Prüflogik hier
if error_found:
self.errors.append("Fehlerbeschreibung")
return False
print_success("Check erfolgreich")
return True
```
Dann in `validate_all()` hinzufügen:
```python
if not self.validate_custom_check():
all_valid = False
```
## Anforderungen
- Python 3.6+
- Keine zusätzlichen Packages erforderlich (nur Standard-Library)
- Optionale sudo-Rechte für Dateirechte-Korrektur
## Integration in Workflow
Das Script kann in automatisierte Workflows integriert werden:
**Lösung:**
```bash
# In CI/CD Pipeline
python3 custom/scripts/validate_and_rebuild.py || exit 1
# Service-Klasse erstellen
cat > custom/Espo/Custom/Services/{Entity}.php << 'EOF'
<?php
namespace Espo\Custom\Services;
use Espo\Services\Record;
class {Entity} extends Record {}
EOF
# Als Git Pre-Commit Hook
#!/bin/bash
python3 custom/scripts/validate_and_rebuild.py --dry-run
```
## Troubleshooting
### Script findet rebuild.php nicht
```bash
# Stelle sicher, dass du im EspoCRM-Root bist
cd /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
# Rebuild
python3 custom/scripts/validate_and_rebuild.py
```
### Dateirechte können nicht korrigiert werden
```bash
# Manuell mit sudo korrigieren
sudo chown -R www-data:www-data custom/
sudo find custom/ -type f -exec chmod 664 {} \;
sudo find custom/ -type d -exec chmod 775 {} \;
### 2. API-Tests schlagen fehl (401 Unauthorized)
**Symptom:**
```
Ergebnis: 0 erfolgreich, 18 fehlgeschlagen
```
### Python3 nicht verfügbar
**Lösung:**
```bash
# Ubuntu/Debian
sudo apt-get install python3
# Korrigiere Credentials
python3 custom/scripts/validate_and_rebuild.py --username admin --password correct-password
# CentOS/RHEL
sudo yum install python3
# Oder überspringe Tests
python3 custom/scripts/validate_and_rebuild.py --skip-tests
```
### 3. Relationship-Fehler
**Symptom:**
```
✗ EntityA.linkB → EntityB: Foreign link 'linkA' fehlt
```
**Lösung:**
Füge bidirektionalen Link in EntityB hinzu - siehe ESPOCRM_BEST_PRACTICES.md
## Workflow-Beispiele
### Development Workflow
```bash
# 1. Nach Code-Änderungen: Quick Check
python3 custom/scripts/validate_and_rebuild.py --dry-run
# 2. Wenn OK: Rebuild durchführen
python3 custom/scripts/validate_and_rebuild.py --skip-tests
# 3. Vor Git-Commit: Vollständiger Test
python3 custom/scripts/validate_and_rebuild.py -v
```
### CI/CD Integration
```yaml
# .github/workflows/espocrm-validate.yml
- name: Validate EspoCRM
run: python3 custom/scripts/validate_and_rebuild.py --dry-run
- name: Run Entity Tests
run: |
python3 custom/scripts/validate_and_rebuild.py \
--base-url http://localhost \
--username ci-user \
--password ${{ secrets.ESPOCRM_PASSWORD }}
```
### Pre-Commit Hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
python3 custom/scripts/validate_and_rebuild.py --dry-run
if [ $? -ne 0 ]; then
echo "Validation failed! Fix errors before committing."
exit 1
fi
```
## Siehe auch
- [README.md](../../README.md) - Hauptdokumentation
- [CUSTOM_DIRECTORY.md](../CUSTOM_DIRECTORY.md) - Custom-Verzeichnis-Struktur
- [workflow_manager.php](workflow_manager.php) - Workflow-Management-Tool
- [ESPOCRM_BEST_PRACTICES.md](../ESPOCRM_BEST_PRACTICES.md) - Vollständige Best Practices
- [CHANGELOG_2026-03-10.md](../CHANGELOG_2026-03-10.md) - Letzte Änderungen
- [E2E_TESTS_README.md](E2E_TESTS_README.md) - E2E Tests (deprecated, integriert in validator)
## Version History
**v2.0 (10. März 2026):**
- ✅ Log-Prüfung mit präzisen Zeitstempeln
- ✅ CRUD-Tests für alle Entities
- ✅ Minimaler/Verbose Output-Modus
- ✅ KI-freundliches JSON-Feedback
- ✅ Service-Klassen-Fehler-Detektion
**v1.0 (9. März 2026):**
- ✅ Initiale Version mit statischer Validierung
- ✅ JSON, PHP, Relationship-Checks
- ✅ Automatische Dateirechte-Korrektur