feat: Add KI-Einstiegsscript for comprehensive project overview
- Introduced `ki_project_overview.py` for automated analysis of EspoCRM project structure, entities, relationships, custom PHP classes, workflows, frontend adjustments, and internationalization. - Created `ki-overview.sh` wrapper script for executing the Python script with various output options. - Updated `README.md` to include a quick start section for the new KI entry script. - Added detailed documentation in `KI_OVERVIEW_README.md` explaining the script's purpose, usage, and output format. - Summarized the new features and files in `KI_OVERVIEW_SUMMARY.md`. - Enhanced `.vscode/settings.json` to approve new scripts for execution.
This commit is contained in:
334
custom/scripts/KI_OVERVIEW_README.md
Normal file
334
custom/scripts/KI_OVERVIEW_README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user