bsiggel/espocrm

Fork 0

Files

bsiggel 63e3841f86 Update documentation: Add Hook development section and Custom Entities overview

2026-03-09 23:12:30 +01:00

9.5 KiB

Raw Blame History

📚 EspoCRM Dokumentations-Index

Schneller Zugriff auf alle Dokumentations-Ressourcen

🎯 Quick Links für AI Agents

START HIER ⭐

docs/ESPOCRM_BEST_PRACTICES.md - Vollständiges Entwickler-Handbuch
docs/README.md - Dokumentations-Navigation & Workflow-Guide
python3 custom/scripts/ki_project_overview.py - Aktueller Projekt-Status für AI

Essentials

docs/tools/QUICKSTART.md - 5-Minuten Quick Start
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 ⭐

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)
✅ Hook-Entwicklung (Entity Lifecycle Events)
✅ Workflow-Management
✅ Testing & Validierung
✅ Fehlerbehandlung & Troubleshooting
✅ Deployment-Prozess

Wann verwenden:

Neuen AI Agent briefen
Entity erstellen
Relationship implementieren
API-Endpoint entwickeln
Hook für Validierung/Berechnung erstellen
Fehler debuggen

2️⃣ Spezial-Themen

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

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

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

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

5-Minuten Quick Start

python3 custom/scripts/validate_and_rebuild.py

docs/tools/VALIDATION_TOOLS.md

Validierungs-Tools Details

PHP-CLI (php -l)
CSSLint
JSHint
Integration

docs/tools/E2E_TESTS_README.md

End-to-End Test Framework

CRUD-Tests
Relationship-Tests
Konfiguration

docs/tools/KI_OVERVIEW_README.md

KI-Projekt-Übersicht Tool

python3 custom/scripts/ki_project_overview.py > /tmp/project-overview.txt

5️⃣ Workflow-Management

docs/workflows/README.md

Workflow-Format & Management

Befehle:

# 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

# 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

# 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

# 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

# 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

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

Fehlerlog-Analyse:

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

Troubleshooting Guide:

cat custom/docs/ESPOCRM_BEST_PRACTICES.md | grep -A 300 "Troubleshooting"

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

9.5 KiB Raw Blame History Unescape Escape

📚 EspoCRM Dokumentations-Index

🎯 Quick Links für AI Agents

START HIER ⭐

Essentials

📁 Dokumentations-Struktur

📖 Dokumentations-Kategorien

1️⃣ Entwickler-Handbuch

docs/ESPOCRM_BEST_PRACTICES.md ⭐

2️⃣ Spezial-Themen

3️⃣ Architektur & Struktur

4️⃣ Tool-Dokumentation

5️⃣ Workflow-Management

🛠️ Wichtigste Tools

🎓 Typische Workflows

1. Neuen AI Agent briefen

2. Neue Entity entwickeln

3. Relationship implementieren

4. Junction Table mit additionalColumns

5. Fehler debuggen

🆘 Support & Hilfe

Bei Problemen:

📊 System-Info

🔄 Reorganisation (9. März 2026)

9.5 KiB

Raw Blame History