espocrm/custom/docs

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:

cat custom/docs/ESPOCRM_BEST_PRACTICES.md

2. Projekt-Analyse abrufen

Für umfassenden aktuellen Projekt-Status:

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:

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:

# 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

# 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

# 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

# 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

# 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:

   python3 custom/scripts/validate_and_rebuild.py
   # → Zeigt automatisch Fehler bei Rebuild-Fehlern
   

2. Troubleshooting Guide:

   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
   • Rebuild schlägt fehl mit "Column does not exist" → Index auf gelöschtes Feld prüfen

---

🆕 Neueste Patterns & Best Practices (März 2026)

Junction Table UI-Integration

Pattern: columnAttributeMap + notStorable Felder

Use Case: Junction-Spalten (wie hnr, syncstatus, lastSync) im Relationship-Panel anzeigen.

Implementierung:

• notStorable Felder als UI-Placeholder
• columnAttributeMap für bidirektionales Mapping
• Custom List Layouts für Relationship-Panels
• Hooks für automatische Updates

Dokumentiert in: ESPOCRM_BEST_PRACTICES.md & TESTERGEBNISSE_JUNCTION_TABLE.md

Dokumenten-Propagierung mit Loop-Schutz

Pattern: AfterRelate/AfterUnrelate Hooks mit statischem Processing-Array

Use Case: Automatische Verknüpfung von Dokumenten zwischen hierarchisch verbundenen Entities.

Hierarchie-Beispiel:

Räumungsklage ←→ AdvowareAkten ←→ AIKnowledge
Mietinkasso   ←→ AdvowareAkten ←→ AIKnowledge
        ↓             ↓              ↓
           Dokumente (automatisch synchronisiert)

Loop-Schutz: Statisches Array mit Key {EntityID}-{DokumentID}-{Aktion} verhindert Endlos-Rekursion.

Implementiert in: custom/Espo/Custom/Hooks/{CVmhRumungsklage,CMietinkasso,CAdvowareAkten,CAIKnowledge}/Propagate*.php

Dokumentiert in: ESPOCRM_BEST_PRACTICES.md - Hook-Entwicklung

Sync-Status-Management

Pattern: Globaler + Junction-level Status mit automatischer Propagierung

Struktur:

• Global (Parent): syncStatus (synced/unclean), lastSync
• Junction (pro Dokument): syncstatus (new/unclean/synced/failed), lastSync

Hooks:

• BeforeSave: Berechnet globalen Status aus allen Junction-Einträgen
• AfterRelate: Setzt Junction-Status auf "new"
• AfterSave (CDokumente): Markiert alle Junction-Einträge als "unclean" bei Dokumentänderung

Real-World: CAdvowareAkten & CAIKnowledge tracken Sync-Status ihrer verknüpften Dokumente.

---

📊 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: 11. März 2026
Version: 2.3 (Junction Table UI-Integration, Dokumenten-Propagierung, Sync-Status-Management)

Für Fragen oder Updates: Siehe custom/docs/ESPOCRM_BEST_PRACTICES.md