335 lines
9.1 KiB
Markdown
335 lines
9.1 KiB
Markdown
# 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
|