Files

bsiggel 2e9db78c6e Refactor code structure for improved readability and maintainability

2026-03-09 23:07:05 +01:00

9.1 KiB

Raw Blame History

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:

Schnellübersicht - Projekt-Statistiken auf einen Blick
README.md - Vollständige Projektdokumentation
Entitäten-Analyse - Alle Custom Entities mit Feldern und Beziehungen
Beziehungsgraph - Wie Entitäten miteinander verbunden sind
Custom Code - PHP Klassen, JavaScript, CSS
Workflows - Aktive und inaktive Workflows
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:

ki_project_overview.py → Informationen sammeln, Kontext für KI bereitstellen
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

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

Für Menschen

Ausgabe in Datei speichern: Für spätere Referenz
Abschnitte einzeln betrachten: Ausgabe ist strukturiert und scrollbar
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

9.1 KiB Raw Blame History