320 lines
8.4 KiB
Markdown
320 lines
8.4 KiB
Markdown
# 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`
|