7.9 KiB
7.9 KiB
Dokumentations-Update: Hook-Entwicklung & Entity-Übersicht
Datum: 9. März 2026
Version: ESPOCRM_BEST_PRACTICES.md 2.0 → 2.1
Durchgeführt von: EspoCRM Docs Maintainer Agent
Zusammenfassung
Umfassende Überarbeitung der Dokumentation mit Fokus auf:
- Hook-Entwicklung - Neuer Haupt-Abschnitt
- Entity-Übersicht - Vollständige Liste aller Custom Entities
- Bekannte Probleme - i18n-Warnungen dokumentiert
Änderungen im Detail
1. Neuer Abschnitt: Hook-Entwicklung
Datei: custom/docs/ESPOCRM_BEST_PRACTICES.md
Umfang: ~600 Zeilen neue Dokumentation
Inhalt:
Überblick & Patterns
- ✅ Hook-Typen-Übersicht (BeforeSave, AfterSave, BeforeRemove, etc.)
- ✅ Moderne Interface-basierte Hooks (EspoCRM 9.x)
- ✅ Legacy Hook-Pattern (EspoCRM < 7.0)
- ✅ Dependency Injection mit Constructor
- ✅ Verfügbare Services (EntityManager, Config, Language, etc.)
Praxis-Beispiele aus dem Projekt
Beispiel 1: CBankverbindungen/BankdatenValidation.php
- IBAN-Validierung mit Modulo-97-Algorithmus
- BIC-Format-Prüfung (8 oder 11 Zeichen)
- Normalisierung (Großbuchstaben, Leerzeichen entfernen)
- i18n für Fehlermeldungen
- BadRequest Exception-Handling
Beispiel 2: CDokumente/CDokumente.php
- Automatische MD5/SHA256-Hash-Berechnung
- File-Upload-Erkennung
- Status-Management (new/changed/synced)
- API-Limitationen dokumentiert
Beispiel 3: CPuls/UpdateTeamStats.php
- Moderne Interface-basierte Implementation (BeforeSave)
- Construction Injection für EntityManager
- Statistik-Berechnung für verwandte Entities
- Performance-Optimierung mit Conditions
Best Practices
✅ DO:
- Interface-basierte Hooks (EspoCRM 9.x)
- Constructor Injection
- Validierung in beforeSave
- Exception-werfen bei Fehlern
- i18n für Fehlermeldungen
- Performance-Optimierung mit
isAttributeChanged()
❌ DON'T:
- Komplexe Business-Logic in Hooks
- Direkte SQL-Queries
- Externe API-Calls in beforeSave
- Circular Dependencies
- UI-Logic in Hooks
Debugging & Troubleshooting
- Log-Output-Patterns
- Cache-Clear & Rebuild-Workflow
- Circular Dependency Detection
- Hook-Reihenfolge (Lifecycle)
2. Custom Entities Übersicht
Datei: custom/docs/ESPOCRM_BEST_PRACTICES.md
Neu hinzugefügt:
Tabelle aller 19 Custom Entities
| Entity | Beschreibung | Hooks | Typ |
|---|---|---|---|
| CAdressen | Adressen-Verwaltung | - | Base |
| CAICollections | AI-Dokumenten-Sammlungen | - | Base |
| CAICollectionCDokumente | Junction: Collections ↔ Dokumente | - | Junction |
| CBankverbindungen | Bankdaten (IBAN/BIC) | ✅ Validierung | Base |
| CBeteiligte | Beteiligte Personen | - | Base |
| CCallQueues | Call-Warteschlangen | - | Base |
| CDokumente | Dokumenten-Management | ✅ Hash-Berechnung | Base |
| CKuendigung | Kündigungen | - | Base |
| CMietinkasso | Mietinkasso-Fälle | - | Base |
| CMietobjekt | Mietobjekte | - | Base |
| CPuls | Posteingangs-System | ✅ Statistik | Base |
| CPulsTeamZuordnung | Puls-Team-Zuordnungen | - | Base |
| CVMHBeteiligte | VMH-spezifische Beteiligte | - | Base |
| CVmhErstgespraech | Erstgespräche | - | Base |
| CVmhMietverhltnis | Mietverhältnisse | - | Base |
| CVmhRumungsklage | Räumungsklagen | - | Base |
| CVmhVermieter | Vermieter | - | Base |
Erweiterte Standard-Entities
- Contact, Call, User, Meeting, Email, Task
- PhoneNumber, Team, BpmnUserTask
Implementierte Hooks (Übersicht)
- CBankverbindungen/BankdatenValidation
- CDokumente/CDokumente
- CPuls/UpdateTeamStats
3. Bekannte i18n-Warnungen dokumentiert
Datei: custom/docs/ESPOCRM_BEST_PRACTICES.md
Neu im Troubleshooting-Abschnitt:
Dokumentierte Warnungen
⚠ CDokumente (en_US): Link 'cAICollections' fehlt in i18n
⚠ CAICollections (de_DE): Link 'meetings' fehlt in i18n
⚠ CAICollections (de_DE): Link 'cDokumente' fehlt in i18n
⚠ CAICollections (en_US): Link 'cDokumente' fehlt in i18n
Status: Funktional keine Auswirkung
Behebung: JSON-Snippets für alle 4 fehlenden i18n-Einträge bereitgestellt
4. Inhaltsverzeichnis aktualisiert
Dateien:
Änderungen:
- ✅ Neuer Punkt 6: "Hook-Entwicklung"
- ✅ Nummerierung angepasst (Workflow-Management: 6 → 7)
- ✅ Index aktualisiert mit Hook-Entwicklung
5. Architektur-Prinzipien erweitert
Datei: custom/docs/ESPOCRM_BEST_PRACTICES.md
Änderung:
DON'T:
- ❌ Keine komplexe Business-Logic in Hooks (nutze Services)
Vorher:
- ❌ Keine komplexe Logik in Hooks
Validierung
Ausgeführt
python3 custom/scripts/validate_and_rebuild.py --dry-run
Ergebnisse
✓ Alle 702 JSON-Dateien syntaktisch korrekt
✓ 45 Relationships geprüft - alle konsistent
✓ 7 Formula-Definitionen korrekt platziert
⚠ 4 unvollständige i18n-Definitionen (dokumentiert)
✓ 15 Layout-Dateien geprüft, keine Fehler
✓ Alle Dateirechte korrekt (www-data:www-data)
✓ Alle 2 CSS-Dateien syntaktisch korrekt
✓ Alle 11 JavaScript-Dateien syntaktisch korrekt
✓ Alle 348 PHP-Dateien syntaktisch korrekt
Status: ✅ Alle Validierungen erfolgreich
Statistiken
Dokumentationsgröße
- Zeilen: 1698 (vorher: ~1100)
- Zunahme: ~600 Zeilen (+54%)
- Abschnitte: 74 (## Überschriften)
Code-Beispiele
- Neue Hook-Beispiele: 3 vollständige Implementierungen
- Code-Blocks: ~20 neue PHP/JSON-Snippets
- Best-Practice-Regeln: 12 DO's, 5 DON'Ts
Für AI Agents
Neue Fähigkeiten nach diesem Update
Agents können jetzt:
- ✅ Hook-Code mit modernen Interfaces schreiben
- ✅ IBAN-Validierung mit Modulo-97 implementieren
- ✅ File-Upload-Hashes automatisch berechnen
- ✅ Statistik-Felder automatisch aktualisieren
- ✅ Dependency Injection korrekt nutzen
- ✅ Circular Dependencies vermeiden
- ✅ Alle 19 Custom Entities überblicken
- ✅ i18n-Warnungen verstehen und beheben
Verwendung
Neuer Agent briefen:
python3 custom/scripts/ki_project_overview.py > overview.txt
cat custom/docs/ESPOCRM_BEST_PRACTICES.md
Hook entwickeln:
- Lies Abschnitt "Hook-Entwicklung" (Zeile ~670-1270)
- Wähle passendes Beispiel (Validierung/Hash/Statistik)
- Implementiere mit modernem Interface-Pattern
- Teste mit validate_and_rebuild.py
Nächste Schritte (optional)
Optionale Verbesserungen
-
i18n-Warnungen beheben
- 4 fehlende Link-Labels hinzufügen
- JSON-Snippets sind bereitgestellt
-
Weitere Hooks dokumentieren
- Falls zukünftig neue Hooks hinzukommen
- AfterSave, BeforeRemove, AfterRelate Beispiele
-
Tool-Dokumentation erweitern
- validate_and_rebuild.py Features dokumentieren
- Hook-spezifische Validierungen hinzufügen
-
Testing erweitern
- Hook-spezifische Unit Tests
- Circular Dependency Detection Tests
Dateien geändert
- ✅
custom/docs/ESPOCRM_BEST_PRACTICES.md(Version 2.0 → 2.1) - ✅
custom/DOCUMENTATION_INDEX.md - ✅
custom/docs/CHANGELOG_2026-03-09.md(NEU)
Kein Code geändert - Nur Dokumentation!
Verifikation
Dokumentations-Links
Git Diff (falls verfügbar)
git diff custom/docs/ESPOCRM_BEST_PRACTICES.md
git diff custom/DOCUMENTATION_INDEX.md
Ende des Updates
Dokumentation ist nun vollständig auf dem neuesten Stand mit umfassender Hook-Entwicklung-Dokumentation und Entity-Übersicht.