# KI-Einstiegsscript für EspoCRM Projekt

## Übersicht

Das `ki_project_overview.py` Script bietet einen vollständigen, automatisch generierten Überblick über das EspoCRM-Projekt. Es ist speziell für KI-basierte Programmierung konzipiert und gibt alle relevanten Informationen aus, die für die Entwicklung benötigt werden.

## Zweck

**Ziel:** Die KI erhält einen aktuellen, umfassenden Informationsstand über das Projekt, ohne manuell verschiedene Dateien durchsuchen zu müssen.

Das Script analysiert automatisch:
- ✅ Alle Custom Entitäten und ihre Felder
- ✅ Beziehungen zwischen Entitäten (Relationship-Graph)
- ✅ Custom PHP Klassen (Formula-Funktionen, Services, etc.)
- ✅ Workflows und deren Status
- ✅ Frontend-Anpassungen (JavaScript, CSS)
- ✅ Custom Layouts
- ✅ Internationalisierung (i18n)
- ✅ README.md Dokumentation

## Verwendung

### Einfach ausführen

```bash
# Im EspoCRM Root-Verzeichnis
python3 custom/scripts/ki_project_overview.py
```

### Ausgabe in Datei speichern

```bash
# Für detaillierte Analyse später
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
```

### Ausgabe an KI übergeben

Das Script ist so konzipiert, dass die Ausgabe direkt an eine KI übergeben werden kann. Die KI erhält damit:

1. **Schnellübersicht** - Projekt-Statistiken auf einen Blick
2. **README.md** - Vollständige Projektdokumentation
3. **Entitäten-Analyse** - Alle Custom Entities mit Feldern und Beziehungen
4. **Beziehungsgraph** - Wie Entitäten miteinander verbunden sind
5. **Custom Code** - PHP Klassen, JavaScript, CSS
6. **Workflows** - Aktive und inaktive Workflows
7. **Internationalisierung** - Unterstützte Sprachen

## Ausgabeformat

Das Script gibt strukturierte, lesbare Ausgaben mit verschiedenen Abschnitten:

```
================================================================================
                                SCHNELLÜBERSICHT                                
================================================================================

📊 Projekt-Statistiken:

   • Entities                21
   • PHP Classes              1
   • Workflows                1
   • JavaScript Files        10
   ...

================================================================================
                                ENTITÄTEN ANALYSE                               
================================================================================

────────────────────────────────────────────────────────────────────────────────
► Entität: CMietobjekt
────────────────────────────────────────────────────────────────────────────────

📋 Scope:
   • entity: CMietobjekt
   • acl: True
   • stream: False
   ...

🔧 Felder (15):
   • name: varchar [REQUIRED] [CUSTOM]
   • adresse: link → CAdressen
   • miete: currency (€)
   ...

🔗 Beziehungen (8):
   • mietverhltnisse [hasMany] → CVmhMietverhltnis.mietobjekt
   • kontakte [hasMany] → Contact.mietobjekte
   ...

⚡ Formula Scripts:
   • beforeSaveApiScript: 25 Zeilen
```

## Was wird analysiert?

### 1. Entitäten (entityDefs)

Für jede Custom Entity:
- Alle Felder mit Typ, Optionen, Constraints
- Alle Beziehungen (Links) zu anderen Entities
- Formula Scripts (beforeSave, afterSave, etc.)
- Scope-Konfiguration (ACL, Stream, Portal-Access)

### 2. Beziehungsgraph

Visualisiert alle Beziehungen zwischen Entities:
- hasMany, belongsTo, hasOne, manyToMany
- Bidirektionale Links mit relationName
- Foreign Keys

### 3. Custom PHP Klassen

Alle PHP-Dateien in `custom/Espo/Custom/Classes/`:
- FormulaFunctions
- Services
- Controllers
- Hooks
- Etc.

### 4. Workflows

Alle Workflows in `custom/workflows/`:
- Name und Status (aktiv/inaktiv)
- Trigger-Typ
- Entity-Zuordnung
- Anzahl der Aktionen

### 5. Frontend

- **JavaScript:** Alle Custom Views und Module
- **CSS:** Registrierte Stylesheets
- **App Config:** cssList, scriptList aus client.json

### 6. Layouts

Custom Layouts für jede Entity:
- detail, list, detailSmall, listSmall
- bottomPanelsDetail, sidePanelsDetail
- Etc.

### 7. Internationalisierung

- Unterstützte Sprachen
- Anzahl Übersetzungsdateien pro Sprache
- Geschätzte Anzahl Labels

## Typische Anwendungsfälle

### Fall 1: Neue Programmieraufgabe
```bash
# KI erhält vollständigen Projekt-Kontext
python3 custom/scripts/ki_project_overview.py
```

Die KI kann dann direkt auf Basis der Ausgabe arbeiten, ohne weitere Dateien lesen zu müssen.

### Fall 2: Beziehungen verstehen
Das Script zeigt automatisch alle Beziehungen zwischen Entities und hilft, Abhängigkeiten zu verstehen.

### Fall 3: Vollständigkeitsprüfung
Schnell erkennen, ob alle erwarteten Entities, Felder und Beziehungen vorhanden sind.

## Integration mit validate_and_rebuild.py

Das KI-Einstiegsscript ist als Ergänzung zum `validate_and_rebuild.py` Script konzipiert:

1. **ki_project_overview.py** → Informationen sammeln, Kontext für KI bereitstellen
2. **validate_and_rebuild.py** → Änderungen validieren und anwenden

### Typischer Workflow

```bash
# 1. Projekt-Übersicht für KI
python3 custom/scripts/ki_project_overview.py

# 2. KI macht Änderungen an JSON-Dateien
# (Basierend auf der Übersicht)

# 3. Validieren und Rebuild
python3 custom/scripts/validate_and_rebuild.py
```

## Technische Details

### Dateisystem-Struktur

Das Script erwartet folgende Struktur:
```
/var/lib/docker/volumes/vmh-espocrm_espocrm/_data/
├── README.md
├── custom/
│   ├── Espo/
│   │   └── Custom/
│   │       ├── Classes/
│   │       └── Resources/
│   │           ├── metadata/
│   │           │   ├── entityDefs/
│   │           │   ├── scopes/
│   │           │   ├── formula/
│   │           │   ├── layouts/
│   │           │   └── ...
│   │           └── i18n/
│   ├── scripts/
│   └── workflows/
└── client/
    └── custom/
        ├── src/
        └── css/
```

### Performance

- Analysiert ~20 Entities in <1 Sekunde
- JSON-Parsing mit Error-Handling
- Effiziente Rekursion durch Dateisystem

### Error-Handling

- Fehlerhafte JSON-Dateien werden übersprungen mit Fehlermeldung
- Fehlende Verzeichnisse führen zu Info-Meldungen, nicht zu Abbruch
- Robuste Exception-Behandlung

## Ausgabe-Sektionen im Detail

### 1. SCHNELLÜBERSICHT
Kompakte Statistiken für schnellen Überblick

### 2. README.md
Vollständiger Inhalt der Projektdokumentation

### 3. ENTITÄTEN ANALYSE
Detaillierte Analyse jeder Custom Entity:
- Scope (ACL, Stream, Portal, etc.)
- Felder (Typ, Constraints, Optionen)
- Beziehungen (Links zu anderen Entities)
- Formula Scripts

### 4. BEZIEHUNGSGRAPH
Visualisierung aller Entity-Beziehungen

### 5. CUSTOM LAYOUTS
Übersicht über angepasste Layouts

### 6. CUSTOM PHP KLASSEN
Alle PHP-Dateien gruppiert nach Typ

### 7. WORKFLOWS
Status und Konfiguration aller Workflows

### 8. FRONTEND ANPASSUNGEN
JavaScript, CSS und App-Konfiguration

### 9. INTERNATIONALISIERUNG
Unterstützte Sprachen und Labels

## Erweiterungen

Das Script kann leicht erweitert werden:

### Neue Analyse-Funktion hinzufügen

```python
def analyze_new_feature():
    """Analysiert neues Feature."""
    print_section("NEUES FEATURE", "=")
    
    # Implementierung
    ...

# In main() Funktion aufrufen
def main():
    ...
    analyze_new_feature()
    ...
```

### Ausgabeformat ändern

Die Ausgabe kann angepasst werden:
- JSON-Format für maschinelle Verarbeitung
- Markdown für Dokumentation
- HTML für Browser-Darstellung

## Best Practices

### Für KI-Integration

1. **Vollständige Ausgabe verwenden:** Nicht abschneiden, KI braucht alle Details
2. **Regelmäßig aktualisieren:** Bei Projekt-Änderungen erneut ausführen
3. **Mit README.md kombinieren:** Script gibt automatisch README aus

### Für Menschen

1. **Ausgabe in Datei speichern:** Für spätere Referenz
2. **Abschnitte einzeln betrachten:** Ausgabe ist strukturiert und scrollbar
3. **Mit grep filtern:** `python3 ... | grep "Entity:"`

## Troubleshooting

### Problem: Script findet keine Entities

**Lösung:** Prüfe, ob `BASE_PATH` korrekt gesetzt ist:
```python
BASE_PATH = Path("/var/lib/docker/volumes/vmh-espocrm_espocrm/_data")
```

### Problem: JSON Parse-Fehler

**Lösung:** Script gibt Fehler aus, aber läuft weiter. Prüfe betroffene Datei mit:
```bash
python3 -m json.tool < file.json
```

### Problem: Keine README.md Ausgabe

**Lösung:** Prüfe ob `README.md` im Root-Verzeichnis existiert

## Siehe auch

- `/custom/CUSTOM_DIRECTORY.md` - Detaillierte Verzeichnisstruktur
- `custom/scripts/validate_and_rebuild.py` - Validierung und Rebuild
- `custom/scripts/VALIDATOR_README.md` - Validator-Dokumentation
- `README.md` - Hauptdokumentation

## Lizenz

Teil des EspoCRM Custom Directory, gleiches Lizenzmodell wie Hauptprojekt.

---

**Erstellt:** Januar 2026  
**Autor:** Automatische KI-Integration  
**Version:** 1.0