espocrm/custom/scripts/KI_OVERVIEW_README.md

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

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

Ausgabe in Datei speichern

# 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

# 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

# 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

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:

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:

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