espocrm/custom/scripts/VALIDATOR_README.md

EspoCRM Validator & Rebuild Tool

Ü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.

Features

✅ Automatische Validierungen

1. JSON-Syntax-Prüfung

   • Validiert alle .json Dateien im custom/ Verzeichnis
   • Findet Syntax-Fehler mit Dateiname und Zeilennummer

2. Relationship-Konsistenz

   • Prüft bidirektionale Relationships (hasMany/hasOne)
   • Validiert foreign-Links zwischen Entities
   • Überprüft relationName-Konsistenz
   • Erkennt fehlende Gegenseiten-Definitionen

3. Formula-Script Platzierung

   • Prüft ob Formula-Scripts in /formula/ statt /entityDefs/ liegen
   • Warnt vor leeren Formula-Definitionen

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

5. Layout-Struktur

   • Validiert clientDefs und bottomPanels
   • Findet unnötige false-Elemente

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)

7. CSS-Validierung

   • Validiert Syntax aller CSS-Dateien
   • Prüft Klammer-Balance und grundlegende Struktur

8. JavaScript-Validierung

   • Prüft Syntax aller JS-Dateien in client/custom/src/

9. PHP-Validierung

   • Validiert PHP-Syntax aller Custom-Klassen

10. Rebuild-Ausführung

    • Führt rebuild.php nur aus, wenn keine kritischen Fehler vorliegen

Verwendung

Direkt ausführen

cd /path/to/espocrm
python3 custom/scripts/validate_and_rebuild.py

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

Fehlertypen

Kritische Fehler (Rebuild-Abbruch)

• JSON-Syntax-Fehler
• Fehlende Relationship-Definitionen
• Falsch platzierte Formula-Scripts

Warnungen (kein Abbruch)

• Fehlende i18n-Übersetzungen
• Layout-Strukturprobleme
• Dateirechte-Probleme

Beispiel-Output

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!

Erweiterung

Das Script ist modular aufgebaut. Neue Validierungen können einfach hinzugefügt werden:

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:

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:

# In CI/CD Pipeline
python3 custom/scripts/validate_and_rebuild.py || exit 1

# Als Git Pre-Commit Hook
#!/bin/bash
python3 custom/scripts/validate_and_rebuild.py --dry-run

Troubleshooting

Script findet rebuild.php nicht

# Stelle sicher, dass du im EspoCRM-Root bist
cd /var/lib/docker/volumes/vmh-espocrm_espocrm/_data
python3 custom/scripts/validate_and_rebuild.py

Dateirechte können nicht korrigiert werden

# 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 {} \;

Python3 nicht verfügbar

# Ubuntu/Debian
sudo apt-get install python3

# CentOS/RHEL
sudo yum install python3

Siehe auch

• README.md - Hauptdokumentation
• CUSTOM_DIRECTORY.md - Custom-Verzeichnis-Struktur
• workflow_manager.php - Workflow-Management-Tool