Refactor code structure for improved readability and maintainability
This commit is contained in:
359
custom/DOCUMENTATION_INDEX.md
Normal file
359
custom/DOCUMENTATION_INDEX.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# 📚 EspoCRM Dokumentations-Index
|
||||
|
||||
**Schneller Zugriff auf alle Dokumentations-Ressourcen**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quick Links für AI Agents
|
||||
|
||||
### START HIER ⭐
|
||||
1. **[docs/ESPOCRM_BEST_PRACTICES.md](docs/ESPOCRM_BEST_PRACTICES.md)** - Vollständiges Entwickler-Handbuch
|
||||
2. **[docs/README.md](docs/README.md)** - Dokumentations-Navigation & Workflow-Guide
|
||||
3. `python3 custom/scripts/ki_project_overview.py` - Aktueller Projekt-Status für AI
|
||||
|
||||
### Essentials
|
||||
- **[docs/tools/QUICKSTART.md](docs/tools/QUICKSTART.md)** - 5-Minuten Quick Start
|
||||
- **[custom/scripts/validate_and_rebuild.py](custom/scripts/validate_and_rebuild.py)** - Haupt-Validierungs-Tool
|
||||
- **Validierung ausführen:** `python3 custom/scripts/validate_and_rebuild.py`
|
||||
|
||||
---
|
||||
|
||||
## 📁 Dokumentations-Struktur
|
||||
|
||||
```
|
||||
custom/
|
||||
├── README.md ← Custom Actions Blueprint (Architektur)
|
||||
├── CUSTOM_DIRECTORY.md ← Verzeichnisstruktur-Übersicht
|
||||
│
|
||||
├── docs/ ← 🆕 ZENTRALE DOKUMENTATION
|
||||
│ ├── README.md ← Dokumentations-Navigation (START)
|
||||
│ ├── ESPOCRM_BEST_PRACTICES.md ← ⭐ HAUPTDOKUMENTATION
|
||||
│ ├── TESTERGEBNISSE_JUNCTION_TABLE.md ← Junction Table Guide
|
||||
│ ├── ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md ← Puls-System Spezifikation
|
||||
│ │
|
||||
│ ├── tools/ ← Tool-Dokumentation
|
||||
│ │ ├── QUICKSTART.md
|
||||
│ │ ├── VALIDATION_TOOLS.md
|
||||
│ │ ├── E2E_TESTS_README.md
|
||||
│ │ ├── KI_OVERVIEW_README.md
|
||||
│ │ └── VALIDATOR_README.md
|
||||
│ │
|
||||
│ └── workflows/ ← Workflow-Dokumentation
|
||||
│ └── README.md
|
||||
│
|
||||
├── scripts/ ← Entwicklungs-Tools
|
||||
│ ├── validate_and_rebuild.py ← Haupt-Validierungs-Tool
|
||||
│ ├── e2e_tests.py ← End-to-End Tests
|
||||
│ ├── ki_project_overview.py ← Projekt-Analyse für AI
|
||||
│ ├── espocrm_api_client.py ← API Client Library
|
||||
│ ├── ki-overview.sh ← Legacy Overview Script
|
||||
│ ├── run_e2e_tests.sh ← E2E Test Runner
|
||||
│ └── junctiontabletests/ ← Junction Table Tests
|
||||
│
|
||||
└── workflows/ ← Workflow JSON-Definitionen
|
||||
└── README.md ← Workflow-Befehle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Dokumentations-Kategorien
|
||||
|
||||
### 1️⃣ Entwickler-Handbuch
|
||||
|
||||
#### [docs/ESPOCRM_BEST_PRACTICES.md](docs/ESPOCRM_BEST_PRACTICES.md) ⭐
|
||||
**Das Hauptdokument - Start hier!**
|
||||
|
||||
**Inhalt:**
|
||||
- ✅ Projekt-Übersicht & System-Architektur
|
||||
- ✅ Architektur-Prinzipien (Clean Code, 3-Schichten)
|
||||
- ✅ Entity-Entwicklung (Templates, Naming, i18n)
|
||||
- ✅ Relationship-Patterns (One-to-Many, Many-to-Many, Junction)
|
||||
- ✅ API-Entwicklung (REST, Custom Endpoints)
|
||||
- ✅ Workflow-Management
|
||||
- ✅ Testing & Validierung
|
||||
- ✅ Fehlerbehandlung & Troubleshooting
|
||||
- ✅ Deployment-Prozess
|
||||
|
||||
**Wann verwenden:**
|
||||
- Neuen AI Agent briefen
|
||||
- Entity erstellen
|
||||
- Relationship implementieren
|
||||
- API-Endpoint entwickeln
|
||||
- Fehler debuggen
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Spezial-Themen
|
||||
|
||||
#### [docs/TESTERGEBNISSE_JUNCTION_TABLE.md](docs/TESTERGEBNISSE_JUNCTION_TABLE.md)
|
||||
**Junction Tables mit additionalColumns**
|
||||
|
||||
**Inhalt:**
|
||||
- Many-to-Many Relationships mit Zusatzfeldern
|
||||
- Junction Entity als API-Endpoint
|
||||
- API-CRUD Operationen
|
||||
- Vollständige Code-Beispiele
|
||||
- ⚠️ UI-Panel Warnung (405 Fehler)
|
||||
|
||||
**Wann verwenden:**
|
||||
- Many-to-Many mit Zusatzfeldern implementieren
|
||||
- Junction Entity API nutzen
|
||||
- additionalColumns verstehen
|
||||
|
||||
---
|
||||
|
||||
#### [docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md](docs/ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md)
|
||||
**Puls-System (CPuls) Spezifikation**
|
||||
|
||||
**Inhalt:**
|
||||
- Posteingangs-System mit KI-Analyse
|
||||
- Team-basierte Dokumenten-Workflows
|
||||
- First-Read-Closes Prinzip
|
||||
- Entity-Definitionen CPuls, CPulsTeamZuordnung
|
||||
- Middleware-Architektur
|
||||
|
||||
**Wann verwenden:**
|
||||
- CPuls-Entity weiterentwickeln
|
||||
- Dokumenten-Workflow verstehen
|
||||
- KI-Integration planen
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Architektur & Struktur
|
||||
|
||||
#### [README.md](README.md)
|
||||
**Custom Actions - Implementierungsprinzip**
|
||||
|
||||
**Inhalt:**
|
||||
- Drei-Schichten-Architektur
|
||||
- Custom Button Actions Blueprint
|
||||
- Entity-Erstellung mit Relationen
|
||||
- Code-Templates
|
||||
- Sicherheit & ACL
|
||||
|
||||
**Wann verwenden:**
|
||||
- Custom Button Action erstellen
|
||||
- Controller/Service Pattern verstehen
|
||||
- Architektur-Overview benötigen
|
||||
|
||||
---
|
||||
|
||||
#### [CUSTOM_DIRECTORY.md](CUSTOM_DIRECTORY.md)
|
||||
**Verzeichnisstruktur-Übersicht**
|
||||
|
||||
**Inhalt:**
|
||||
- Vollständige custom/ Struktur
|
||||
- Backend (Espo/Custom/)
|
||||
- Frontend (client/custom/)
|
||||
- Metadata-Organisation
|
||||
- Scripts & Workflows
|
||||
|
||||
**Wann verwenden:**
|
||||
- Datei-Platzierung nachschlagen
|
||||
- Verzeichnis-Organisation verstehen
|
||||
- Neue Dateien korrekt anlegen
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Tool-Dokumentation
|
||||
|
||||
#### [docs/tools/QUICKSTART.md](docs/tools/QUICKSTART.md)
|
||||
**5-Minuten Quick Start**
|
||||
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [docs/tools/VALIDATION_TOOLS.md](docs/tools/VALIDATION_TOOLS.md)
|
||||
**Validierungs-Tools Details**
|
||||
- PHP-CLI (php -l)
|
||||
- CSSLint
|
||||
- JSHint
|
||||
- Integration
|
||||
|
||||
---
|
||||
|
||||
#### [docs/tools/E2E_TESTS_README.md](docs/tools/E2E_TESTS_README.md)
|
||||
**End-to-End Test Framework**
|
||||
- CRUD-Tests
|
||||
- Relationship-Tests
|
||||
- Konfiguration
|
||||
|
||||
---
|
||||
|
||||
#### [docs/tools/KI_OVERVIEW_README.md](docs/tools/KI_OVERVIEW_README.md)
|
||||
**KI-Projekt-Übersicht Tool**
|
||||
|
||||
```bash
|
||||
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Workflow-Management
|
||||
|
||||
#### [docs/workflows/README.md](docs/workflows/README.md)
|
||||
**Workflow-Format & Management**
|
||||
|
||||
**Befehle:**
|
||||
```bash
|
||||
# Liste
|
||||
php custom/scripts/workflow_manager.php list
|
||||
|
||||
# Import
|
||||
php custom/scripts/workflow_manager.php import custom/workflows/my-workflow.json
|
||||
|
||||
# Export
|
||||
php custom/scripts/workflow_manager.php export
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Wichtigste Tools
|
||||
|
||||
| Tool | Zweck | Befehl |
|
||||
|------|-------|--------|
|
||||
| **validate_and_rebuild.py** | 🎯 Validierung + Rebuild + E2E + Fehlerlog | `python3 custom/scripts/validate_and_rebuild.py` |
|
||||
| **ki_project_overview.py** | 📊 Projekt-Analyse für AI | `python3 custom/scripts/ki_project_overview.py` |
|
||||
| **e2e_tests.py** | 🧪 End-to-End CRUD Tests | `python3 custom/scripts/e2e_tests.py` |
|
||||
|
||||
**NEU in validate_and_rebuild.py:**
|
||||
- ✅ Automatische Fehlerlog-Analyse bei Rebuild-Fehlern
|
||||
- ✅ Zeigt letzte 50 Log-Zeilen
|
||||
- ✅ Filtert ERROR/WARNING/EXCEPTION
|
||||
- ✅ Gibt Log-File-Pfad aus
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Typische Workflows
|
||||
|
||||
### 1. Neuen AI Agent briefen
|
||||
|
||||
```bash
|
||||
# 1. Hauptdokumentation lesen
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md
|
||||
|
||||
# 2. Aktuellen Projekt-Status holen
|
||||
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
|
||||
|
||||
# 3. Dokumentations-Navigation
|
||||
cat custom/docs/README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Neue Entity entwickeln
|
||||
|
||||
```bash
|
||||
# 1. Template nachschlagen
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 50 "Entity Definition Template"
|
||||
|
||||
# 2. Entity-Dateien erstellen (entityDefs, scopes, i18n)
|
||||
|
||||
# 3. Validierung + Rebuild
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Relationship implementieren
|
||||
|
||||
```bash
|
||||
# 1. Pattern nachschlagen
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 100 "Relationship-Patterns"
|
||||
|
||||
# 2. Links konfigurieren
|
||||
|
||||
# 3. Validierung (prüft bidirektionale Konsistenz)
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Junction Table mit additionalColumns
|
||||
|
||||
```bash
|
||||
# 1. Vollständige Anleitung
|
||||
cat custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md
|
||||
|
||||
# 2. Implementierung (Entity + Controller + Service)
|
||||
|
||||
# 3. Validierung
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Fehler debuggen
|
||||
|
||||
```bash
|
||||
# 1. Validierung ausführen (zeigt automatisch Fehlerlog)
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
|
||||
# 2. Troubleshooting Guide
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Support & Hilfe
|
||||
|
||||
### Bei Problemen:
|
||||
|
||||
1. **Fehlerlog-Analyse:**
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
# → Zeigt automatisch Fehlerlog bei Rebuild-Fehlern
|
||||
```
|
||||
|
||||
2. **Troubleshooting Guide:**
|
||||
```bash
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 300 "Troubleshooting"
|
||||
```
|
||||
|
||||
3. **Häufige Fehler:**
|
||||
- Layout `false` → `{}` ändern
|
||||
- i18n fehlt → beide Sprachen (de_DE + en_US) anlegen
|
||||
- Relationship kaputt → bidirektional prüfen (foreign)
|
||||
- ACL 403 → Rechte in Admin UI setzen
|
||||
- 405 Fehler → Keine additionalColumns in UI-Panels!
|
||||
|
||||
---
|
||||
|
||||
## 📊 System-Info
|
||||
|
||||
- **EspoCRM Version:** 9.3.2
|
||||
- **PHP Version:** 8.2.30
|
||||
- **Database:** MariaDB 12.2.2
|
||||
- **Docker Container:** espocrm, espocrm-db
|
||||
- **Workspace:** `/var/lib/docker/volumes/vmh-espocrm_espocrm/_data`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Reorganisation (9. März 2026)
|
||||
|
||||
**Änderungen:**
|
||||
- ✅ Alle Dokumentation zentralisiert in `custom/docs/`
|
||||
- ✅ Tool-Dokumentation in `custom/docs/tools/`
|
||||
- ✅ Workflow-Dokumentation in `custom/docs/workflows/`
|
||||
- ✅ Neue Hauptdokumentation: `ESPOCRM_BEST_PRACTICES.md`
|
||||
- ✅ Test-Scripts organisiert in `custom/scripts/junctiontabletests/`
|
||||
- ✅ validate_and_rebuild.py erweitert um automatische Fehlerlog-Ausgabe
|
||||
|
||||
**Migration:**
|
||||
- `scripts/KI_OVERVIEW_README.md` → `docs/tools/`
|
||||
- `scripts/VALIDATION_TOOLS.md` → `docs/tools/`
|
||||
- `scripts/E2E_TESTS_README.md` → `docs/tools/`
|
||||
- `scripts/QUICKSTART.md` → `docs/tools/`
|
||||
- `scripts/VALIDATOR_README.md` → `docs/tools/`
|
||||
- `workflows/README.md` → `docs/workflows/`
|
||||
- `TESTERGEBNISSE_JUNCTION_TABLE.md` → `docs/`
|
||||
- `ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md` → `docs/`
|
||||
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** 9. März 2026
|
||||
|
||||
**Für Fragen:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|
||||
1087
custom/docs/ESPOCRM_BEST_PRACTICES.md
Normal file
1087
custom/docs/ESPOCRM_BEST_PRACTICES.md
Normal file
File diff suppressed because it is too large
Load Diff
319
custom/docs/README.md
Normal file
319
custom/docs/README.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# EspoCRM Custom Development - Dokumentation
|
||||
|
||||
**Zentrale Dokumentation für EspoCRM-Entwicklung mit KI-Support**
|
||||
|
||||
---
|
||||
|
||||
## 📂 Struktur
|
||||
|
||||
```
|
||||
custom/docs/
|
||||
├── README.md # Diese Datei
|
||||
├── ESPOCRM_BEST_PRACTICES.md # ⭐ HAUPTDOKUMENTATION
|
||||
├── TESTERGEBNISSE_JUNCTION_TABLE.md # Junction Table Implementation
|
||||
├── ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md # Puls-System Spezifikation
|
||||
├── tools/ # Tool-Dokumentation
|
||||
│ ├── QUICKSTART.md # Quick Start Guide
|
||||
│ ├── VALIDATION_TOOLS.md # Validierungs-Tools
|
||||
│ ├── E2E_TESTS_README.md # End-to-End Tests
|
||||
│ ├── KI_OVERVIEW_README.md # KI-Projekt-Übersicht
|
||||
│ └── VALIDATOR_README.md # Validator Details
|
||||
└── workflows/ # Workflow-Dokumentation
|
||||
└── README.md # Workflow-Format & Import/Export
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Für AI Code Agents - HIER STARTEN!
|
||||
|
||||
### 1. Lies zuerst: ESPOCRM_BEST_PRACTICES.md
|
||||
|
||||
**Das Hauptdokument enthält:**
|
||||
- ✅ Projekt-Übersicht & Architektur
|
||||
- ✅ Entity-Entwicklung (Naming, Templates, i18n)
|
||||
- ✅ Relationship-Patterns (One-to-Many, Many-to-Many, Junction Tables)
|
||||
- ✅ API-Entwicklung (REST Endpoints, Custom Actions)
|
||||
- ✅ Workflow-Management
|
||||
- ✅ Testing & Validierung
|
||||
- ✅ Fehlerbehandlung & Troubleshooting
|
||||
- ✅ Deployment-Prozess
|
||||
- ✅ Projekt-spezifische Entities
|
||||
|
||||
**Befehl:**
|
||||
```bash
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md
|
||||
```
|
||||
|
||||
### 2. Projekt-Analyse abrufen
|
||||
|
||||
**Für umfassenden aktuellen Projekt-Status:**
|
||||
```bash
|
||||
python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt
|
||||
cat /tmp/project-overview.txt
|
||||
```
|
||||
|
||||
**Output:** Alle Entities, Relationships, Custom Code, Workflows
|
||||
|
||||
### 3. Validierung & Rebuild ausführen
|
||||
|
||||
**Vor jeder Entwicklung:**
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
**Das Tool führt automatisch durch:**
|
||||
1. JSON-Syntax Check
|
||||
2. Relationship-Validierung
|
||||
3. i18n-Vollständigkeit
|
||||
4. Layout-Struktur
|
||||
5. Dateirechte
|
||||
6. CSS/JS/PHP Validierung
|
||||
7. EspoCRM Rebuild
|
||||
8. E2E-Tests
|
||||
9. **NEU:** Automatische Fehlerlog-Analyse bei Rebuild-Fehlern!
|
||||
|
||||
---
|
||||
|
||||
## 📖 Dokumentations-Guide
|
||||
|
||||
### Hauptdokumentation
|
||||
|
||||
#### ESPOCRM_BEST_PRACTICES.md
|
||||
**Vollständiges Entwickler-Handbuch**
|
||||
- Architektur-Prinzipien
|
||||
- Entity-Development mit Templates
|
||||
- Relationship-Patterns inkl. Junction Tables
|
||||
- API-Entwicklung (Controller, Service, REST)
|
||||
- Workflow-Management
|
||||
- Testing (Validierung, E2E)
|
||||
- Troubleshooting & Fehlerbehandlung
|
||||
|
||||
**Verwende diese Datei für:**
|
||||
- Neuen Code-Agent briefen
|
||||
- Entwicklungsstandards nachschlagen
|
||||
- Entity-Templates kopieren
|
||||
- Fehler debuggen
|
||||
|
||||
#### TESTERGEBNISSE_JUNCTION_TABLE.md
|
||||
**Junction Table Implementation Guide**
|
||||
- Many-to-Many mit additionalColumns
|
||||
- Junction Entity als API-Endpoint
|
||||
- Vollständige Code-Beispiele
|
||||
- API-Nutzung (CRUD, Filter, Sort)
|
||||
|
||||
**Verwende diese Datei für:**
|
||||
- Many-to-Many Beziehungen mit Zusatzfeldern
|
||||
- API-only Access Pattern
|
||||
- Junction Entity Implementation
|
||||
|
||||
#### ENTWICKLUNGSPLAN_ENTWICKLUNGEN.md
|
||||
**Puls-System (CPuls) Spezifikation**
|
||||
- Posteingangs-System mit KI-Analyse
|
||||
- Team-basierte Dokumenten-Workflows
|
||||
- First-Read-Closes Prinzip
|
||||
- Entity-Definitionen und Beziehungen
|
||||
|
||||
**Verwende diese Datei für:**
|
||||
- CPuls-Entity Weiterentwicklung
|
||||
- Dokumenten-Workflow-Logik
|
||||
- KI-Integration-Patterns
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Tool-Dokumentation
|
||||
|
||||
### tools/QUICKSTART.md
|
||||
**5-Minuten Quick Start für Validator**
|
||||
- Installation bereits fertig
|
||||
- Verwendung: `python3 custom/scripts/validate_and_rebuild.py`
|
||||
- Output-Interpretation
|
||||
|
||||
### tools/VALIDATION_TOOLS.md
|
||||
**Technische Details zu Validierungs-Tools**
|
||||
- PHP-CLI (php -l)
|
||||
- CSSLint (csslint)
|
||||
- JSHint (jshint)
|
||||
- Integration im Validator
|
||||
|
||||
### tools/E2E_TESTS_README.md
|
||||
**End-to-End Test Framework**
|
||||
- CRUD-Tests für Custom Entities
|
||||
- Relationship-Tests
|
||||
- Konfiguration & Ausführung
|
||||
|
||||
### tools/KI_OVERVIEW_README.md
|
||||
**KI-Projekt-Übersicht Tool**
|
||||
- Automatische Projekt-Analyse
|
||||
- Output-Format für AI Agents
|
||||
- Verwendung: `python3 custom/scripts/ki_project_overview.py`
|
||||
|
||||
### tools/VALIDATOR_README.md
|
||||
**Validator Details**
|
||||
- Alternative zu VALIDATION_TOOLS.md
|
||||
- Erweiterte Validator-Funktionalität
|
||||
|
||||
---
|
||||
|
||||
## 📋 Workflow-Dokumentation
|
||||
|
||||
### workflows/README.md
|
||||
**Workflow-Format & Management**
|
||||
- Simple Workflow JSON-Format
|
||||
- BPM Flowchart Format
|
||||
- Import/Export mit `workflow_manager.php`
|
||||
- Trigger Types, Actions, Conditions
|
||||
|
||||
**Befehle:**
|
||||
```bash
|
||||
# Workflows auflisten
|
||||
php custom/scripts/workflow_manager.php list
|
||||
|
||||
# Workflow importieren
|
||||
php custom/scripts/workflow_manager.php import custom/workflows/my-workflow.json
|
||||
|
||||
# Alle Workflows exportieren
|
||||
php custom/scripts/workflow_manager.php export
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Typische Workflows
|
||||
|
||||
### Neue Entity entwickeln
|
||||
|
||||
```bash
|
||||
# 1. Best Practices lesen
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 50 "Entity Definition Template"
|
||||
|
||||
# 2. Entity-Dateien erstellen (entityDefs, scopes, i18n de_DE + en_US)
|
||||
|
||||
# 3. Validierung + Rebuild
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
### Relationship implementieren
|
||||
|
||||
```bash
|
||||
# 1. Relationship-Pattern nachschlagen
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 100 "Relationship-Patterns"
|
||||
|
||||
# 2. Links in beiden Entities konfigurieren
|
||||
|
||||
# 3. Validierung (prüft bidirektionale Konsistenz)
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
### Junction Table mit additionalColumns
|
||||
|
||||
```bash
|
||||
# 1. Vollständige Anleitung lesen
|
||||
cat custom/docs/TESTERGEBNISSE_JUNCTION_TABLE.md
|
||||
|
||||
# 2. Entity-Definitionen + Junction Entity erstellen
|
||||
|
||||
# 3. Controller & Service für Junction Entity
|
||||
|
||||
# 4. Validierung + Test
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
```
|
||||
|
||||
### Fehler debuggen
|
||||
|
||||
```bash
|
||||
# 1. Validierung ausführen (zeigt automatisch Fehlerlog bei Rebuild-Fehler)
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
|
||||
# 2. Manuell Logs prüfen (falls nötig)
|
||||
tail -100 data/logs/espo-$(date +%Y-%m-%d).log | grep -i error
|
||||
|
||||
# 3. Troubleshooting Guide
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 200 "Troubleshooting"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Entwicklungs-Tools Übersicht
|
||||
|
||||
| Tool | Zweck | Befehl |
|
||||
|------|-------|--------|
|
||||
| **validate_and_rebuild.py** | Haupttool: Validierung + Rebuild + E2E | `python3 custom/scripts/validate_and_rebuild.py` |
|
||||
| **ki_project_overview.py** | Projekt-Analyse für AI | `python3 custom/scripts/ki_project_overview.py` |
|
||||
| **e2e_tests.py** | End-to-End CRUD Tests | `python3 custom/scripts/e2e_tests.py` |
|
||||
| **workflow_manager.php** | Workflow Import/Export | `php custom/scripts/workflow_manager.php list` |
|
||||
|
||||
**Alle Tools dokumentiert in:** `custom/docs/tools/`
|
||||
|
||||
---
|
||||
|
||||
## 📚 Weitere Ressourcen
|
||||
|
||||
### Projekt-spezifische Dokumente
|
||||
|
||||
- `../README.md` - Custom Actions Blueprint
|
||||
- `../CUSTOM_DIRECTORY.md` - Verzeichnisstruktur-Übersicht
|
||||
|
||||
### EspoCRM Offizielle Docs
|
||||
|
||||
- **Main Docs:** https://docs.espocrm.com/
|
||||
- **API Reference:** https://docs.espocrm.com/development/api/
|
||||
- **Formula Functions:** https://docs.espocrm.com/administration/formula/
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Best Practices Zusammenfassung
|
||||
|
||||
### DO ✅
|
||||
|
||||
- **IMMER beide Sprachen:** de_DE + en_US (en_US ist Fallback!)
|
||||
- **Bidirektionale Relationships:** `foreign` muss zurück zeigen
|
||||
- **Validierung vor Rebuild:** Nutze `validate_and_rebuild.py`
|
||||
- **Sprechende Namen:** `C{EntityName}` für Custom Entities
|
||||
- **Clean Code:** Kleine Funktionen, Type Hints, Kommentare
|
||||
- **Layouts mit {}:** EspoCRM 7.x+ erfordert `{}` statt `false`
|
||||
|
||||
### DON'T ❌
|
||||
|
||||
- **Keine fehlende i18n:** immer de_DE UND en_US
|
||||
- **Keine unidirektionalen Links:** immer foreign konfigurieren
|
||||
- **Keine komplexe Logik in Hooks:** nutze Services
|
||||
- **Keine direkten SQL-Queries:** nutze EntityManager
|
||||
- **Keine hard-coded Werte:** nutze Config
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Support & Troubleshooting
|
||||
|
||||
### Bei Problemen:
|
||||
|
||||
1. **Fehlerlog-Analyse:**
|
||||
```bash
|
||||
python3 custom/scripts/validate_and_rebuild.py
|
||||
# → Zeigt automatisch Fehler bei Rebuild-Fehlern
|
||||
```
|
||||
|
||||
2. **Troubleshooting Guide:**
|
||||
```bash
|
||||
cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 300 "Troubleshooting"
|
||||
```
|
||||
|
||||
3. **Häufige Fehler:**
|
||||
- Layout `false` → `{}` ändern
|
||||
- i18n fehlt → beide Sprachen anlegen
|
||||
- Relationship kaputt → bidirektional prüfen
|
||||
- ACL 403 → Rechte in Admin UI
|
||||
|
||||
---
|
||||
|
||||
## 📊 System-Info
|
||||
|
||||
- **EspoCRM Version:** 9.3.2
|
||||
- **PHP Version:** 8.2.30
|
||||
- **Database:** MariaDB 12.2.2
|
||||
- **Docker Container:** espocrm, espocrm-db
|
||||
- **Workspace:** `/var/lib/docker/volumes/vmh-espocrm_espocrm/_data`
|
||||
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** 9. März 2026
|
||||
|
||||
**Für Fragen oder Updates:** Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|
||||
@@ -266,9 +266,21 @@ response = requests.put(
|
||||
| CREATE via API | ✅ | POST mit allen Feldern |
|
||||
| UPDATE via API | ✅ | PUT zum Ändern von syncId |
|
||||
| DELETE via API | ✅ | Standard-DELETE |
|
||||
| View-Darstellung | ✅* | Möglich, aber manuell konfigurieren |
|
||||
| View-Darstellung | ❌ | Nicht empfohlen - verursacht 405 Fehler |
|
||||
|
||||
*) Benötigt manuelle Layout-Konfiguration im Entity Manager
|
||||
## ⚠️ UI-Panel Warnung
|
||||
|
||||
**WICHTIG:** additionalColumns sollten NICHT in Standard-Relationship-Panels angezeigt werden!
|
||||
|
||||
**Problem:**
|
||||
- Standard relationship panels versuchen inline-editing
|
||||
- Dies führt zu 405 Method Not Allowed Fehlern
|
||||
- additionalColumns sind nicht kompatibel mit Standard-Panel-Architektur
|
||||
|
||||
**Empfehlung:**
|
||||
- ✅ Nutze API-only Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ❌ NICHT in CDokumente detail view als relationship panel anzeigen
|
||||
|
||||
## 🎯 Fazit
|
||||
|
||||
@@ -280,6 +292,18 @@ Die **Junction-Tabelle mit `additionalColumns` ist vollständig via REST-API nut
|
||||
- ✅ CRUD-Operationen vollständig unterstützt
|
||||
- ✅ `syncId` ist direkt in der Response
|
||||
- ✅ Einfache Integration in externe Systeme
|
||||
- ✅ API-only Pattern verhindert 405-Fehler
|
||||
|
||||
**Einschränkungen:**
|
||||
- ⚠️ UI-Darstellung in Standard-Relationship-Panels verursacht 405 Fehler
|
||||
- ⚠️ additionalColumns nur über Junction-Entity-API zugänglich
|
||||
- ⚠️ Standard relationship endpoints (z.B. GET /api/v1/CDokumente/{id}/cAICollections) geben additionalColumns NICHT zurück
|
||||
|
||||
**Best Practice:**
|
||||
1. ✅ Junction Entity als API-Endpoint nutzen (`/api/v1/CAICollectionCDokumente`)
|
||||
2. ✅ Keine UI-Panels für Junction-Relationships mit additionalColumns
|
||||
3. ✅ API-Integration für externe Systeme (Middleware, KI, etc.)
|
||||
4. ✅ Bei Bedarf: Separate Management-UI für Junction Entity (ohne Relationship-Panel)
|
||||
|
||||
**Wichtig:**
|
||||
1. Controller und Service erstellen
|
||||
@@ -287,6 +311,7 @@ Die **Junction-Tabelle mit `additionalColumns` ist vollständig via REST-API nut
|
||||
3. Entity-Definition mit korrekten Feldtypen
|
||||
4. ACL-Rechte für die Junction-Entity setzen
|
||||
5. Cache löschen und rebuild
|
||||
6. **NICHT** als Relationship-Panel in UI anzeigen (→ 405 Fehler)
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
@@ -367,12 +392,27 @@ Die `syncId` kann in der Datenbank gespeichert werden:
|
||||
- ✅ Daten werden korrekt persistiert
|
||||
|
||||
### 4. View-Darstellung
|
||||
**Status: TECHNISCH MÖGLICH**
|
||||
**Status: ⚠️ NICHT EMPFOHLEN (API-ONLY PATTERN)**
|
||||
|
||||
Die Beziehung kann im EspoCRM-Frontend dargestellt werden durch:
|
||||
- Anzeige in Relationship-Panels
|
||||
- Konfiguration über Entity Manager → Relationships
|
||||
- Anpassung der Layouts für die Anzeige von `syncId` als Spalte
|
||||
**Problem:** Standard EspoCRM Relationship-Panels versuchen inline-editing von Feldern. Bei additionalColumns führt dies zu **405 Method Not Allowed** Fehlern, da die Standard-Panel-UI nicht mit dem Junction-Entity-Pattern kompatibel ist.
|
||||
|
||||
**Versucht & Fehlgeschlagen:**
|
||||
1. ❌ Direct display of syncId in relationship panel layout → 405 Fehler
|
||||
2. ❌ Custom View mit actionEditLinkData → Blank views, dann weiter 405 Fehler
|
||||
3. ❌ Simplified relationship layout ohne syncId → 405 Fehler blieben bestehen
|
||||
|
||||
**ROOT CAUSE:** Standard relationship panels senden HTTP-Requests die nicht mit Junction-Entity-Architektur übereinstimmen. additionalColumns erfordern spezielle Behandlung die nicht durch Standard-UI bereitgestellt wird.
|
||||
|
||||
**LÖSUNG:** API-ONLY Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ✅ Kein UI-Panel in CDokumente → keine 405 Fehler
|
||||
- ✅ Alle Funktionen über REST API verfügbar
|
||||
- ✅ Perfekt für externe Systeme und Middleware
|
||||
|
||||
**Falls UI Display gewünscht:**
|
||||
- Option: Custom Panel das direkt die Junction Entity list-view lädt (gefiltert nach documentId)
|
||||
- Option: Separate Tab/Page für Junction Entity-Management
|
||||
- Nicht empfohlen: Standard relationship panel mit additionalColumns
|
||||
|
||||
## ❌ Was NICHT funktioniert
|
||||
|
||||
72
custom/docs/workflows/README.md
Normal file
72
custom/docs/workflows/README.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Workflow Definitions
|
||||
|
||||
This directory contains workflow definitions in JSON format that can be imported into EspoCRM using the workflow manager script.
|
||||
|
||||
## File Format
|
||||
|
||||
### Simple Workflow
|
||||
```json
|
||||
{
|
||||
"type": "simple",
|
||||
"name": "workflow-name",
|
||||
"entity_type": "EntityName",
|
||||
"trigger_type": "afterRecordSaved",
|
||||
"is_active": true,
|
||||
"description": "Description of what this workflow does",
|
||||
"category": "Category Name",
|
||||
"conditions_all": [],
|
||||
"conditions_any": [],
|
||||
"conditions_formula": null,
|
||||
"actions": []
|
||||
}
|
||||
```
|
||||
|
||||
**Trigger Types:**
|
||||
- `afterRecordSaved` - After record is created or updated
|
||||
- `afterRecordCreated` - Only after record is created
|
||||
- `scheduled` - Runs on a schedule
|
||||
- `manual` - Manually triggered
|
||||
|
||||
**Condition Types:**
|
||||
- `equals`, `notEquals`, `greaterThan`, `lessThan`, `contains`, `notContains`, `isEmpty`, `isNotEmpty`, `isTrue`, `isFalse`, `wasEqual`, `wasNotEqual`, `changed`, `notChanged`
|
||||
|
||||
**Action Types:**
|
||||
- `sendEmail` - Send email to recipient
|
||||
- `createEntity` - Create a new record
|
||||
- `updateEntity` - Update current record
|
||||
- `relateTo` - Link to another record
|
||||
- `unrelateFrom` - Unlink from record
|
||||
- `applyAssignmentRule` - Apply assignment rules
|
||||
- `createNotification` - Create notification
|
||||
|
||||
### BPM Flowchart
|
||||
```json
|
||||
{
|
||||
"type": "bpm",
|
||||
"name": "flowchart-name",
|
||||
"target_type": "EntityName",
|
||||
"is_active": true,
|
||||
"description": "Description",
|
||||
"data": {
|
||||
"list": []
|
||||
},
|
||||
"elements_data_hash": {},
|
||||
"event_start_all_id_list": []
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Import a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php import /var/www/html/custom/workflows/your-workflow.json
|
||||
```
|
||||
|
||||
Export a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php export <workflow-id> /var/www/html/custom/workflows/exported.json
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
- `vmh-erstberatung-abschliessen.json` - Sends email and sets status when consultation is completed
|
||||
BIN
custom/scripts/__pycache__/validate_and_rebuild.cpython-311.pyc
Normal file
BIN
custom/scripts/__pycache__/validate_and_rebuild.cpython-311.pyc
Normal file
Binary file not shown.
@@ -739,6 +739,81 @@ class EntityValidator:
|
||||
print_success(f"Alle {len(php_files)} PHP-Dateien sind syntaktisch korrekt")
|
||||
return True
|
||||
|
||||
def show_error_logs(self):
|
||||
"""Zeige die letzten Fehlerlog-Einträge aus data/logs/."""
|
||||
from datetime import datetime
|
||||
|
||||
print_header("FEHLERLOG ANALYSE")
|
||||
|
||||
logs_path = self.base_path / "data" / "logs"
|
||||
if not logs_path.exists():
|
||||
print_warning("Logs-Verzeichnis nicht gefunden")
|
||||
return
|
||||
|
||||
# Finde das neueste Log-File
|
||||
today = datetime.now().strftime("%Y-%m-%d")
|
||||
log_file = logs_path / f"espo-{today}.log"
|
||||
|
||||
if not log_file.exists():
|
||||
# Fallback: Finde das neueste Log-File
|
||||
log_files = sorted(logs_path.glob("espo-*.log"), key=lambda f: f.stat().st_mtime, reverse=True)
|
||||
if log_files:
|
||||
log_file = log_files[0]
|
||||
print_info(f"Kein Log für heute gefunden, verwende: {log_file.name}")
|
||||
else:
|
||||
print_warning("Keine Log-Dateien gefunden")
|
||||
return
|
||||
|
||||
print_info(f"Analysiere: {log_file.name}")
|
||||
|
||||
try:
|
||||
with open(log_file, 'r', encoding='utf-8') as f:
|
||||
lines = f.readlines()
|
||||
|
||||
if not lines:
|
||||
print_info("Log-Datei ist leer")
|
||||
return
|
||||
|
||||
# Zeige die letzten 50 Zeilen
|
||||
last_lines = lines[-50:]
|
||||
|
||||
# Filter für Fehler und Warnungen
|
||||
errors = []
|
||||
warnings = []
|
||||
|
||||
for line in last_lines:
|
||||
line_upper = line.upper()
|
||||
if 'ERROR' in line_upper or 'FATAL' in line_upper or 'EXCEPTION' in line_upper:
|
||||
errors.append(line.strip())
|
||||
elif 'WARNING' in line_upper or 'WARN' in line_upper:
|
||||
warnings.append(line.strip())
|
||||
|
||||
if errors:
|
||||
print_error(f"\n{len(errors)} Fehler in den letzten 50 Log-Zeilen gefunden:\n")
|
||||
for i, error in enumerate(errors[-10:], 1): # Zeige max. 10 Fehler
|
||||
print(f"{Colors.RED}{i}.{Colors.END} {error}")
|
||||
if len(errors) > 10:
|
||||
print(f"\n{Colors.YELLOW}... und {len(errors) - 10} weitere Fehler{Colors.END}")
|
||||
|
||||
if warnings:
|
||||
print_warning(f"\n{len(warnings)} Warnungen in den letzten 50 Log-Zeilen gefunden:\n")
|
||||
for i, warning in enumerate(warnings[-5:], 1): # Zeige max. 5 Warnungen
|
||||
print(f"{Colors.YELLOW}{i}.{Colors.END} {warning}")
|
||||
if len(warnings) > 5:
|
||||
print(f"\n{Colors.YELLOW}... und {len(warnings) - 5} weitere Warnungen{Colors.END}")
|
||||
|
||||
if not errors and not warnings:
|
||||
print_info("Keine Fehler oder Warnungen in den letzten 50 Log-Zeilen gefunden")
|
||||
print_info("\nLetzte 10 Log-Zeilen:")
|
||||
for line in last_lines[-10:]:
|
||||
print(f" {line.strip()}")
|
||||
|
||||
print(f"\n{Colors.BLUE}ℹ{Colors.END} Vollständige Log-Datei: {log_file}")
|
||||
print(f"{Colors.BLUE}ℹ{Colors.END} Zum Anzeigen: tail -50 {log_file}")
|
||||
|
||||
except Exception as e:
|
||||
print_error(f"Fehler beim Lesen der Log-Datei: {e}")
|
||||
|
||||
def run_rebuild(self) -> bool:
|
||||
"""Führe den EspoCRM Rebuild aus."""
|
||||
print_header("10. ESPOCRM REBUILD")
|
||||
@@ -811,6 +886,9 @@ class EntityValidator:
|
||||
print_error("Rebuild fehlgeschlagen:")
|
||||
if result.stderr:
|
||||
print(f"\n{result.stderr}")
|
||||
|
||||
# Zeige automatisch die letzten Fehlerlog-Einträge an
|
||||
self.show_error_logs()
|
||||
return False
|
||||
else:
|
||||
print_warning("Kein EspoCRM Docker-Container gefunden")
|
||||
@@ -862,6 +940,9 @@ class EntityValidator:
|
||||
print_error("Rebuild fehlgeschlagen:")
|
||||
if result.stderr:
|
||||
print(f"\n{result.stderr}")
|
||||
|
||||
# Zeige automatisch die letzten Fehlerlog-Einträge an
|
||||
self.show_error_logs()
|
||||
return False
|
||||
except subprocess.TimeoutExpired:
|
||||
print_error("Rebuild-Timeout (>60 Sekunden)")
|
||||
|
||||
@@ -1,72 +1,39 @@
|
||||
# Workflow Definitions
|
||||
# Workflow Documentation
|
||||
|
||||
This directory contains workflow definitions in JSON format that can be imported into EspoCRM using the workflow manager script.
|
||||
Dokumentation für EspoCRM Workflow-Management.
|
||||
|
||||
## File Format
|
||||
## Workflow-Format & Management
|
||||
|
||||
### Simple Workflow
|
||||
```json
|
||||
{
|
||||
"type": "simple",
|
||||
"name": "workflow-name",
|
||||
"entity_type": "EntityName",
|
||||
"trigger_type": "afterRecordSaved",
|
||||
"is_active": true,
|
||||
"description": "Description of what this workflow does",
|
||||
"category": "Category Name",
|
||||
"conditions_all": [],
|
||||
"conditions_any": [],
|
||||
"conditions_formula": null,
|
||||
"actions": []
|
||||
}
|
||||
```
|
||||
Siehe: `custom/docs/workflows/README.md` für vollständige Workflow-Dokumentation inkl.:
|
||||
- Simple Workflow JSON-Format
|
||||
- BPM Flowchart Format
|
||||
- Trigger Types (afterRecordSaved, afterRecordCreated, scheduled, manual)
|
||||
- Action Types (sendEmail, createEntity, updateEntity, etc.)
|
||||
- Condition Types
|
||||
- Import/Export mit workflow_manager.php
|
||||
|
||||
**Trigger Types:**
|
||||
- `afterRecordSaved` - After record is created or updated
|
||||
- `afterRecordCreated` - Only after record is created
|
||||
- `scheduled` - Runs on a schedule
|
||||
- `manual` - Manually triggered
|
||||
## Workflow-Befehle
|
||||
|
||||
**Condition Types:**
|
||||
- `equals`, `notEquals`, `greaterThan`, `lessThan`, `contains`, `notContains`, `isEmpty`, `isNotEmpty`, `isTrue`, `isFalse`, `wasEqual`, `wasNotEqual`, `changed`, `notChanged`
|
||||
|
||||
**Action Types:**
|
||||
- `sendEmail` - Send email to recipient
|
||||
- `createEntity` - Create a new record
|
||||
- `updateEntity` - Update current record
|
||||
- `relateTo` - Link to another record
|
||||
- `unrelateFrom` - Unlink from record
|
||||
- `applyAssignmentRule` - Apply assignment rules
|
||||
- `createNotification` - Create notification
|
||||
|
||||
### BPM Flowchart
|
||||
```json
|
||||
{
|
||||
"type": "bpm",
|
||||
"name": "flowchart-name",
|
||||
"target_type": "EntityName",
|
||||
"is_active": true,
|
||||
"description": "Description",
|
||||
"data": {
|
||||
"list": []
|
||||
},
|
||||
"elements_data_hash": {},
|
||||
"event_start_all_id_list": []
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Import a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php import /var/www/html/custom/workflows/your-workflow.json
|
||||
# Alle Workflows auflisten
|
||||
php custom/scripts/workflow_manager.php list
|
||||
|
||||
# Workflow importieren
|
||||
php custom/scripts/workflow_manager.php import custom/workflows/my-workflow.json
|
||||
|
||||
# Alle Workflows exportieren
|
||||
php custom/scripts/workflow_manager.php export
|
||||
|
||||
# Workflow löschen
|
||||
php custom/scripts/workflow_manager.php delete workflow-name
|
||||
```
|
||||
|
||||
Export a workflow:
|
||||
```bash
|
||||
docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php export <workflow-id> /var/www/html/custom/workflows/exported.json
|
||||
```
|
||||
## Workflow-Dateien
|
||||
|
||||
## Examples
|
||||
Workflow-Definitionen werden als JSON-Dateien in diesem Verzeichnis gespeichert und können mit dem workflow_manager.php Tool importiert werden.
|
||||
|
||||
- `vmh-erstberatung-abschliessen.json` - Sends email and sets status when consultation is completed
|
||||
**Datei-Naming:** `{workflow-name}.json` (Kleinbuchstaben, Bindestriche)
|
||||
|
||||
---
|
||||
|
||||
Für Details siehe: **custom/docs/workflows/README.md**
|
||||
|
||||
Reference in New Issue
Block a user