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

```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
   - 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:**
```bash
# 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:**
```bash
# 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

```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

- [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