espocrm/custom/docs/tools/VALIDATOR_README.md

EspoCRM Validator & Rebuild Tool v2.0

Letzte Aktualisierung: 10. März 2026
Tool: custom/scripts/validate_and_rebuild.py

Übersicht

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.

🆕 Neue Features in v2.0

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

# 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

# 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
   • 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 bei M2M
   • Erkennt fehlende Gegenseiten-Definitionen

3. Erforderliche Dateien

   • Prüft Vorhandensein von scopes-Dateien
   • Validiert i18n-Dateien (de_DE + en_US)
   • Warnt bei fehlenden Translations

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. PHP-Syntax-Validierung

   • Validiert alle Custom-PHP-Klassen
   • Nutzt php -l für Syntax-Check

Phase 2: Rebuild mit Log-Prüfung

6. Cache-Clearing

   • Löscht EspoCRM-Cache vor Rebuild

7. EspoCRM Rebuild

   • Führt php command.php rebuild aus
   • Prüft Logs direkt nach Rebuild
   • Bricht ab bei Fehlern in Logs

Phase 3: Live Entity-Tests (optional)

Für jede Custom Entity (außer Junction Tables):

8. CREATE Test

   • Erstellt Test-Record via API
   • Prüft Logs nach Request
   • Validiert Response

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/Tests fehlgeschlagen

Fehlertypen

Kritische Fehler (Rebuild-Abbruch)

• JSON-Syntax-Fehler
• PHP-Syntax-Fehler
• Fehlende Relationship-Definitionen
• Rebuild-Fehler
• Log-Fehler nach Rebuild

Warnungen (kein Abbruch)

• Fehlende i18n-Übersetzungen
• Fehlende scopes-Dateien
• Dateirechte-Probleme (werden auto-korrigiert)

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:

CRITICAL: InjectableFactory: Class 'Espo\Custom\Services\{Entity}' does not exist

Lösung:

# 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

# Rebuild
python3 custom/scripts/validate_and_rebuild.py

2. API-Tests schlagen fehl (401 Unauthorized)

Symptom:

Ergebnis: 0 erfolgreich, 18 fehlgeschlagen

Lösung:

# Korrigiere Credentials
python3 custom/scripts/validate_and_rebuild.py --username admin --password correct-password

# 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

# 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

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

#!/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

• ESPOCRM_BEST_PRACTICES.md - Vollständige Best Practices
• CHANGELOG_2026-03-10.md - Letzte Änderungen
• 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