bsiggel/espocrm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0340c59e5c9c05990edf5198a83d8123ea5de579
espocrm/custom/docs
History

README.md

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

🎓 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

📊 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

Reference in New Issue View Git Blame Copy Permalink