bsiggel/espocrm

Fork 0

Files

bsiggel c2766ec66a Update documentation for EspoCRM Best Practices and Validator Tool

2026-03-10 12:46:14 +01:00

9.5 KiB

Raw Permalink Blame History

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

JSON-Syntax-Prüfung
- Validiert alle .json Dateien im custom/ Verzeichnis
- Findet Syntax-Fehler mit Dateiname und Zeilennummer
Relationship-Konsistenz
- Prüft bidirektionale Relationships (hasMany/hasOne)
- Validiert foreign-Links zwischen Entities
- Überprüft relationName-Konsistenz bei M2M
- Erkennt fehlende Gegenseiten-Definitionen
Erforderliche Dateien
- Prüft Vorhandensein von scopes-Dateien
- Validiert i18n-Dateien (de_DE + en_US)
- Warnt bei fehlenden Translations
Dateirechte
- Prüft Owner (www-data:www-data) in:
  - custom/Espo/Custom/Resources/
  - client/custom/
  - data/ (inkl. config.php)
- Korrigiert automatisch (664/775)
PHP-Syntax-Validierung
- Validiert alle Custom-PHP-Klassen
- Nutzt php -l für Syntax-Check

Phase 2: Rebuild mit Log-Prüfung

Cache-Clearing
- Löscht EspoCRM-Cache vor Rebuild
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):

CREATE Test
- Erstellt Test-Record via API
- Prüft Logs nach Request
- Validiert Response
READ Test
- Liest erstellten Record
- Prüft Logs
- Validiert Daten
UPDATE Test
- Aktualisiert Record
- Prüft Logs
- Validiert Änderung
LIST Test
- Ruft Entity-Liste ab
- Prüft Logs
- Validiert Response
DELETE Test
- Löscht Test-Record
- Prüft Logs
- Entfernt aus Cleanup-Liste
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

9.5 KiB Raw Permalink Blame History Unescape Escape

EspoCRM Validator & Rebuild Tool v2.0

Übersicht

🆕 Neue Features in v2.0

1. Intelligenter Output-Modus

2. Log-Prüfung mit präzisen Zeitstempeln

3. CRUD-Tests für alle Entities

4. KI-freundliches JSON-Feedback

Verwendung

Basis-Befehle

Erweiterte Parameter

Validierungsphasen

Phase 1: Statische Validierung

Phase 2: Rebuild mit Log-Prüfung

Phase 3: Live Entity-Tests (optional)

Output-Beispiele

Standard-Modus (Minimal)

Verbose-Modus (-v)

Bei Fehlern (mit Log-Analyse)

Exit Codes

Fehlertypen

Kritische Fehler (Rebuild-Abbruch)

Warnungen (kein Abbruch)

Test-Fehler (kein Abbruch bei --skip-tests)

Häufige Fehler und Lösungen

1. InjectableFactory: Service-Klasse fehlt

2. API-Tests schlagen fehl (401 Unauthorized)

3. Relationship-Fehler

Workflow-Beispiele

Development Workflow

CI/CD Integration

Pre-Commit Hook

Siehe auch

Version History

9.5 KiB

Raw Permalink Blame History

Verbose-Modus (`-v`)